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