Return to getopt.1 CVS log

Up to [local] / src / usr.bin / getopt

Annotation of src/usr.bin/getopt/getopt.1, Revision 1.9

1.9     ! jmc         1: .\"    $OpenBSD: getopt.1,v 1.8 2003/02/17 13:39:37 jmc Exp $  -*- nroff -*-
1.8       jmc         2: .\"
                      3: .\" This material, written by Henry Spencer, was released by him
                      4: .\" into the public domain and is thus not subject to any copyright.
                      5: .\"
1.1       deraadt     6: .Dd June 21, 1993
                      7: .Dt GETOPT 1
                      8: .Os
                      9: .Sh NAME
                     10: .Nm getopt
                     11: .Nd parse command options
                     12: .Sh SYNOPSIS
1.9     ! jmc        13: .Nm set -- `getopt optstring $*`
1.1       deraadt    14: .Sh DESCRIPTION
1.4       aaron      15: .Nm
1.1       deraadt    16: is used to break up options in command lines for easy parsing by
                     17: shell procedures, and to check for legal options.
1.4       aaron      18: .Op optstring
1.1       deraadt    19: is a string of recognized option letters (see
1.7       aaron      20: .Xr getopt 3 ) ;
1.1       deraadt    21: if a letter is followed by a colon, the option
                     22: is expected to have an argument which may or may not be
1.5       aaron      23: separated from it by whitespace.
1.1       deraadt    24: The special option
1.9     ! jmc        25: .Sq --
1.1       deraadt    26: is used to delimit the end of the options.
1.4       aaron      27: .Nm
1.1       deraadt    28: will place
1.9     ! jmc        29: .Sq --
1.1       deraadt    30: in the arguments at the end of the options,
                     31: or recognize it if used explicitly.
                     32: The shell arguments
1.9     ! jmc        33: .Pf ( Va $1 , $2 , ... )
        !            34: are reset so that each option is
1.1       deraadt    35: preceded by a
1.9     ! jmc        36: .Sq -
1.1       deraadt    37: and in its own shell argument;
                     38: each option argument is also in its own shell argument.
1.6       aaron      39: .Sh EXAMPLES
1.1       deraadt    40: The following code fragment shows how one might process the arguments
                     41: for a command that can take the options
1.6       aaron      42: .Fl a
1.1       deraadt    43: and
1.6       aaron      44: .Fl b ,
1.1       deraadt    45: and the option
1.6       aaron      46: .Fl o ,
1.1       deraadt    47: which requires an argument.
                     48: .Bd -literal -offset indent
1.9     ! jmc        49: set -- `getopt abo: $*`
1.1       deraadt    50: if test $? != 0
                     51: then
                     52:        echo 'Usage: ...'
                     53:        exit 2
                     54: fi
                     55: for i
                     56: do
                     57:        case "$i"
                     58:        in
1.9     ! jmc        59:                -a|-b)
1.1       deraadt    60:                        flag=$i; shift;;
1.9     ! jmc        61:                -o)
1.1       deraadt    62:                        oarg=$2; shift; shift;;
1.9     ! jmc        63:                --)
1.1       deraadt    64:                        shift; break;;
                     65:        esac
                     66: done
                     67: .Ed
                     68: .Pp
                     69: This code will accept any of the following as equivalent:
                     70: .Bd -literal -offset indent
1.9     ! jmc        71: cmd -aoarg file file
        !            72: cmd -a -o arg file file
        !            73: cmd -oarg -a file file
        !            74: cmd -a -oarg -- file file
1.1       deraadt    75: .Ed
                     76: .Sh DIAGNOSTICS
1.4       aaron      77: .Nm
1.1       deraadt    78: prints an error message on the standard error output when it
                     79: encounters an option letter not included in
                     80: .Op optstring .
1.6       aaron      81: .Sh SEE ALSO
                     82: .Xr sh 1 ,
                     83: .Xr getopt 3
1.1       deraadt    84: .Sh HISTORY
                     85: Written by Henry Spencer, working from a Bell Labs manual page.
                     86: Behavior believed identical to the Bell version.
                     87: .Sh BUGS
                     88: Whatever
                     89: .Xr getopt 3
                     90: has.
                     91: .Pp
1.5       aaron      92: Arguments containing whitespace or embedded shell metacharacters
1.6       aaron      93: generally will not survive intact; this looks easy to fix but isn't.
1.1       deraadt    94: .Pp
                     95: The error message for an invalid option is identified as coming
                     96: from
1.4       aaron      97: .Nm
1.1       deraadt    98: rather than from the shell procedure containing the invocation
                     99: of
                    100: .Nm getopt ;
                    101: this again is hard to fix.
                    102: .Pp
                    103: The precise best way to use the
                    104: .Nm set
                    105: command to set the arguments without disrupting the value(s) of
                    106: shell options varies from one shell version to another.