Return to getopt.1 CVS log

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

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

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