1.\" $NetBSD: getopt.1,v 1.14 2002/09/30 11:09:02 grant Exp $ 2.Dd November 9, 2000 3.Dt GETOPT 1 4.Os 5.Sh NAME 6.Nm getopt 7.Nd parse command options 8.Sh SYNOPSIS 9.Li args=\`getopt optstring $*\` 10.Pp 11.Li set \-\- \`getopt optstring $*\` 12.Sh DESCRIPTION 13.Nm 14is used to break up options in command lines for easy parsing by 15shell procedures, and to check for legal options. 16.Op 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.Dq \-\- 24is used to delimit the end of the options. 25.Nm 26will place 27.Dq \-\- 28in the arguments at the end of the options, 29or recognize it if used explicitly. 30The shell arguments 31(\fB$1 $2\fR ...) are reset so that each option is 32preceded by a 33.Dq \- 34and in its own shell argument; 35each option argument is also in its own shell argument. 36.Sh EXAMPLES 37The following code fragment shows how one might process the arguments 38for a command that can take the options 39.Op a 40and 41.Op b , 42and the option 43.Op c , 44which requires an argument. 45.Pp 46.Bd -literal -offset indent 47args=\`getopt abc: $*\` 48if [ $? != 0 ]; then 49 echo 'Usage: ...' 50 exit 2 51fi 52set \-\- $args 53while [ $# \-gt 0 ]; do 54 case "$1" in 55 \-a|\-b) 56 flag=$1 57 ;; 58 \-c) 59 carg=$2; shift 60 ;; 61 \-\-) 62 shift; break 63 ;; 64 esac 65 shift 66done 67.Ed 68.Pp 69This code will accept any of the following as equivalent: 70.Pp 71.Bd -literal -offset indent 72cmd \-acarg file file 73cmd \-a \-c arg file file 74cmd \-carg -a file file 75cmd \-a \-carg \-\- file file 76.Ed 77.Pp 78.St -p1003.2 79mandates that the 80.Xr sh 1 81set command return the value of 0 for the exit status. 82Therefore, the exit status of the 83.Nm 84command is lost when 85.Nm 86and the 87.Xr sh 1 88set command are used on the same line. 89The example given is one way to detect errors found by 90.Nm "" . 91.Sh DIAGNOSTICS 92.Nm 93prints an error message on the standard error output when it 94encounters an option letter not included in 95.Op optstring . 96.Sh SEE ALSO 97.Xr sh 1 , 98.Xr getopt 3 99.Sh HISTORY 100Written by Henry Spencer, working from a Bell Labs manual page. 101Behavior believed identical to the Bell version. 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 isn't. 109.Pp 110The error message for an invalid option is identified as coming 111from 112.Nm 113rather than from the shell procedure containing the invocation 114of 115.Nm "" ; 116this again is hard to fix. 117.Pp 118The precise best way to use the 119.Ic set 120command to set the arguments without disrupting the value(s) of 121shell options varies from one shell version to another. 122