Options How-To

How do I find out what a command line option does?

Look in src/main.c in the option_data array for the string to corresponds to the command line option; the entries are of the form:

{ "option", 'O', TYPE, "data", argtype },

For the processing of --some-nifty-option from the command line, you're searching for "some-nifty-option".

If TYPE is OPT_BOOLEAN or OPT_VALUE:

• Note the value of "data"'. Then look in src/init.c at the commands array for an entry that starts with the same data. These lines are of the form:

  { "data", &opt.variable, cmd_TYPE },

  The corresponding line will tell you what variable is set when that option is entered on the command line. Now use grep or some other search tool to find out where the variable is referenced.

  For example, the --accept option sets the value of opt.accepts, which is referenced in src/ftp.c and src/utils.c

If TYPE is anything else:

• Look to see how src/main.c handles that TYPE.

  For example, OPT_ _APPEND_OUTPUT sets the option named logfile and then sets the variable append_to_log to true. Searching for append_to_log shows that it is only used in src/main.c. Checking src/init.c (as described above) for the option "logfile" shows that it sets the value of opt.lfilename, which is referenced in src/mswindows.c, src/progress.c, and src/utils.c.

How do I add a new command line option?

The simplest approach is to find an existing option that is close to what you want to accomplish and mirror it. You will need to edit the necessary source files as follows:

src/main.c

• Add a line to the option_data array in the following format:

  { "option", 'O', TYPE, "data", argtype },

  where:

  option	is the long name to be accepted from the command line
  O	is the short name (one character) to be accepted from the command or ' ' if there is no short name; the short name must only be assigned to one option. Note: There are very few short names available and the maintainers are not inclined to give them out unless the option is likely to be used frequently.
  TYPE	is one of the following standard options:
  	OPT_VALUE	option must be followed on the command line by a value that will be stored in an options variable (see src/init.c below)
  	OPT_BOOLEAN	option is a boolean value that may appear on the command line as --option for true or --no-option for false
  	OPT_FUNCALL	an internal function will be invoked if the option is selected on the command line
  	Note: If one of these choices won't work for your option you can add a new value to the enum list (of the form OPT_ _XXX) and add special code to handle it in src/main.c.
  data	For OPT_VALUE and OPT_BOOLEAN, the "name" assigned to the option in the commands array defined in src/init.c (see below). For OPT_FUNCALL, a pointer to the function to be invoked.
  argtype	For OPT_VALUE and OPT_BOOLEAN, use -1. For OPT_FUNCALL use no_argument.

  NOTE: The options must appear in alphabetical order because a boolean search is used for the list.

src/main.c

• Add the help string to function print_help as follows:

  N_("\
  -O,  --option            does something nifty.\n"),

  If the short name is ' ', put spaces in place of "-O,". Select a reasonable place to add the text into the help output in one of the existing groups of options:
  • Startup
  • Logging and input file
  • Download
  • Directories
  • HTTP options
  • HTTPS (SSL/TLS) options
  • FTP options
  • Recursive download
  • Recursive accept/reject.

src/options.h

• Define the variable to receive the value of the option in the options structure.

src/init.c

• Add a line to the commands array in the following format:

  { "data", &opt.variable, cmd_TYPE },

  where:

  data	matches the "data" string you entered above in the options_data array in src/main.c
  variable	the variable you defined in src/options.h
  cmd_TYPE	specifies how the command line data is to be processed for storage in the variable. Some of the more common ones appear in the following list (see src/init.c' for more). For the following cmd_TYPE choices, the variable will contain:
  	cmd_boolean	a value of 1 for true or 0 for false
  	cmd_number	a numeric value
  	cmd_string	a string value
  	cmd_file	a string value corresponding to a file
  	cmd_directory	a string value corresponding to a directory
  	cmd_time	a numeric value corresponding to seconds (the command line parser accepts things like 5m for 5 minutes and 1h for 1 hour)
  	cmd_vector	an array of string values

src/anything.c

• Modify the processing of wget to take into account the value of opt.variable