118b3ba26SMartin Cracauer.Dd April 3, 1999 2b37b9a6dSNate Williams.Dt GETOPT 1 3b37b9a6dSNate Williams.Os 4b37b9a6dSNate Williams.Sh NAME 5b37b9a6dSNate Williams.Nm getopt 6b37b9a6dSNate Williams.Nd parse command options 7b37b9a6dSNate Williams.Sh SYNOPSIS 80ab2a7aeSMartin Cracauer.Ic var=\`getopt Ar optstring 918b3ba26SMartin Cracauer.Qq $@ 100ab2a7aeSMartin Cracauer\` ; set \-\- $var 11b37b9a6dSNate Williams.Sh DESCRIPTION 12b37b9a6dSNate Williams.Nm Getopt 13b37b9a6dSNate Williamsis used to break up options in command lines for easy parsing by 14b37b9a6dSNate Williamsshell procedures, and to check for legal options. 150b6471c9SJoerg Wunsch.Ar Optstring 16b37b9a6dSNate Williamsis a string of recognized option letters (see 17b37b9a6dSNate Williams.Xr getopt 3 18b37b9a6dSNate Williams); 19b37b9a6dSNate Williamsif a letter is followed by a colon, the option 20b37b9a6dSNate Williamsis expected to have an argument which may or may not be 21b37b9a6dSNate Williamsseparated from it by white space. 22b37b9a6dSNate WilliamsThe special option 230b6471c9SJoerg Wunsch.Ql \-\- 24b37b9a6dSNate Williamsis used to delimit the end of the options. 25b37b9a6dSNate Williams.Nm Getopt 26b37b9a6dSNate Williamswill place 270b6471c9SJoerg Wunsch.Ql \-\- 28b37b9a6dSNate Williamsin the arguments at the end of the options, 29b37b9a6dSNate Williamsor recognize it if used explicitly. 30b37b9a6dSNate WilliamsThe shell arguments 31b37b9a6dSNate Williams(\fB$1 $2\fR ...) are reset so that each option is 32b37b9a6dSNate Williamspreceded by a 330b6471c9SJoerg Wunsch.Ql \- 34b37b9a6dSNate Williamsand in its own shell argument; 35b37b9a6dSNate Williamseach option argument is also in its own shell argument. 36b37b9a6dSNate Williams.Sh EXAMPLE 37b37b9a6dSNate WilliamsThe following code fragment shows how one might process the arguments 38b37b9a6dSNate Williamsfor a command that can take the options 390b6471c9SJoerg Wunsch.Fl a 40b37b9a6dSNate Williamsand 410b6471c9SJoerg Wunsch.Fl b , 42b37b9a6dSNate Williamsand the option 430b6471c9SJoerg Wunsch.Fl o , 44b37b9a6dSNate Williamswhich requires an argument. 45b37b9a6dSNate Williams.Pp 46b37b9a6dSNate Williams.Bd -literal -offset indent 4718b3ba26SMartin Cracauertmp=$(getopt abo: "$@") 4818b3ba26SMartin Cracauerif [ $? != 0 ] 49b37b9a6dSNate Williamsthen 50b37b9a6dSNate Williams echo 'Usage: ...' 51b37b9a6dSNate Williams exit 2 52b37b9a6dSNate Williamsfi 530ab2a7aeSMartin Cracauerset \-\- $tmp 54b37b9a6dSNate Williamsfor i 55b37b9a6dSNate Williamsdo 56b37b9a6dSNate Williams case "$i" 57b37b9a6dSNate Williams in 58b37b9a6dSNate Williams \-a|\-b) 590ab2a7aeSMartin Cracauer echo flag $i set; sflags="${i#-}$sflags"; 600ab2a7aeSMartin Cracauer shift;; 61b37b9a6dSNate Williams \-o) 620ab2a7aeSMartin Cracauer echo oarg is "'"$2"'"; oarg="$2"; shift; 630ab2a7aeSMartin Cracauer shift;; 64b37b9a6dSNate Williams \-\-) 65b37b9a6dSNate Williams shift; break;; 66b37b9a6dSNate Williams esac 67b37b9a6dSNate Williamsdone 6818b3ba26SMartin Cracauerecho single-char flags: $sflags 6918b3ba26SMartin Cracauerecho oarg is "'"$oarg"'" 70b37b9a6dSNate Williams.Ed 71b37b9a6dSNate Williams.Pp 72b37b9a6dSNate WilliamsThis code will accept any of the following as equivalent: 73b37b9a6dSNate Williams.Pp 74b37b9a6dSNate Williams.Bd -literal -offset indent 75b37b9a6dSNate Williamscmd \-aoarg file file 76b37b9a6dSNate Williamscmd \-a \-o arg file file 77b37b9a6dSNate Williamscmd \-oarg -a file file 78b37b9a6dSNate Williamscmd \-a \-oarg \-\- file file 7918b3ba26SMartin Cracauer.Pp 80b37b9a6dSNate Williams.Ed 81b37b9a6dSNate Williams.Sh SEE ALSO 82b37b9a6dSNate Williams.Xr sh 1 , 83b37b9a6dSNate Williams.Xr getopt 3 84b37b9a6dSNate Williams.Sh DIAGNOSTICS 85b37b9a6dSNate Williams.Nm Getopt 8618b3ba26SMartin Cracauerprints an error message on the standard error output and exits with 8718b3ba26SMartin Cracauerstatus > 0 when it encounters an option letter not included in 880b6471c9SJoerg Wunsch.Ar optstring . 89b37b9a6dSNate Williams.Sh HISTORY 90b37b9a6dSNate WilliamsWritten by Henry Spencer, working from a Bell Labs manual page. 9118b3ba26SMartin CracauerBehavior believed identical to the Bell version. Example replaced in 9218b3ba26SMartin Cracauer.Fx 9318b3ba26SMartin Cracauerversion 3.2 and 4.0. 94b37b9a6dSNate Williams.Sh BUGS 95b37b9a6dSNate WilliamsWhatever 96b37b9a6dSNate Williams.Xr getopt 3 97b37b9a6dSNate Williamshas. 98b37b9a6dSNate Williams.Pp 990ab2a7aeSMartin CracauerArguments containing white space or embedded shell metacharacters 1000ab2a7aeSMartin Cracauergenerally will not survive intact; this looks easy to fix but isn't. 101b37b9a6dSNate Williams.Pp 102b37b9a6dSNate WilliamsThe error message for an invalid option is identified as coming 103b37b9a6dSNate Williamsfrom 104b37b9a6dSNate Williams.Nm getopt 105b37b9a6dSNate Williamsrather than from the shell procedure containing the invocation 106b37b9a6dSNate Williamsof 107b37b9a6dSNate Williams.Nm getopt ; 1080ab2a7aeSMartin Cracauerthis again is hard to fix. 1090ab2a7aeSMartin Cracauer.Pp 1100ab2a7aeSMartin CracauerThe precise best way to use the 1110ab2a7aeSMartin Cracauer.Nm set 1120ab2a7aeSMartin Cracauercommand to set the arguments without disrupting the value(s) of 1130ab2a7aeSMartin Cracauershell options varies from one shell version to another. 114