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