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