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