149364d3cSMike Pritchard.\" $FreeBSD$ 249364d3cSMike Pritchard.\" 3c47f6acfSJohn-Mark Gurney.Dd August 1, 2015 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. 386c7216dfSRuslan Ermilov.Sh EXIT STATUS 396c7216dfSRuslan ErmilovThe 406c7216dfSRuslan Ermilov.Nm 416c7216dfSRuslan Ermilovutility prints an error message on the standard error output and exits with 426c7216dfSRuslan Ermilovstatus > 0 when it encounters an option letter not included in 436c7216dfSRuslan Ermilov.Ar optstring . 44251c176fSRuslan Ermilov.Sh EXAMPLES 45b37b9a6dSNate WilliamsThe following code fragment shows how one might process the arguments 46b37b9a6dSNate Williamsfor a command that can take the options 470b6471c9SJoerg Wunsch.Fl a 48b37b9a6dSNate Williamsand 490b6471c9SJoerg Wunsch.Fl b , 50b37b9a6dSNate Williamsand the option 510b6471c9SJoerg Wunsch.Fl o , 52b37b9a6dSNate Williamswhich requires an argument. 53b37b9a6dSNate Williams.Bd -literal -offset indent 54eec64f74SMartin Cracauerargs=\`getopt abo: $*\` 55eec64f74SMartin Cracauer# you should not use \`getopt abo: "$@"\` since that would parse 56eec64f74SMartin Cracauer# the arguments differently from what the set command below does. 57200520dfSUlrich Spörleinif [ $? -ne 0 ]; then 58b37b9a6dSNate Williams echo 'Usage: ...' 59b37b9a6dSNate Williams exit 2 60b37b9a6dSNate Williamsfi 61eec64f74SMartin Cracauerset \-\- $args 62eec64f74SMartin Cracauer# You cannot use the set command with a backquoted getopt directly, 63eec64f74SMartin Cracauer# since the exit code from getopt would be shadowed by those of set, 64eec64f74SMartin Cracauer# which is zero by definition. 65c47f6acfSJohn-Mark Gurneywhile :; do 66200520dfSUlrich Spörlein case "$1" in 67b37b9a6dSNate Williams \-a|\-b) 68200520dfSUlrich Spörlein echo "flag $1 set"; sflags="${1#-}$sflags" 69200520dfSUlrich Spörlein shift 70200520dfSUlrich Spörlein ;; 71b37b9a6dSNate Williams \-o) 72200520dfSUlrich Spörlein echo "oarg is '$2'"; oarg="$2" 73200520dfSUlrich Spörlein shift; shift 74200520dfSUlrich Spörlein ;; 75b37b9a6dSNate Williams \-\-) 76200520dfSUlrich Spörlein shift; break 77200520dfSUlrich Spörlein ;; 78b37b9a6dSNate Williams esac 79b37b9a6dSNate Williamsdone 80200520dfSUlrich Spörleinecho "single-char flags: '$sflags'" 81200520dfSUlrich Spörleinecho "oarg is '$oarg'" 82b37b9a6dSNate Williams.Ed 83b37b9a6dSNate Williams.Pp 84b37b9a6dSNate WilliamsThis code will accept any of the following as equivalent: 85b37b9a6dSNate Williams.Bd -literal -offset indent 86c47f6acfSJohn-Mark Gurneycmd \-aoarg file1 file2 87c47f6acfSJohn-Mark Gurneycmd \-a \-o arg file1 file2 88c47f6acfSJohn-Mark Gurneycmd \-oarg -a file1 file2 89c47f6acfSJohn-Mark Gurneycmd \-a \-oarg \-\- file1 file2 90b37b9a6dSNate Williams.Ed 91b37b9a6dSNate Williams.Sh SEE ALSO 92b2a75fdfSRuslan Ermilov.Xr getopts 1 , 93b37b9a6dSNate Williams.Xr sh 1 , 94b37b9a6dSNate Williams.Xr getopt 3 95b37b9a6dSNate Williams.Sh HISTORY 960fdf8af9SAlexey ZelkinWritten by 970fdf8af9SAlexey Zelkin.An Henry Spencer , 980fdf8af9SAlexey Zelkinworking from a Bell Labs manual page. 9987faa07bSSheldon HearnBehavior believed identical to the Bell version. 10087faa07bSSheldon HearnExample changed in 10118b3ba26SMartin Cracauer.Fx 10218b3ba26SMartin Cracauerversion 3.2 and 4.0. 103b37b9a6dSNate Williams.Sh BUGS 104b37b9a6dSNate WilliamsWhatever 105b37b9a6dSNate Williams.Xr getopt 3 106b37b9a6dSNate Williamshas. 107b37b9a6dSNate Williams.Pp 1080ab2a7aeSMartin CracauerArguments containing white space or embedded shell metacharacters 109eec64f74SMartin Cracauergenerally will not survive intact; this looks easy to fix but 1100227791bSRuslan Ermilovis not. 1116a3e8b0aSRuslan ErmilovPeople trying to fix 1128fe908efSRuslan Ermilov.Nm 113eec64f74SMartin Cracaueror the example in this manpage should check the history of this file 114eec64f74SMartin Cracauerin 115eec64f74SMartin Cracauer.Fx . 116b37b9a6dSNate Williams.Pp 117b37b9a6dSNate WilliamsThe error message for an invalid option is identified as coming 118b37b9a6dSNate Williamsfrom 1198fe908efSRuslan Ermilov.Nm 120b37b9a6dSNate Williamsrather than from the shell procedure containing the invocation 121b37b9a6dSNate Williamsof 1228fe908efSRuslan Ermilov.Nm ; 1230ab2a7aeSMartin Cracauerthis again is hard to fix. 1240ab2a7aeSMartin Cracauer.Pp 1250ab2a7aeSMartin CracauerThe precise best way to use the 1260ab2a7aeSMartin Cracauer.Nm set 1270ab2a7aeSMartin Cracauercommand to set the arguments without disrupting the value(s) of 1280ab2a7aeSMartin Cracauershell options varies from one shell version to another. 129eec64f74SMartin Cracauer.Pp 130eec64f74SMartin CracauerEach shellscript has to carry complex code to parse arguments halfway 1316a3e8b0aSRuslan Ermilovcorrectly (like the example presented here). 1326a3e8b0aSRuslan ErmilovA better getopt-like tool 133eec64f74SMartin Cracauerwould move much of the complexity into the tool and keep the client 134eec64f74SMartin Cracauershell scripts simpler. 135