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