1.Dd April 3, 1999 2.Dt GETOPT 1 3.Os 4.Sh NAME 5.Nm getopt 6.Nd parse command options 7.Sh SYNOPSIS 8.Nm args=\`getopt Ar optstring $*\` 9; errcode=$?; set \-\- $args 10.Sh DESCRIPTION 11.Nm Getopt 12is used to break up options in command lines for easy parsing by 13shell procedures, and to check for legal options. 14.Ar Optstring 15is a string of recognized option letters (see 16.Xr getopt 3 17); 18if a letter is followed by a colon, the option 19is expected to have an argument which may or may not be 20separated from it by white space. 21The special option 22.Ql \-\- 23is used to delimit the end of the options. 24.Nm Getopt 25will place 26.Ql \-\- 27in the arguments at the end of the options, 28or recognize it if used explicitly. 29The shell arguments 30(\fB$1 $2\fR ...) are reset so that each option is 31preceded by a 32.Ql \- 33and in its own shell argument; 34each option argument is also in its own shell argument. 35.Sh EXAMPLE 36The following code fragment shows how one might process the arguments 37for a command that can take the options 38.Fl a 39and 40.Fl b , 41and the option 42.Fl o , 43which requires an argument. 44.Pp 45.Bd -literal -offset indent 46args=\`getopt abo: $*\` 47# you should not use \`getopt abo: "$@"\` since that would parse 48# the arguments differently from what the set command below does. 49if [ $? != 0 ] 50then 51 echo 'Usage: ...' 52 exit 2 53fi 54set \-\- $args 55# You cannot use the set command with a backquoted getopt directly, 56# since the exit code from getopt would be shadowed by those of set, 57# which is zero by definition. 58for i 59do 60 case "$i" 61 in 62 \-a|\-b) 63 echo flag $i set; sflags="${i#-}$sflags"; 64 shift;; 65 \-o) 66 echo oarg is "'"$2"'"; oarg="$2"; shift; 67 shift;; 68 \-\-) 69 shift; break;; 70 esac 71done 72echo single-char flags: "'"$sflags"'" 73echo oarg is "'"$oarg"'" 74.Ed 75.Pp 76This code will accept any of the following as equivalent: 77.Pp 78.Bd -literal -offset indent 79cmd \-aoarg file file 80cmd \-a \-o arg file file 81cmd \-oarg -a file file 82cmd \-a \-oarg \-\- file file 83.Pp 84.Ed 85.Sh SEE ALSO 86.Xr sh 1 , 87.Xr getopt 3 88.Sh DIAGNOSTICS 89.Nm Getopt 90prints an error message on the standard error output and exits with 91status > 0 when it encounters an option letter not included in 92.Ar optstring . 93.Sh HISTORY 94Written by Henry Spencer, working from a Bell Labs manual page. 95Behavior believed identical to the Bell version. Example changed in 96.Fx 97version 3.2 and 4.0. 98.Sh BUGS 99Whatever 100.Xr getopt 3 101has. 102.Pp 103Arguments containing white space or embedded shell metacharacters 104generally will not survive intact; this looks easy to fix but 105isn't. People trying to fix 106.Nm getopt 107or the example in this manpage should check the history of this file 108in 109.Fx . 110.Pp 111The error message for an invalid option is identified as coming 112from 113.Nm getopt 114rather than from the shell procedure containing the invocation 115of 116.Nm getopt ; 117this again is hard to fix. 118.Pp 119The precise best way to use the 120.Nm set 121command to set the arguments without disrupting the value(s) of 122shell options varies from one shell version to another. 123.Pp 124Each shellscript has to carry complex code to parse arguments halfway 125correcty (like the example presented here). A better getopt-like tool 126would move much of the complexity into the tool and keep the client 127shell scripts simpler. 128