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