Return to getopt.1 CVS log

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

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

1.15    ! okan        1: .\"    $OpenBSD: getopt.1,v 1.14 2007/05/31 19:20:10 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.15    ! okan        6: .Dd $Mdocdate: May 31 2007 $
1.1       deraadt     7: .Dt GETOPT 1
                      8: .Os
                      9: .Sh NAME
                     10: .Nm getopt
                     11: .Nd parse command options
                     12: .Sh SYNOPSIS
1.13      jmc        13: .Nm args=`getopt optstring $*`; set -- $args
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.15    ! okan       24: However, if a letter is followed by two colons, the argument is optional
        !            25: and may not be separated by whitespace \- this is an extension not
        !            26: covered by POSIX.
1.1       deraadt    27: The special option
1.9       jmc        28: .Sq --
1.1       deraadt    29: is used to delimit the end of the options.
1.4       aaron      30: .Nm
1.1       deraadt    31: will place
1.9       jmc        32: .Sq --
1.1       deraadt    33: in the arguments at the end of the options,
                     34: or recognize it if used explicitly.
                     35: The shell arguments
1.9       jmc        36: .Pf ( Va $1 , $2 , ... )
                     37: are reset so that each option is
1.1       deraadt    38: preceded by a
1.9       jmc        39: .Sq -
1.1       deraadt    40: and in its own shell argument;
                     41: each option argument is also in its own shell argument.
1.11      jmc        42: .Pp
                     43: Note that the construction
                     44: .Cm set -- `getopt optstring $*`
                     45: is not recommended,
                     46: as the exit value from
                     47: .Dq set
                     48: will prevent the exit value from
                     49: .Nm
                     50: from being determined.
1.6       aaron      51: .Sh EXAMPLES
1.1       deraadt    52: The following code fragment shows how one might process the arguments
                     53: for a command that can take the options
1.6       aaron      54: .Fl a
1.1       deraadt    55: and
1.6       aaron      56: .Fl b ,
1.1       deraadt    57: and the option
1.6       aaron      58: .Fl o ,
1.1       deraadt    59: which requires an argument.
                     60: .Bd -literal -offset indent
1.10      jmc        61: args=`getopt abo: $*`
                     62: if [ $? -ne 0 ]
1.1       deraadt    63: then
                     64:        echo 'Usage: ...'
                     65:        exit 2
                     66: fi
1.10      jmc        67: set -- $args
1.12      otto       68: while [ $# -ge 0 ]
1.1       deraadt    69: do
1.12      otto       70:        case "$1"
1.1       deraadt    71:        in
1.9       jmc        72:                -a|-b)
1.12      otto       73:                        flag="$1"; shift;;
1.9       jmc        74:                -o)
1.12      otto       75:                        oarg="$2"; shift; shift;;
1.9       jmc        76:                --)
1.1       deraadt    77:                        shift; break;;
                     78:        esac
                     79: done
                     80: .Ed
                     81: .Pp
                     82: This code will accept any of the following as equivalent:
                     83: .Bd -literal -offset indent
1.9       jmc        84: cmd -aoarg file file
                     85: cmd -a -o arg file file
                     86: cmd -oarg -a file file
                     87: cmd -a -oarg -- file file
1.1       deraadt    88: .Ed
                     89: .Sh DIAGNOSTICS
1.4       aaron      90: .Nm
1.1       deraadt    91: prints an error message on the standard error output when it
                     92: encounters an option letter not included in
                     93: .Op optstring .
1.6       aaron      94: .Sh SEE ALSO
                     95: .Xr sh 1 ,
                     96: .Xr getopt 3
1.1       deraadt    97: .Sh HISTORY
                     98: Written by Henry Spencer, working from a Bell Labs manual page.
                     99: Behavior believed identical to the Bell version.
                    100: .Sh BUGS
                    101: Whatever
                    102: .Xr getopt 3
                    103: has.
                    104: .Pp
1.5       aaron     105: Arguments containing whitespace or embedded shell metacharacters
1.6       aaron     106: generally will not survive intact; this looks easy to fix but isn't.
1.1       deraadt   107: .Pp
                    108: The error message for an invalid option is identified as coming
                    109: from
1.4       aaron     110: .Nm
1.1       deraadt   111: rather than from the shell procedure containing the invocation
                    112: of
                    113: .Nm getopt ;
                    114: this again is hard to fix.
                    115: .Pp
                    116: The precise best way to use the
                    117: .Nm set
                    118: command to set the arguments without disrupting the value(s) of
                    119: shell options varies from one shell version to another.