mdw@git.distorted.org.uk Git - ezmlm/blob - getopt.3

   1 .TH getopt 3
   2 .SH NAME
   3 getopt \- get option character from command line
   4 .SH SYNTAX
   5 .B #include <getopt.h>
   6
   7 char *\fBoptarg\fP;
   8 .br
   9 int \fBoptind\fP;
  10 .br
  11 int \fBoptpos\fP;
  12 .br
  13 int \fBopteof\fP;
  14 .br
  15 int \fBoptproblem\fP;
  16 .br
  17 char *\fBoptprogname\fP;
  18 .br
  19 int \fBopterr\fP;
  20
  21 int \fBgetopt(\fP\fIargc,argv,opts\fR\fB)\fP;
  22
  23 int \fIargc\fR;
  24 .br
  25 char **\fIargv\fR;
  26 .br
  27 char *\fIopts\fR;
  28 .SH DESCRIPTION
  29 This is a clone version of
  30 the standard
  31 .B getopt
  32 library,
  33 built on top of
  34 .BR subgetopt(3) .
  35
  36 See
  37 .B subgetopt(3)
  38 for a detailed description of
  39 .B getopt
  40 processing.
  41 The main difference between
  42 .B getopt
  43 and
  44 .B subgetopt
  45 is that
  46 .B getopt
  47 prints error messages
  48 in case of problems.
  49 To turn off these error messages, set
  50 .B opterr
  51 (default nonzero)
  52 to zero.
  53
  54 This clone version of
  55 .B getopt
  56 also provides an
  57 .B optprogname
  58 variable.
  59 There are two uses for this variable:
  60
  61 (1)
  62 By default
  63 .B optprogname
  64 is null.
  65 When
  66 .B getopt
  67 sees this,
  68 it
  69 attempts to initialize
  70 .B optprogname
  71 from
  72 .IR argv\fB[0] ,
  73 stripping the directory name.
  74 The calling program can use
  75 .B optprogname
  76 after calling
  77 .B getopt
  78 at least once.
  79 This is appropriate if the name of the program should be
  80 determined from its command line.
  81
  82 (2)
  83 .B getopt
  84 prints
  85 .B optprogname
  86 at the beginning
  87 of any error messages.
  88 So the calling program can,
  89 before calling
  90 .BR getopt ,
  91 initialize
  92 .B optprogname
  93 as desired.
  94 This is appropriate if the name of the program should not be
  95 determined from its command line.
  96 .SH "COMPATIBILITY"
  97 Old versions of
  98 .B getopt
  99 do not include
 100 .BR opterr .
 101 .BR optpos ,
 102 .BR opteof ,
 103 .BR optproblem ,
 104 and
 105 .B optprogname
 106 are specific to this clone version of
 107 .BR getopt .
 108
 109 Many features of this clone version of
 110 .B getopt
 111 are poorly defined, if available at all,
 112 in most versions of
 113 .BR getopt .
 114 For example, the standard
 115 .B getopt
 116 interface does not define
 117 .B optind
 118 until the end of the option list.
 119 And
 120 .B optarg
 121 is not defined
 122 unless
 123 .B getopt
 124 has just returned
 125 an option which takes an argument.
 126 In this clone version,
 127 .B optind
 128 and
 129 .B optpos
 130 always indicate the next character to be read,
 131 and
 132 .B optarg
 133 is null whenever
 134 the current option does not take an argument.
 135 See
 136 .B subgetopt(3)
 137 for precise definitions of the parsing procedure.
 138
 139 When it reaches the end of the option list,
 140 this version of
 141 .B getopt
 142 always returns
 143 .BR opteof ,
 144 which is the same as
 145 .BR subgetoptdone ,
 146 which is initialized to
 147 .BR SUBGETOPTDONE ,
 148 which is defined as \-1.
 149 The standard behavior is to return
 150 EOF
 151 from
 152 .B stdio(3).
 153 This is incompatible
 154 on any weird machine where
 155 EOF is different from \-1.
 156 The calling program could set
 157 .B opteof
 158 to EOF to imitate the standard behavior.
 159
 160 Like most versions of
 161 .BR getopt ,
 162 this clone version allows, but does not demand, that
 163 option arguments be
 164 separated from the option by whitespace, i.e., be
 165 in the next command-line argument.
 166
 167 Some versions of
 168 .B getopt
 169 provide an
 170 .B optopt
 171 variable.
 172 .B optopt
 173 is incompatible across systems:
 174 for example,
 175 GNU
 176 .B getopt
 177 uses it the same way that this clone version uses
 178 .BR optproblem ,
 179 while
 180 BSD
 181 .B getopt
 182 uses it to
 183 indicate the last option character returned by
 184 .BR getopt .
 185 This clone version does not provide
 186 .BR optopt .
 187 The use of
 188 .B optopt
 189 is strongly discouraged.
 190
 191 Some versions of
 192 .B getopt
 193 do not recognize a double hyphen as the end of arguments.
 194 This version allows a double hyphen, or in fact any argument beginning
 195 with two hyphens.
 196
 197 A lone hyphen is always recognized as the end of arguments.
 198 Some versions of
 199 .B getopt
 200 allow lone hyphens as options.
 201 This practice is wrong and is strongly discouraged.
 202 .SH "SYNTAX NOTE"
 203 .B getopt
 204 is actually a macro abbreviation for
 205 .BR getoptmine .
 206 The external
 207 .B opterr
 208 and
 209 .B optprogname
 210 variables
 211 are macros for
 212 .B getopterr
 213 and
 214 .BR getoptprogname .
 215 All the other
 216 .B opt
 217 variables are macros
 218 for
 219 .BR subgetopt .
 220 These macros are defined in
 221 .BR <getopt.h> ,
 222 unless
 223 .B GETOPTNOSHORT
 224 is defined.
 225 Further macros are defined in
 226 .BR <subgetopt.h> ,
 227 which is included by
 228 .BR <getopt.h> ,
 229 unless
 230 .B SUBGETOPTNOSHORT
 231 is defined.
 232 .SH VERSION
 233 getopt version 1.9, 931129.
 234 .SH AUTHOR
 235 Placed into the public domain by Daniel J. Bernstein.