usr.bin/getopt/getopt.1

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