1.\" $FreeBSD$ 2.\" 3.Dd January 26, 2011 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 EXIT STATUS 39The 40.Nm 41utility prints an error message on the standard error output and exits with 42status > 0 when it encounters an option letter not included in 43.Ar optstring . 44.Sh EXAMPLES 45The following code fragment shows how one might process the arguments 46for a command that can take the options 47.Fl a 48and 49.Fl b , 50and the option 51.Fl o , 52which requires an argument. 53.Bd -literal -offset indent 54args=\`getopt abo: $*\` 55# you should not use \`getopt abo: "$@"\` since that would parse 56# the arguments differently from what the set command below does. 57if [ $? -ne 0 ]; then 58 echo 'Usage: ...' 59 exit 2 60fi 61set \-\- $args 62# You cannot use the set command with a backquoted getopt directly, 63# since the exit code from getopt would be shadowed by those of set, 64# which is zero by definition. 65while true; do 66 case "$1" in 67 \-a|\-b) 68 echo "flag $1 set"; sflags="${1#-}$sflags" 69 shift 70 ;; 71 \-o) 72 echo "oarg is '$2'"; oarg="$2" 73 shift; shift 74 ;; 75 \-\-) 76 shift; break 77 ;; 78 esac 79done 80echo "single-char flags: '$sflags'" 81echo "oarg is '$oarg'" 82.Ed 83.Pp 84This code will accept any of the following as equivalent: 85.Bd -literal -offset indent 86cmd \-aoarg file file 87cmd \-a \-o arg file file 88cmd \-oarg -a file file 89cmd \-a \-oarg \-\- file file 90.Ed 91.Sh SEE ALSO 92.Xr getopts 1 , 93.Xr sh 1 , 94.Xr getopt 3 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 110is not. 111People trying to fix 112.Nm 113or the example in this manpage should check the history of this file 114in 115.Fx . 116.Pp 117The error message for an invalid option is identified as coming 118from 119.Nm 120rather than from the shell procedure containing the invocation 121of 122.Nm ; 123this again is hard to fix. 124.Pp 125The precise best way to use the 126.Nm set 127command to set the arguments without disrupting the value(s) of 128shell options varies from one shell version to another. 129.Pp 130Each shellscript has to carry complex code to parse arguments halfway 131correctly (like the example presented here). 132A better getopt-like tool 133would move much of the complexity into the tool and keep the client 134shell scripts simpler. 135