1.\" $OpenBSD: getopt.1,v 1.16 2010/10/28 18:33:28 jmc 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: October 28 2010 $ 7.Dt GETOPT 1 8.Os 9.Sh NAME 10.Nm getopt 11.Nd parse command options 12.Sh SYNOPSIS 13.Nm args=`getopt optstring $*`; set -- $args 14.Sh DESCRIPTION 15.Nm 16is used to break up options in command lines for easy parsing by 17shell procedures, and to check for legal options. 18.Op optstring 19is a string of recognized option letters (see 20.Xr getopt 3 ) ; 21if a letter is followed by a colon, the option 22is expected to have an argument which may or may not be 23separated from it by whitespace. 24However, if a letter is followed by two colons, the argument is optional 25and may not be separated by whitespace \- this is an extension not 26covered by POSIX. 27The special option 28.Sq -- 29is used to delimit the end of the options. 30.Nm 31will place 32.Sq -- 33in the arguments at the end of the options, 34or recognize it if used explicitly. 35The shell arguments 36.Pf ( Va $1 , $2 , ... ) 37are reset so that each option is 38preceded by a 39.Sq - 40and in its own shell argument; 41each option argument is also in its own shell argument. 42.Pp 43Note that the construction 44.Cm set -- `getopt optstring $*` 45is not recommended, 46as the exit value from 47.Dq set 48will prevent the exit value from 49.Nm 50from being determined. 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 [ $# -ge 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.Op 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 BUGS 101Whatever 102.Xr getopt 3 103has. 104.Pp 105Arguments containing whitespace or embedded shell metacharacters 106generally will not survive intact; this looks easy to fix but isn't. 107.Pp 108The error message for an invalid option is identified as coming 109from 110.Nm 111rather than from the shell procedure containing the invocation 112of 113.Nm getopt ; 114this again is hard to fix. 115.Pp 116The precise best way to use the 117.Nm set 118command to set the arguments without disrupting the value(s) of 119shell options varies from one shell version to another. 120