Return to getopt.1 CVS log

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

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

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