Return to getopt.1 CVS log

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

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

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