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