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