1.\" $FreeBSD: src/usr.bin/getopt/getopt.1,v 1.10.2.5 2002/12/29 16:35:39 schweikh Exp $ 2.\" $DragonFly: src/usr.bin/getopt/getopt.1,v 1.2 2003/06/17 04:29:27 dillon Exp $ 3.\" 4.Dd April 3, 1999 5.Dt GETOPT 1 6.Os 7.Sh NAME 8.Nm getopt 9.Nd parse command options 10.Sh SYNOPSIS 11.Nm args=\`getopt Ar optstring $*\` 12; errcode=$?; set \-\- $args 13.Sh DESCRIPTION 14The 15.Nm 16utility is used to break up options in command lines for easy parsing by 17shell procedures, and to check for legal options. 18.Ar 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 white space. 24The special option 25.Ql \-\- 26is used to delimit the end of the options. 27The 28.Nm 29utility will place 30.Ql \-\- 31in the arguments at the end of the options, 32or recognize it if used explicitly. 33The shell arguments 34(\fB$1 $2\fR ...) are reset so that each option is 35preceded by a 36.Ql \- 37and in its own shell argument; 38each option argument is also in its own shell argument. 39.Sh EXAMPLES 40The following code fragment shows how one might process the arguments 41for a command that can take the options 42.Fl a 43and 44.Fl b , 45and the option 46.Fl o , 47which requires an argument. 48.Pp 49.Bd -literal -offset indent 50args=\`getopt abo: $*\` 51# you should not use \`getopt abo: "$@"\` since that would parse 52# the arguments differently from what the set command below does. 53if [ $? != 0 ] 54then 55 echo 'Usage: ...' 56 exit 2 57fi 58set \-\- $args 59# You cannot use the set command with a backquoted getopt directly, 60# since the exit code from getopt would be shadowed by those of set, 61# which is zero by definition. 62for i 63do 64 case "$i" 65 in 66 \-a|\-b) 67 echo flag $i set; sflags="${i#-}$sflags"; 68 shift;; 69 \-o) 70 echo oarg is "'"$2"'"; oarg="$2"; shift; 71 shift;; 72 \-\-) 73 shift; break;; 74 esac 75done 76echo single-char flags: "'"$sflags"'" 77echo oarg is "'"$oarg"'" 78.Ed 79.Pp 80This code will accept any of the following as equivalent: 81.Pp 82.Bd -literal -offset indent 83cmd \-aoarg file file 84cmd \-a \-o arg file file 85cmd \-oarg -a file file 86cmd \-a \-oarg \-\- file file 87.Pp 88.Ed 89.Sh SEE ALSO 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. People trying to fix 114.Nm 115or the example in this manpage should check the history of this file 116in 117.Fx . 118.Pp 119The error message for an invalid option is identified as coming 120from 121.Nm 122rather than from the shell procedure containing the invocation 123of 124.Nm ; 125this again is hard to fix. 126.Pp 127The precise best way to use the 128.Nm set 129command to set the arguments without disrupting the value(s) of 130shell options varies from one shell version to another. 131.Pp 132Each shellscript has to carry complex code to parse arguments halfway 133correctly (like the example presented here). A better getopt-like tool 134would move much of the complexity into the tool and keep the client 135shell scripts simpler. 136