1.\" $NetBSD: getopt.1,v 1.19 2010/01/24 20:13:28 dholland Exp $ 2.Dd November 28, 2009 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.Pq Ev $1 , Ev $2 , ... 32are reset so that each option is 33preceded by a 34.Dq \- 35and in its own shell argument; 36each option argument is also in its own shell argument. 37.Pp 38.Nm 39should not be used in new scripts; use the shell builtin 40.Nm getopts 41instead. 42.Sh EXAMPLES 43The following code fragment shows how one might process the arguments 44for a command that can take the options 45.Op a 46and 47.Op b , 48and the option 49.Op c , 50which requires an argument. 51.Pp 52.Bd -literal -offset indent 53args=\`getopt abc: $*\` 54if [ $? \-ne 0 ]; then 55 echo 'Usage: ...' 56 exit 2 57fi 58set \-\- $args 59while [ $# \-gt 0 ]; do 60 case "$1" in 61 \-a|\-b) 62 flag=$1 63 ;; 64 \-c) 65 carg=$2; shift 66 ;; 67 \-\-) 68 shift; break 69 ;; 70 esac 71 shift 72done 73.Ed 74.Pp 75This code will accept any of the following as equivalent: 76.Pp 77.Bd -literal -offset indent 78cmd \-acarg file file 79cmd \-a \-c arg file file 80cmd \-carg -a file file 81cmd \-a \-carg \-\- file file 82.Ed 83.Pp 84.St -p1003.2 85mandates that the 86.Xr sh 1 87set command return the value of 0 for the exit status. 88Therefore, the exit status of the 89.Nm 90command is lost when 91.Nm 92and the 93.Xr sh 1 94set command are used on the same line. 95The example given is one way to detect errors found by 96.Nm . 97.Sh DIAGNOSTICS 98.Nm 99prints an error message on the standard error output when it 100encounters an option letter not included in 101.Op optstring . 102.Sh SEE ALSO 103.Xr sh 1 , 104.Xr getopt 3 105.Sh HISTORY 106Written by Henry Spencer, working from a Bell Labs manual page. 107Behavior believed identical to the Bell version. 108.Sh BUGS 109Whatever 110.Xr getopt 3 111has. 112.Pp 113Arguments containing white space or embedded shell metacharacters 114generally will not survive intact; this looks easy to fix but isn't. 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.Ic set 126command to set the arguments without disrupting the value(s) of 127shell options varies from one shell version to another. 128