--- name: "ParseArgv" section: "3" platform: "linux" package: "minc-tools" version: "2.2.00-6" release: "Debian 8 (Jessie)" platforms: ["linux", "macos"] url: "https://new.carta.tech/ParseArgv/3" --- # ParseArgv(3) process command-line options ``` ``` ## NAME ParseArgv - process command-line options ## SYNOPSIS **#include \** int\ **ParseArgv**(*argcPtr, argv, argTable, flags*) ## ARGUMENTS - int *argcPtr* (in/out) Pointer to number of arguments in argv; gets modified to hold number of unprocessed arguments that remain after the call. - char *\*\*argv* (in/out) Command line arguments passed to main program. Modified to hold unprocessed arguments that remain after the call. - ArgvInfo *\*argTable* (in) Array of argument descriptors, terminated by element with type ARGV\_END. - int *flags* (in) If non-zero, then it specifies one or more flags that control the parsing of arguments. Different flags may be OR'ed together. The flags currently defined are ARGV\_DONT\_SKIP\_FIRST\_ARG, ARGV\_NO\_ABBREV, ARGV\_NO\_LEFTOVERS, ARGV\_NO\_DEFAULTS and ARGV\_NO\_PRINT. ``` ``` ## DESCRIPTION **ParseArgv** processes an array of command-line arguments according to a table describing the kinds of arguments that are expected. Each of the arguments in *argv* is processed in turn: if it matches one of the entries in *argTable*, the argument is processed according to that entry and discarded. The arguments that do not match anything in *argTable* are copied down to the beginning of *argv* (retaining their original order) and returned to the caller. At the end of the call **ParseArgv** sets *\*argcPtr* to hold the number of arguments that are left in *argv*, and *argv\[\*argcPtr\]* will hold the value NULL. Normally, **ParseArgv** assumes that *argv\[0\]* is a command name, so it is treated like an argument that doesn't match *argTable* and returned to the caller; however, if the ARGV\_DONT\_SKIP\_FIRST\_ARG bit is set in *flags* then *argv\[0\]* will be processed just like the other elements of *argv*. **ParseArgv** normally returns the value FALSE (0). If an error occurs while parsing the arguments, then TRUE (1) is returned and **ParseArgv** will print an error message on stderr. In the event of an error return, *\*argvPtr* will not have been modified, but *argv* could have been partially modified. The possible causes of errors are explained below. The *argTable* array specifies the kinds of arguments that are expected; each of its entries has the following structure: ``` typedef struct { char *key; int type; char *src; char *dst; char *help; } ArgvInfo; ``` The *key* field is a string such as \`\`-display'' or \`\`-bg'' that is compared with the values in *argv*. *Type* indicates how to process an argument that matches *key* (more on this below). *Src* and *dst* are additional values used in processing the argument. Their exact usage depends on *type*, but typically *src* indicates a value and *dst* indicates where to store the value. The **char \*** declarations for *src* and *dst* are placeholders: the actual types may be different. Lastly, *help* is a string giving a brief description of this option; this string is printed when users ask for help about command-line options. When processing an argument in *argv*, **ParseArgv** compares the argument to each of the *key*'s in *argTable*. **ParseArgv** selects the first specifier whose *key* matches the argument exactly, if such a specifier exists. Otherwise **ParseArgv** selects a specifier for which the argument is a unique abbreviation. If the argument is a unique abbreviation for more than one specifier, then an error is returned. If there is no matching entry in *argTable*, then the argument is skipped and returned to the caller. Once a matching argument specifier is found, **ParseArgv** processes the argument according to the *type* field of the specifier. The argument that matched *key* is called \`\`the matching argument'' in the descriptions below. As part of the processing, **ParseArgv** may also use the next argument in *argv* after the matching argument, which is called \`\`the following argument''. The legal values for *type*, and the processing that they cause, are as follows: - **ARGV\_END** Marks the end of the table. The last entry in *argTable* must have this type; all of its other fields are ignored and it will never match any arguments. - **ARGV\_CONSTANT** *Src* is treated as an integer and *dst* is treated as a pointer to an integer. *Src* is stored at *\*dst*. The matching argument is discarded. - **ARGV\_INT** The following argument must contain an integer string in the format accepted by **strtol** (e.g. \`\`0'' and \`\`0x'' prefixes may be used to specify octal or hexadecimal numbers, respectively). *Dst* is treated as a pointer to an integer; the following argument is converted to an integer value and stored at *\*dst*. *Src* is treated as an integer count: if its value is greater than 1, then that many arguments are processed and *Dst* is treated as an array pointer. The matching and following arguments are discarded from *argv*. - **ARGV\_FLOAT** The following argument must contain a floating-point number in the format accepted by **strtol**. *Dst* is treated as the address of an double-precision floating point value; the following argument is converted to a double-precision value and stored at *\*dst*. *Src* is treated as an integer count: if its value is greater than 1, then that many arguments are processed and *Dst* is treated as an array pointer. The matching and following arguments are discarded from *argv*. - **ARGV\_STRING** In this form, *dst* is treated as a pointer to a (char \*); **ParseArgv** stores at *\*dst* a pointer to the following argument, and discards the matching and following arguments from *argv*. *Src* is treated as an integer count: if its value is greater than 1, then that many arguments are processed and *Dst* is treated as an array pointer. - **ARGV\_HELP** When this kind of option is encountered, **ParseArgv** uses the *help* fields of *argTable* to format a message describing all the valid arguments. The message is written on stderr and **ParseArgv** returns TRUE. When this happens, the caller normally aborts. If the *key* field of a ARGV\_HELP specifier is NULL, then the specifier will never match any arguments; in this case the specifier simply provides extra documentation, which will be included when some other ARGV\_HELP entry causes help information to be returned. - **ARGV\_REST** This option is used by programs or commands that allow the last several of their options to be the name and/or options for some other program. If a **ARGV\_REST** argument is found, then **ParseArgv** doesn't process any of the remaining arguments; it returns them all at the beginning of *argv* (along with any other unprocessed arguments). In addition, **ParseArgv** treats *dst* as the address of an integer value, and stores at *\*dst* the index of the first of the **ARGV\_REST** options in the returned *argv*. This allows the program to distinguish the **ARGV\_REST** options from other unprocessed options that preceeded the **ARGV\_REST**. - **ARGV\_FUNC** For this kind of argument, *src* is treated as the address of a procedure, which is invoked to process the following argument. The procedure should have the following structure: ``` int func(dst, key, nextArg) char *dst; char *key; char *nextArg; { } ``` - The *dst* and *key* parameters will contain the corresponding fields from the *argTable* entry, and *nextArg* will point to the following argument from *argv* (or NULL if there aren't any more arguments left in *argv*). If *func* uses *nextArg* (so that **ParseArgv** should discard it), then it should return 1. Otherwise it should return 0 and **TkParseArgv** will process the following argument in the normal fashion. In either event the matching argument is discarded. - **ARGV\_GENFUNC** This form provides a more general procedural escape. It treats *src* as the address of a procedure, and passes that procedure all of the remaining arguments. The procedure should have the following form: ``` int genfunc(dst, key, argc, argv) char *dst; char *key; int argc; char **argv; { } ``` - The *dst* and *key* parameters will contain the corresponding fields from the *argTable* entry. *Argc* and *argv* refer to all of the options after the matching one. *Genfunc* should behave in a fashion similar to **ParseArgv**: parse as many of the remaining arguments as it can, then return any that are left by compacting them to the beginning of *argv* (starting at *argv*\[0\]). *Genfunc* should return a count of how many arguments are left in *argv*; **ParseArgv** will process them. If *genfunc* encounters an error then it should print an error message on stderr, and return -1; when this happens **ParseArgv** will abort its processing and return TRUE. ## FLAGS - **ARGV\_DONT\_SKIP\_FIRST\_ARG** **ParseArgv** normally treats *argv\[0\]* as a program or command name, and returns it to the caller just as if it hadn't matched *argTable*. If this flag is given, then *argv\[0\]* is not given special treatment. - **ARGV\_NO\_ABBREV** Normally, **ParseArgv** accepts unique abbreviations for *key* values in *argTable*. If this flag is given then only exact matches will be acceptable. - **ARGV\_NO\_LEFTOVERS** Normally, **ParseArgv** returns unrecognized arguments to the caller. If this bit is set in *flags* then **ParseArgv** will return an error if it encounters any argument that doesn't match *argTable*. The only exception to this rule is *argv\[0\]*, which will be returned to the caller with no errors as long as ARGV\_DONT\_SKIP\_FIRST\_ARG isn't specified. - **ARGV\_NO\_DEFAULTS** Normally, **ParseArgv** searches an internal table of standard argument specifiers in addition to *argTable*. If this bit is set in *flags*, then **ParseArgv** will use only *argTable* and not its default table. - **ARGV\_NO\_PRINT** Normally, **ParseArgv** prints error message on stderr. If this bit is set in *flags*, then **ParseArgv** will not print any error messages. ## EXAMPLE Here is an example definition of an *argTable* and some sample command lines that use the options. Note the effect on *argc* and *argv*; arguments processed by **ParseArgv** are eliminated from *argv*, and *argc* is updated to reflect reduced number of arguments. ``` /* * Define and set default values for globals. */ int debugFlag = 0; int numReps = 100; char defaultFileName[] = "out"; char *fileName = defaultFileName; Boolean exec = FALSE; /* * Define option descriptions. */ ArgvInfo argTable[] = { {"-X", ARGV_CONSTANT, (char *) 1, (char *) &debugFlag, "Turn on debugging printfs"}, {"-N", ARGV_INT, (char *) NULL, (char *) &numReps, "Number of repetitions"}, {"-of", ARGV_STRING, (char *) NULL, (char *) &fileName, "Name of file for output"}, {"x", ARGV_REST, (char *) NULL, (char *) &exec, "File to exec, followed by any arguments (must be last argument)."}, {(char *) NULL, ARGV_END, (char *) NULL, (char *) NULL, (char *) NULL} }; main(argc, argv) int argc; char *argv[]; { ... if (ParseArgv(&argc, argv, argTable, 0)) { exit(1); } /* * Remainder of the program. */ } ``` Note that default values can be assigned to variables named in *argTable*: the variables will only be overwritten if the particular arguments are present in *argv*. Here are some example command lines and their effects. ``` prog -N 200 infile # just sets the numReps variable to 200 prog -of out200 infile # sets fileName to reference "out200" prog -XN 10 infile # sets the debug flag, also sets numReps ``` In all of the above examples, *argc* will be set by **ParseArgv** to 2, *argv*\[0\] will be \`\`prog'', *argv*\[1\] will be \`\`infile'', and *argv*\[2\] will be NULL. ## KEYWORDS arguments, command line, options