1.\" $OpenBSD: getopt.1,v 1.14 2007/05/31 19:20:10 jmc Exp $ -*- nroff -*- 2.\" 3.\" This material, written by Henry Spencer, was released by him 4.\" into the public domain and is thus not subject to any copyright. 5.\" 6.Dd $Mdocdate: May 31 2007 $ 7.Dt GETOPT 1 8.Os 9.Sh NAME 10.Nm getopt 11.Nd parse command options 12.Sh SYNOPSIS 13.Nm args=`getopt optstring $*`; set -- $args 14.Sh DESCRIPTION 15.Nm 16is used to break up options in command lines for easy parsing by 17shell procedures, and to check for legal options. 18.Op optstring 19is a string of recognized option letters (see 20.Xr getopt 3 ) ; 21if a letter is followed by a colon, the option 22is expected to have an argument which may or may not be 23separated from it by whitespace. 24The special option 25.Sq -- 26is used to delimit the end of the options. 27.Nm 28will place 29.Sq -- 30in the arguments at the end of the options, 31or recognize it if used explicitly. 32The shell arguments 33.Pf ( Va $1 , $2 , ... ) 34are reset so that each option is 35preceded by a 36.Sq - 37and in its own shell argument; 38each option argument is also in its own shell argument. 39.Pp 40Note that the construction 41.Cm set -- `getopt optstring $*` 42is not recommended, 43as the exit value from 44.Dq set 45will prevent the exit value from 46.Nm 47from being determined. 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: $*` 59if [ $? -ne 0 ] 60then 61 echo 'Usage: ...' 62 exit 2 63fi 64set -- $args 65while [ $# -ge 0 ] 66do 67 case "$1" 68 in 69 -a|-b) 70 flag="$1"; shift;; 71 -o) 72 oarg="$2"; shift; shift;; 73 --) 74 shift; break;; 75 esac 76done 77.Ed 78.Pp 79This code will accept any of the following as equivalent: 80.Bd -literal -offset indent 81cmd -aoarg file file 82cmd -a -o arg file file 83cmd -oarg -a file file 84cmd -a -oarg -- file file 85.Ed 86.Sh DIAGNOSTICS 87.Nm 88prints an error message on the standard error output when it 89encounters an option letter not included in 90.Op optstring . 91.Sh SEE ALSO 92.Xr sh 1 , 93.Xr getopt 3 94.Sh HISTORY 95Written by Henry Spencer, working from a Bell Labs manual page. 96Behavior believed identical to the Bell version. 97.Sh BUGS 98Whatever 99.Xr getopt 3 100has. 101.Pp 102Arguments containing whitespace or embedded shell metacharacters 103generally will not survive intact; this looks easy to fix but isn't. 104.Pp 105The error message for an invalid option is identified as coming 106from 107.Nm 108rather than from the shell procedure containing the invocation 109of 110.Nm getopt ; 111this again is hard to fix. 112.Pp 113The precise best way to use the 114.Nm set 115command to set the arguments without disrupting the value(s) of 116shell options varies from one shell version to another. 117