149364d3cSMike Pritchard.\" $FreeBSD$ 249364d3cSMike Pritchard.\" 318b3ba26SMartin Cracauer.Dd April 3, 1999 4b37b9a6dSNate Williams.Dt GETOPT 1 5b37b9a6dSNate Williams.Os 6b37b9a6dSNate Williams.Sh NAME 7b37b9a6dSNate Williams.Nm getopt 8b37b9a6dSNate Williams.Nd parse command options 9b37b9a6dSNate Williams.Sh SYNOPSIS 10eec64f74SMartin Cracauer.Nm args=\`getopt Ar optstring $*\` 11eec64f74SMartin Cracauer; errcode=$?; set \-\- $args 12b37b9a6dSNate Williams.Sh DESCRIPTION 133898680cSPhilippe CharnierThe 143898680cSPhilippe Charnier.Nm 153898680cSPhilippe Charnierutility is used to break up options in command lines for easy parsing by 16b37b9a6dSNate Williamsshell procedures, and to check for legal options. 170b6471c9SJoerg Wunsch.Ar Optstring 18b37b9a6dSNate Williamsis a string of recognized option letters (see 1994ba280cSRuslan Ermilov.Xr getopt 3 ) ; 20b37b9a6dSNate Williamsif a letter is followed by a colon, the option 21b37b9a6dSNate Williamsis expected to have an argument which may or may not be 22b37b9a6dSNate Williamsseparated from it by white space. 23b37b9a6dSNate WilliamsThe special option 240b6471c9SJoerg Wunsch.Ql \-\- 25b37b9a6dSNate Williamsis used to delimit the end of the options. 263898680cSPhilippe CharnierThe 273898680cSPhilippe Charnier.Nm 283898680cSPhilippe Charnierutility will place 290b6471c9SJoerg Wunsch.Ql \-\- 30b37b9a6dSNate Williamsin the arguments at the end of the options, 31b37b9a6dSNate Williamsor recognize it if used explicitly. 32b37b9a6dSNate WilliamsThe shell arguments 33b37b9a6dSNate Williams(\fB$1 $2\fR ...) are reset so that each option is 34b37b9a6dSNate Williamspreceded by a 350b6471c9SJoerg Wunsch.Ql \- 36b37b9a6dSNate Williamsand in its own shell argument; 37b37b9a6dSNate Williamseach option argument is also in its own shell argument. 38251c176fSRuslan Ermilov.Sh EXAMPLES 39b37b9a6dSNate WilliamsThe following code fragment shows how one might process the arguments 40b37b9a6dSNate Williamsfor a command that can take the options 410b6471c9SJoerg Wunsch.Fl a 42b37b9a6dSNate Williamsand 430b6471c9SJoerg Wunsch.Fl b , 44b37b9a6dSNate Williamsand the option 450b6471c9SJoerg Wunsch.Fl o , 46b37b9a6dSNate Williamswhich requires an argument. 47b37b9a6dSNate Williams.Pp 48b37b9a6dSNate Williams.Bd -literal -offset indent 49eec64f74SMartin Cracauerargs=\`getopt abo: $*\` 50eec64f74SMartin Cracauer# you should not use \`getopt abo: "$@"\` since that would parse 51eec64f74SMartin Cracauer# the arguments differently from what the set command below does. 52b2a75fdfSRuslan Ermilovif [ $? -ne 0 ] 53b37b9a6dSNate Williamsthen 54b37b9a6dSNate Williams echo 'Usage: ...' 55b37b9a6dSNate Williams exit 2 56b37b9a6dSNate Williamsfi 57eec64f74SMartin Cracauerset \-\- $args 58eec64f74SMartin Cracauer# You cannot use the set command with a backquoted getopt directly, 59eec64f74SMartin Cracauer# since the exit code from getopt would be shadowed by those of set, 60eec64f74SMartin Cracauer# which is zero by definition. 61b37b9a6dSNate Williamsfor i 62b37b9a6dSNate Williamsdo 63b37b9a6dSNate Williams case "$i" 64b37b9a6dSNate Williams in 65b37b9a6dSNate Williams \-a|\-b) 660ab2a7aeSMartin Cracauer echo flag $i set; sflags="${i#-}$sflags"; 670ab2a7aeSMartin Cracauer shift;; 68b37b9a6dSNate Williams \-o) 690ab2a7aeSMartin Cracauer echo oarg is "'"$2"'"; oarg="$2"; shift; 700ab2a7aeSMartin Cracauer shift;; 71b37b9a6dSNate Williams \-\-) 72b37b9a6dSNate Williams shift; break;; 73b37b9a6dSNate Williams esac 74b37b9a6dSNate Williamsdone 75eec64f74SMartin Cracauerecho single-char flags: "'"$sflags"'" 7618b3ba26SMartin Cracauerecho oarg is "'"$oarg"'" 77b37b9a6dSNate Williams.Ed 78b37b9a6dSNate Williams.Pp 79b37b9a6dSNate WilliamsThis code will accept any of the following as equivalent: 80b37b9a6dSNate Williams.Pp 81b37b9a6dSNate Williams.Bd -literal -offset indent 82b37b9a6dSNate Williamscmd \-aoarg file file 83b37b9a6dSNate Williamscmd \-a \-o arg file file 84b37b9a6dSNate Williamscmd \-oarg -a file file 85b37b9a6dSNate Williamscmd \-a \-oarg \-\- file file 8618b3ba26SMartin Cracauer.Pp 87b37b9a6dSNate Williams.Ed 88b37b9a6dSNate Williams.Sh SEE ALSO 89b2a75fdfSRuslan Ermilov.Xr getopts 1 , 90b37b9a6dSNate Williams.Xr sh 1 , 91b37b9a6dSNate Williams.Xr getopt 3 92b37b9a6dSNate Williams.Sh DIAGNOSTICS 933898680cSPhilippe CharnierThe 943898680cSPhilippe Charnier.Nm 953898680cSPhilippe Charnierutility prints an error message on the standard error output and exits with 9618b3ba26SMartin Cracauerstatus > 0 when it encounters an option letter not included in 970b6471c9SJoerg Wunsch.Ar optstring . 98b37b9a6dSNate Williams.Sh HISTORY 990fdf8af9SAlexey ZelkinWritten by 1000fdf8af9SAlexey Zelkin.An Henry Spencer , 1010fdf8af9SAlexey Zelkinworking from a Bell Labs manual page. 10287faa07bSSheldon HearnBehavior believed identical to the Bell version. 10387faa07bSSheldon HearnExample changed in 10418b3ba26SMartin Cracauer.Fx 10518b3ba26SMartin Cracauerversion 3.2 and 4.0. 106b37b9a6dSNate Williams.Sh BUGS 107b37b9a6dSNate WilliamsWhatever 108b37b9a6dSNate Williams.Xr getopt 3 109b37b9a6dSNate Williamshas. 110b37b9a6dSNate Williams.Pp 1110ab2a7aeSMartin CracauerArguments containing white space or embedded shell metacharacters 112eec64f74SMartin Cracauergenerally will not survive intact; this looks easy to fix but 1136a3e8b0aSRuslan Ermilovisn't. 1146a3e8b0aSRuslan ErmilovPeople trying to fix 1158fe908efSRuslan Ermilov.Nm 116eec64f74SMartin Cracaueror the example in this manpage should check the history of this file 117eec64f74SMartin Cracauerin 118eec64f74SMartin Cracauer.Fx . 119b37b9a6dSNate Williams.Pp 120b37b9a6dSNate WilliamsThe error message for an invalid option is identified as coming 121b37b9a6dSNate Williamsfrom 1228fe908efSRuslan Ermilov.Nm 123b37b9a6dSNate Williamsrather than from the shell procedure containing the invocation 124b37b9a6dSNate Williamsof 1258fe908efSRuslan Ermilov.Nm ; 1260ab2a7aeSMartin Cracauerthis again is hard to fix. 1270ab2a7aeSMartin Cracauer.Pp 1280ab2a7aeSMartin CracauerThe precise best way to use the 1290ab2a7aeSMartin Cracauer.Nm set 1300ab2a7aeSMartin Cracauercommand to set the arguments without disrupting the value(s) of 1310ab2a7aeSMartin Cracauershell options varies from one shell version to another. 132eec64f74SMartin Cracauer.Pp 133eec64f74SMartin CracauerEach shellscript has to carry complex code to parse arguments halfway 1346a3e8b0aSRuslan Ermilovcorrectly (like the example presented here). 1356a3e8b0aSRuslan ErmilovA better getopt-like tool 136eec64f74SMartin Cracauerwould move much of the complexity into the tool and keep the client 137eec64f74SMartin Cracauershell scripts simpler. 138