getopt/getopt.1

   1 .\"     $NetBSD: getopt.1,v 1.8 1997/10/19 02:16:57 lukem Exp $
   2 .Dd June 21, 1993
   3 .Dt GETOPT 1
   4 .Os
   5 .Sh NAME
   6 .Nm getopt
   7 .Nd parse command options
   8 .Sh SYNOPSIS
   9 .Li args=\`getopt optstring $*\`
  10 .Pp
  11 .Li set \-\- \`getopt optstring $*\`
  12 .Sh DESCRIPTION
  13 .Nm
  14 is used to break up options in command lines for easy parsing by
  15 shell procedures, and to check for legal options.
  16 .Op Optstring
  17 is a string of recognized option letters (see
  18 .Xr getopt 3
  19 );
  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 .Dq \-\-
  25 is used to delimit the end of the options.
  26 .Nm
  27 will place
  28 .Dq \-\-
  29 in the arguments at the end of the options,
  30 or recognize it if used explicitly.
  31 The shell arguments
  32 (\fB$1 $2\fR ...) are reset so that each option is
  33 preceded by a
  34 .Dq \-
  35 and in its own shell argument;
  36 each option argument is also in its own shell argument.
  37 .Sh EXAMPLE
  38 The following code fragment shows how one might process the arguments
  39 for a command that can take the options
  40 .Op a
  41 and
  42 .Op b ,
  43 and the option
  44 .Op o ,
  45 which requires an argument.
  46 .Pp
  47 .Bd -literal -offset indent
  48 args=\`getopt abo: $*\`
  49 if test $? != 0
  50 then
  51         echo 'Usage: ...'
  52         exit 2
  53 fi
  54 set \-\- $args
  55 for i
  56 do
  57         case "$i"
  58         in
  59                 \-a|\-b)
  60                         flag=$i; shift;;
  61                 \-o)
  62                         oarg=$2; shift; shift;;
  63                 \-\-)
  64                         shift; break;;
  65         esac
  66 done
  67 .Ed
  68 .Pp
  69 This code will accept any of the following as equivalent:
  70 .Pp
  71 .Bd -literal -offset indent
  72 cmd \-aoarg file file
  73 cmd \-a \-o arg file file
  74 cmd \-oarg -a file file
  75 cmd \-a \-oarg \-\- file file
  76 .Ed
  77 .Pp
  78 .St -p1003.2
  79 mandates that the
  80 .Xr sh 1
  81 set command return the value of 0 for the exit status.  Therefore,
  82 the exit status of the
  83 .Nm
  84 command is lost when
  85 .Nm
  86 and the
  87 .Xr sh 1
  88 set command are used on the same line.  The example given
  89 is one way to detect errors found by
  90 .Nm "" .
  91 .Sh SEE ALSO
  92 .Xr sh 1 ,
  93 .Xr getopt 3
  94 .Sh DIAGNOSTICS
  95 .Nm
  96 prints an error message on the standard error output when it
  97 encounters an option letter not included in
  98 .Op optstring .
  99 .Sh HISTORY
 100 Written by Henry Spencer, working from a Bell Labs manual page.
 101 Behavior believed identical to the Bell version.
 102 .Sh BUGS
 103 Whatever
 104 .Xr getopt 3
 105 has.
 106 .Pp
 107 Arguments containing white space or embedded shell metacharacters
 108 generally will not survive intact;  this looks easy to fix but isn't.
 109 .Pp
 110 The error message for an invalid option is identified as coming
 111 from
 112 .Nm
 113 rather than from the shell procedure containing the invocation
 114 of
 115 .Nm "" ;
 116 this again is hard to fix.
 117 .Pp
 118 The precise best way to use the
 119 .Ic set
 120 command to set the arguments without disrupting the value(s) of
 121 shell options varies from one shell version to another.