diff options
Diffstat (limited to 'getopt-1.1.0a/getopt.1')
| -rw-r--r-- | getopt-1.1.0a/getopt.1 | 441 |
1 files changed, 441 insertions, 0 deletions
diff --git a/getopt-1.1.0a/getopt.1 b/getopt-1.1.0a/getopt.1 new file mode 100644 index 000000000..b7e360315 --- /dev/null +++ b/getopt-1.1.0a/getopt.1 @@ -0,0 +1,441 @@ +.TH GETOPT 1 "May 31, 1997" Linux "" +.SH NAME +getopt \- parse command options (enhanced) +.SH SYNOPSIS +.BR getopt " optstring parameters" + +.BR getopt " [options] [" -- "] optstring parameters" + +.BR getopt " [options] " -o | --options " optstring [options] [" -- "] parameters" +.SH DESCRIPTION +.B getopt +is used to break up +.RI ( parse ) +options in command lines for easy parsing by +shell procedures, and to check for legal options. +It uses the +.SM GNU +.BR getopt (3) +routines to do this. + +The parameters +.B getopt +is called with can be divided into two parts: options +which modify the way getopt will parse +.RI ( options +and +.I -o|--options optstring +in the +.BR SYNOPSIS), +and the parameters which are to be +parsed +.RI ( parameters +in the +.BR SYNOPSIS). +The second part will start at the first non-option parameter +that is not an option argument, or after the first occurence of +.RB ` -- '. +If no +.RB ` -o ' +or +.RB ` --options ' +option is found in the first part, the first +parameter of the second part is used as the short options string. + +If the environment variable +.B GETOPT_COMPATIBLE +is set, or if its first parameter +is not an option (does not start with a +.RB ` - ', +this is the first format in the +.BR SYNOPSIS), +.B getopt +will generate output that is compatible with that of other versions of +.BR getopt (1). +It will still do parameter shuffling and recognize optional +arguments (see section +.B COMPATIBILITY +for more information). + +Traditional implementations of +.BR getopt (1) +are unable to cope with whitespace and other (shell-specific) special characters +in arguments and non-option parameters. To solve this problem, this +implementation can generate +quoted output which must once again be interpreted by the shell (usually +by using the +.B eval +command). This has the effect of preserving those characters, but +you must call +.B getopt +in a way that is no longer compatible with other versions (the second +or third format in the +.BR SYNOPSIS). +To determine whether this enhanced version of +.BR getopt (1) +is installed, a special test option +.RB ( -T ) +can be used. +.SH OPTIONS +.IP "-a, --alternative" +Allow long options to start with a single +.RB ` - '. +.IP "-h, --help" +Output a small usage guide and exit succesfully. No other output is generated. +.IP "-l, --longoptions longopts" +The long (multi-character) options to be recognized. +More than one option name +may be specified at once, by separating the names with commas. This option +may be given more than once, the +.I longopts +are cummulative. +Each long option name +in +.I longopts +may be followed by one colon to indicate it has a required argument,and by two colons to indicate it has an optional argument. +.IP "-n, --name progname" +The name that will be used by the +.BR getopt (3) +routines when it reports errors. Note that errors of +.BR getopt (1) +are still reported as coming from getopt. +.IP "-o, --options shortopts" +The short (one-character) options to be recognized. If this options is not +found, the first parameter of +.B getopt +that does not start with +a +.RB ` - ' +(and is not an option argument) is used as the short options string. +Each short option character +in +.I shortopts +may be followed by one colon to indicate it has a required argument, +and by two colons to indicate it has an optional argument. +The first character of shortopts may be +.RB ` + ' +or +.RB ` - ' +to influence the way +options are parsed and output is generated (see section +.B SCANNING MODES +for details). +.IP "-q, --quiet" +Disable error reporting by getopt(3). +.IP "-Q, --quiet-output" +Do not generate normal output. Errors are still reported by +.BR getopt (3), +unless you also use +.IR -q . +.IP "-s, --shell shell" +Set quoting conventions to those of shell. If no -s argument is found, +the +.SM BASH +conventions are used. Valid arguments are currently +.RB ` sh ' +.RB ` bash ', +.RB ` csh ', +and +.RB ` tcsh '. +.IP "-u, --unquoted" +Do not quote the output. Note that whitespace and special (shell-dependent) +characters can cause havoc in this mode (like they do with other +.BR getopt (1) +implementations). +.IP "-T --test" +Test if your +.BR getopt (1) +is this enhanced version or an old version. This generates no output, +and sets the error status to 4. Other implementations of +.BR getopt (1), +and this version if the environment variable +.B GETOPT_COMPATIBLE +is set, +will return +.RB ` -- ' +and error status 0. +.IP "-V, --version" +Output version information and exit succesfully. No other output is generated. +.SH PARSING +This section specifies the format of the second part of the parameters of +.B getopt +(the +.I parameters +in the +.BR SYNOPSIS ). +The next section +.RB ( OUTPUT ) +describes the output that is +generated. These parameters were typically the parameters a shell function +was called with. +Care must be taken that each parameter the shell function was +called with corresponds to exactly one parameter in the parameter list of +.B getopt +(see the +.BR EXAMPLES ). +All parsing is done by the GNU +.BR getopt (3) +routines. + +The parameters are parsed from left to right. Each parameter is classified as a +short option, a long option, an argument to an option, +or a non-option parameter. + +A simple short option is a +.RB ` - ' +followed by a short option character. If +the option has a required argument, it may be written directly after the option +character or as the next parameter (ie. separated by whitespace on the +command line). If the +option has an optional argument, it must be written directly after the +option character if present. + +It is possible to specify several short options after one +.RB ` - ', +as long as all (except possibly the last) do not have required or optional +arguments. + +A long option normally begins with +.RB ` -- ' +followed by the long option name. +If the option has a required argument, it may be written directly after +the long option name, separated by +.RB ` = ', +or as the next argument (ie. separated by whitespace on the command line). +If the option has an optional argument, it must +be written directly after the long option name, separated by +.RB ` = ', +if present (if you add the +.RB ` = ' +but nothing behind it, it is interpreted +as if no argument was present; this is a slight bug, see the +.BR BUGS ). +Long options may be abbreviated, as long as the abbreviation is not +ambiguous. + +Each parameter not starting with a +.RB ` - ', +and not a required argument of +a previous option, is a non-option parameter. Each parameter after +a +.RB ` -- ' +parameter is always interpreted as a non-option parameter. +If the environment variable +.B POSIXLY_CORRECT +is set, or if the short +option string started with a +.RB ` + ', +all remaining parameters are interpreted +as non-option parameters as soon as the first non-option parameter is +found. +.SH OUTPUT +Output is generated for each element described in the previous section. +Output is done +in the same order as the elements are specified in the input, except +for non-option parameters. Output can be done in +.I compatible +.RI ( unquoted ) +mode, or in such way that whitespace and other special characters within +arguments and non-option parameters are preserved (see +.BR QUOTING ). +When the output is processed in the shell script, it will seem to be +composed of distinct elements that can be processed one by one (by using the +shift command in most shell languages). This is imperfect in unquoted mode, +as elements can be split at unexpected places if they contain whitespace +or special characters. + +If there are problems parsing the parameters, for example because a +required argument is not found or an option is not recognized, an error +will be reported on stderr, there will be no output for the offending +element, and a non-zero error status is returned. + +For a short option, a single +.RB ` - ' +and the option character are generated +as one parameter. If the option has an argument, the next +parameter will be the argument. If the option takes an optional argument, +but none was found, the next parameter will be generated but be empty in +quoting mode, +but no second parameter will be generated in unquoted (compatible) mode. +Note that many other +.BR getopt (1) +implemetations do not support optional arguments. + +If several short options were specified after a single +.RB ` - ', +each will be present in the output as a separate parameter. + +For a long option, +.RB ` -- ' +and the full option name are generated as one +parameter. This is done regardless whether the option was abbreviated or +specified with a single +.RB ` - ' +in the input. Arguments are handled as with short options. + +Normally, no non-option parameters output is generated until all options +and their arguments have been generated. Then +.RB ` -- ' +is generated as a +single parameter, and after it the non-option parameters in the order +they were found, each as a separate parameter. +Only if the first character of the short options string was a +.RB ` - ', +non-option parameter output is generated at the place they are found in the +input (this is not supported if the first format of the +.B SYNOPSIS +is used; in that case all preceding occurences of +.RB ` - ' +and +.RB ` + ' +are ignored). +.SH QUOTING +In compatible mode, whitespace or 'special' characters in arguments or +non-option parameters are not handled correctly. As the output is +fed to the shell script, the script does not know how it is supposed to break +the output into separate parameters. To circumvent this +problem, this implementation offers quoting. The idea is that output +is generated with quotes around each parameter. When this output is once +again fed to the shell (usually by a shell +.B eval +command), it is split correctly into separate parameters. + +Quoting is not enabled if the environment variable +.B GETOPT_COMPATIBLE +is set, if the first form of the +.B SYNOPSIS +is used, or if the option +.RB ` -u ' +is found. + +Different shells use different quoting conventions. You can use the +.RB ` -s ' +option to select the shell you are using. The following shells are +currently supported: +.RB ` sh ', +.RB ` bash ', +.RB ` csh ' +and +.RB ` tcsh '. +Actually, only two `flavors' are distinguished: sh-like quoting conventions +and csh-like quoting conventions. Chances are that if you use another shell +script language, one of these flavors can still be used. + +.SH "SCANNING MODES" +The first character of the short options string may be a +.RB ` - ' +or a +.RB ` + ' +to indicate a special scanning mode. If the first calling form +in the +.B SYNOPSIS +is used they are ignored; the environment variable +.B POSIXLY_CORRECT +is still examined, though. + +If the first character is +.RB ` + ', +or if the environment variable +.B POSIXLY_CORRECT +is set, parsing stops as soon as the first non-option parameter +(ie. a parameter that does not start with a +.RB ` - ') +is found that +is not an option argument. The remaining parameters are all interpreted as +non-option parameters. + +If the first character is a +.RB ` - ', +non-option parameters are outputed at the place where they are found; in normal +operation, they are all collected at the end of output after a +.RB ` -- ' +parameter has been generated. Note that this +.RB ` -- ' +parameter is still generated, but it will always be the last parameter in +this mode. +.SH COMPATIBILITY +This version of +.BR getopt (1) +is written to be as compatible as possible to +other versions. Usually you can just replace them with this version +without any modifications, and with some advantages. + +If the first character of the first parameter of getopt is not a +.RB ` - ', +getopt goes into compatibility mode. It will interpret its first parameter as +the string of short options, and all other arguments will be parsed. It +will still do parameter shuffling (ie. all non-option parameters are outputed +at the end), unless the environment variable +.B POSIXLY_CORRECT +is set. + +The environment variable +.B GETOPT_COMPATIBLE +forces +.B getopt +into compatibility mode. Setting both this environment variable and +.B POSIXLY_CORRECT +offers 100% compatibility for `difficult' programs. Usually, though, +neither is needed. + +In compatibility mode, leading +.RB ` - ' +and +.RB ` + ' +characters in the short options string are ignored. +.SH RETURN CODES +.B getopt +returns error code +.B 0 +for succesful parsing, +.B 1 +if +.BR getopt (3) +returns errors, +.B 2 +if it does not understand its own parameters, +.B 3 +if an internal error occurs like out-of-memory, and +.B 4 +if it is called with +.BR -T . +.SH EXAMPLES +Example scripts for (ba)sh and (t)csh are provided with the +.BR getopt (1) +distribution, and are optionally installed in +.B /usr/local/lib/getopt +or +.BR /usr/lib/getopt . +.SH ENVIRONMENT +.IP POSIXLY_CORRECT +This environment variable is examined by the +.BR getopt (3) +routines. +If it is set, parsing stops as soon as a parameter +is found that is not an option or an option argument. All remaining +parameters are also interpreted as non-option parameters, regardless +whether they start with a +.RB ` - '. +.IP GETOPT_COMPATIBLE +Forces +.B getopt +to use the first calling format as specified in the +.BR SYNOPSIS . +.SH BUGS +.BR getopt (3) +can parse long options with optional arguments that are given an empty optional +argument (but can not do this for short options). This +.BR getopt (1) +treats optional arguments that are empty as if they were not present. + +The syntax if you do not want any short option variables at all is +not very intuitive (you have to set them explicitely to the empty +string). + +.SH AUTHOR +Frodo Looijaard <frodol@dds.nl> +.SH "SEE ALSO" +.BR getopt (3), +.BR bash (1), +.BR tcsh (1). + |