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