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