.Dd January 26, 2011 .Dt GETOPT 1 .Os .Sh NAME .Nm getopt .Nd parse command options .Sh SYNOPSIS .Nm args=\`getopt Ar optstring $*\` ; errcode=$?; set -- $args .Sh DESCRIPTION The .Nm utility is used to break up options in command lines for easy parsing by shell procedures, and to check for legal options. .Ar Optstring is a string of recognized option letters (see .Xr getopt 3 ) ; if a letter is followed by a colon, the option is expected to have an argument which may or may not be separated from it by white space. The special option .Ql -- is used to delimit the end of the options. The .Nm utility will place .Ql -- in the arguments at the end of the options, or recognize it if used explicitly. The shell arguments ($1 $2 ...) are reset so that each option is preceded by a .Ql - and in its own shell argument; each option argument is also in its own shell argument. .Sh EXIT STATUS The .Nm utility prints an error message on the standard error output and exits with status > 0 when it encounters an option letter not included in .Ar optstring . .Sh EXAMPLES The following code fragment shows how one might process the arguments for a command that can take the options .Fl a and .Fl b , and the option .Fl o , which requires an argument. d -literal -offset indent args=\`getopt abo: $*\` # you should not use \`getopt abo: "$@"\` since that would parse # the arguments differently from what the set command below does. if [ $? -ne 0 ]; then echo 'Usage: ...' exit 2 fi set -- $args # You cannot use the set command with a backquoted getopt directly, # since the exit code from getopt would be shadowed by those of set, # which is zero by definition. while true; do case "$1" in -a|-b) echo "flag $1 set"; sflags="${1#-}$sflags" shift ;; -o) echo "oarg is '$2'"; oarg="$2" shift; shift ;; --) shift; break ;; esac done echo "single-char flags: '$sflags'" echo "oarg is '$oarg'" .Ed
p This code will accept any of the following as equivalent: d -literal -offset indent cmd -aoarg file file cmd -a -o arg file file cmd -oarg -a file file cmd -a -oarg -- file file .Ed .Sh SEE ALSO .Xr getopts 1 , .Xr sh 1 , .Xr getopt 3 .Sh HISTORY Written by .An Henry Spencer , working from a Bell Labs manual page. Behavior believed identical to the Bell version. Example changed in .Fx version 3.2 and 4.0. .Sh BUGS Whatever .Xr getopt 3 has.
p Arguments containing white space or embedded shell metacharacters generally will not survive intact; this looks easy to fix but is not. People trying to fix .Nm or the example in this manpage should check the history of this file in .Fx .
p The error message for an invalid option is identified as coming from .Nm rather than from the shell procedure containing the invocation of .Nm ; this again is hard to fix.
p The precise best way to use the .Nm set command to set the arguments without disrupting the value(s) of shell options varies from one shell version to another.
p Each shellscript has to carry complex code to parse arguments halfway correctly (like the example presented here). A better getopt-like tool would move much of the complexity into the tool and keep the client shell scripts simpler.