.Dd November 28, 2009 .Dt GETOPT 1 .Os .Sh NAME .Nm getopt .Nd parse command options .Sh SYNOPSIS .Li args=\`getopt optstring $*\`
p .Li set -- \`getopt optstring $*\` .Sh DESCRIPTION .Nm is used to break up options in command lines for easy parsing by shell procedures, and to check for legal options. .Op 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 .Dq -- is used to delimit the end of the options. .Nm will place .Dq -- in the arguments at the end of the options, or recognize it if used explicitly. The shell arguments
q Ev $1 , Ev $2 , ... are reset so that each option is preceded by a .Dq - and in its own shell argument; each option argument is also in its own shell argument.
p .Nm should not be used in new scripts; use the shell builtin .Nm getopts instead. .Sh EXAMPLES The following code fragment shows how one might process the arguments for a command that can take the options .Op a and .Op b , and the option .Op c , which requires an argument.
p d -literal -offset indent args=\`getopt abc: $*\` if [ $? -ne 0 ]; then echo 'Usage: ...' exit 2 fi set -- $args while [ $# -gt 0 ]; do case "$1" in -a|-b) flag=$1 ;; -c) carg=$2; shift ;; --) shift; break ;; esac shift done .Ed
p This code will accept any of the following as equivalent:
p d -literal -offset indent cmd -acarg file file cmd -a -c arg file file cmd -carg -a file file cmd -a -carg -- file file .Ed
p .St -p1003.2 mandates that the .Xr sh 1 set command return the value of 0 for the exit status. Therefore, the exit status of the .Nm command is lost when .Nm and the .Xr sh 1 set command are used on the same line. The example given is one way to detect errors found by .Nm . .Sh DIAGNOSTICS .Nm prints an error message on the standard error output when it encounters an option letter not included in .Op optstring . .Sh SEE ALSO .Xr sh 1 , .Xr getopt 3 .Sh HISTORY Written by Henry Spencer, working from a Bell Labs manual page. Behavior believed identical to the Bell version. .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 isn't.
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 c set command to set the arguments without disrupting the value(s) of shell options varies from one shell version to another.