usr.bin/getopt/getopt.1

   1 .\" $FreeBSD: src/usr.bin/getopt/getopt.1,v 1.10.2.5 2002/12/29 16:35:39 schweikh Exp $
   2 .\"
   3 .Dd October 7, 2009
   4 .Dt GETOPT 1
   5 .Os
   6 .Sh NAME
   7 .Nm getopt
   8 .Nd parse command options
   9 .Sh SYNOPSIS
  10 .Nm args=\`getopt Ar optstring $*\`
  11 ; errcode=$?; set \-\- $args
  12 .Sh DESCRIPTION
  13 The
  14 .Nm
  15 utility is deprecated.
  16 New shell scripts should use the POSIX
  17 .Ic getopts
  18 shell builtin, as described in the
  19 .Xr sh 1
  20 manual page.
  21 .Pp
  22 The
  23 .Nm
  24 utility is used to break up options in command lines for easy parsing by
  25 shell procedures, and to check for legal options.
  26 .Ar Optstring
  27 is a string of recognized option letters (see
  28 .Xr getopt 3 ) ;
  29 if a letter is followed by a colon, the option
  30 is expected to have an argument which may or may not be
  31 separated from it by white space.
  32 The special option
  33 .Ql \-\-
  34 is used to delimit the end of the options.
  35 The
  36 .Nm
  37 utility will place
  38 .Ql \-\-
  39 in the arguments at the end of the options,
  40 or recognize it if used explicitly.
  41 The shell arguments
  42 (\fB$1 $2\fR ...) are reset so that each option is
  43 preceded by a
  44 .Ql \-
  45 and in its own shell argument;
  46 each option argument is also in its own shell argument.
  47 .Sh EXIT STATUS
  48 .Ex -std
  49 .Sh EXAMPLES
  50 The following code fragment shows how one might process the arguments
  51 for a command that can take the options
  52 .Fl a
  53 and
  54 .Fl b ,
  55 and the option
  56 .Fl o ,
  57 which requires an argument.
  58 .Bd -literal -offset indent
  59 args=\`getopt abo: $*\`
  60 # you should not use \`getopt abo: "$@"\` since that would parse
  61 # the arguments differently from what the set command below does.
  62 if [ $? != 0 ]
  63 then
  64         echo 'Usage: ...'
  65         exit 2
  66 fi
  67 set \-\- $args
  68 # You cannot use the set command with a backquoted getopt directly,
  69 # since the exit code from getopt would be shadowed by those of set,
  70 # which is zero by definition.
  71 for i
  72 do
  73         case "$i"
  74         in
  75                 \-a|\-b)
  76                         echo flag $i set; sflags="${i#-}$sflags";
  77                         shift;;
  78                 \-o)
  79                         echo oarg is "'"$2"'"; oarg="$2"; shift;
  80                         shift;;
  81                 \-\-)
  82                         shift; break;;
  83         esac
  84 done
  85 echo single-char flags: "'"$sflags"'"
  86 echo oarg is "'"$oarg"'"
  87 .Ed
  88 .Pp
  89 This code will accept any of the following as equivalent:
  90 .Bd -literal -offset indent
  91 cmd \-aoarg file file
  92 cmd \-a \-o arg file file
  93 cmd \-oarg -a file file
  94 cmd \-a \-oarg \-\- file file
  95 .Ed
  96 .Sh DIAGNOSTICS
  97 The
  98 .Nm
  99 utility prints an error message on the standard error output
 100 when it encounters an option letter not included in
 101 .Ar optstring .
 102 .Sh SEE ALSO
 103 .Xr sh 1 ,
 104 .Xr getopt 3
 105 .Sh HISTORY
 106 Written by
 107 .An Henry Spencer ,
 108 working from a Bell Labs manual page.
 109 Behavior believed identical to the Bell version.
 110 Example changed in
 111 .Fx
 112 version 3.2 and 4.0.
 113 .Sh BUGS
 114 Whatever
 115 .Xr getopt 3
 116 has.
 117 .Pp
 118 Arguments containing white space or embedded shell metacharacters
 119 generally will not survive intact;  this looks easy to fix but
 120 isn't. People trying to fix
 121 .Nm
 122 or the example in this manpage should check the history of this file
 123 in
 124 .Fx .
 125 .Pp
 126 The error message for an invalid option is identified as coming
 127 from
 128 .Nm
 129 rather than from the shell procedure containing the invocation
 130 of
 131 .Nm ;
 132 this again is hard to fix.
 133 .Pp
 134 The precise best way to use the
 135 .Nm set
 136 command to set the arguments without disrupting the value(s) of
 137 shell options varies from one shell version to another.
 138 .Pp
 139 Each shellscript has to carry complex code to parse arguments halfway
 140 correctly (like the example presented here). A better getopt-like tool
 141 would move much of the complexity into the tool and keep the client
 142 shell scripts simpler.
 143 For
 144 .Xr sh 1
 145 scripts, the POSIX
 146 .Ic getopts
 147 shell builtin provides a better way to perform this task.