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