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