Return to getopt.1 CVS log

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

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

1.2     ! deraadt     1: .\"    $OpenBSD: getopt.1,v 1.1.1.1 1995/10/18 08:45:19 deraadt 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
                     11: .Nm Getopt
                     12: is used to break up options in command lines for easy parsing by
                     13: shell procedures, and to check for legal options.
                     14: .Op Optstring
                     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
                     20: separated from it by white space.
                     21: The special option
                     22: .Dq \-\-
                     23: is used to delimit the end of the options.
                     24: .Nm Getopt
                     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.
                     35: .Sh EXAMPLE
                     36: The following code fragment shows how one might process the arguments
                     37: for a command that can take the options
                     38: .Op a
                     39: and
                     40: .Op b ,
                     41: and the option
                     42: .Op o ,
                     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 SEE ALSO
                     75: .Xr sh 1 ,
                     76: .Xr getopt 3
                     77: .Sh DIAGNOSTICS
                     78: .Nm Getopt
                     79: prints an error message on the standard error output when it
                     80: encounters an option letter not included in
                     81: .Op optstring .
                     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
                     90: Arguments containing white space or embedded shell metacharacters
                     91: generally will not survive intact;  this looks easy to fix but isn't.
                     92: .Pp
                     93: The error message for an invalid option is identified as coming
                     94: from
                     95: .Nm getopt
                     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.