nightmaremail

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs

subgetopt.3 (5800B)


      1 .TH subgetopt 3
      2 .SH NAME
      3 subgetopt \- get option character from command line
      4 .SH SYNTAX
      5 .B #include <subgetopt.h>
      6 
      7 char *\fBsgoptarg\fP;
      8 .br
      9 int \fBsgoptind\fP;
     10 .br
     11 int \fBsgoptpos\fP;
     12 .br
     13 int \fBsgoptdone\fP;
     14 .br
     15 int \fBsgoptproblem\fP;
     16 
     17 int \fBsgopt(\fP\fIargc,argv,opts\fR\fB)\fP;
     18 
     19 int \fIargc\fR;
     20 .br
     21 char **\fIargv\fR;
     22 .br
     23 char *\fIopts\fR;
     24 .SH DESCRIPTION
     25 .B sgopt
     26 returns the next valid command-line option character
     27 from
     28 .IR argv .
     29 
     30 Valid option characters are listed in the
     31 .I opts
     32 string.
     33 .I opts
     34 may be empty.
     35 A character in
     36 .I opts
     37 may be followed by a colon,
     38 in which case it
     39 takes an
     40 .I option argument\fR.
     41 Avoid using the characters ?, :, and \- as option characters.
     42 
     43 Below
     44 .I option argument
     45 is abbreviated
     46 as
     47 .I optarg
     48 and
     49 .I command-line argument
     50 is abbreviated as
     51 .IR cmdarg .
     52 
     53 Options are listed in cmdargs which begin with
     54 a minus sign.
     55 Several options which do not take optargs may be combined
     56 into one cmdarg.
     57 
     58 An option which takes an optarg may be handled in two ways.
     59 If it appears at the very end of a cmdarg,
     60 then the entire next cmdarg is the optarg.
     61 But if there are any characters in the cmdarg
     62 after the option character,
     63 then those characters form the optarg.
     64 The optarg is returned in
     65 .BR sgoptarg .
     66 Next time
     67 .B sgopt
     68 looks at the cmdarg which follows the optarg.
     69 
     70 If a cmdarg does not begin with a hyphen,
     71 or if it is a lone hyphen not followed by any characters,
     72 or if it begins with two hyphens,
     73 then it terminates option processing,
     74 and
     75 .B sgopt
     76 returns an appropriate code.
     77 If there are two hyphens,
     78 .B sgopt
     79 will advance attention to the next cmdarg,
     80 so it can be called again to read further options.
     81 .SH "PROPER USAGE"
     82 .B sgoptproblem
     83 should be used only when
     84 .B sgopt
     85 returns ?.
     86 .B sgoptind
     87 and
     88 .B sgoptpos
     89 are defined all the time.
     90 .B sgoptarg
     91 is defined all the time;
     92 it is null unless
     93 .B sgopt
     94 has just returned an option with optarg.
     95 
     96 .B sgopt
     97 is typically used as follows.
     98 
     99 .EX
    100 #include <subgetopt.h>
    101 
    102 main(argc,argv) int argc; char **argv; { int opt;
    103 
    104 while ((opt = sgopt(argc,argv,"a:s")) != sgoptdone)
    105 .br
    106   switch(opt) {
    107 .br
    108     case 'a':
    109 .br
    110       printf("opt a with optarg %s\\n",sgoptarg); break;
    111 .br
    112     case 's':
    113 .br
    114       printf("opt s with no optarg\\n"); break;
    115 .br
    116     case '?':
    117 .br
    118       if (argv[sgoptind] && (sgoptind < argc))
    119 .br
    120         printf("illegal opt %c\\n",sgoptproblem);
    121 .br
    122       else
    123 .br
    124         printf("missing arg, opt %c\\n",sgoptproblem);
    125 .br
    126       exit(1);
    127 .br
    128   }
    129 
    130 argv += sgoptind;
    131 .br
    132 while (*argv) printf("argument %s\\n",*argv++);
    133 .br
    134 exit(0);
    135 .br
    136 }
    137 .EE
    138 
    139 The end of the command line is
    140 marked by either
    141 .IR argc ,
    142 or a null pointer in
    143 .IR argv ,
    144 whichever comes first.
    145 Normally
    146 these two markers coincide,
    147 so it is redundant
    148 to test for
    149 both
    150 .I argv\fB[sgoptind]
    151 and
    152 .B sgoptind < \fIargc\fR.
    153 The above code shows both tests as an illustration.
    154 
    155 .B Multiple option sets:
    156 One useful technique is to call
    157 .B sgopt
    158 with a primary
    159 .I opts
    160 until it returns EOF,
    161 then call
    162 .B sgopt
    163 with a secondary
    164 .I opts
    165 until it returns EOF.
    166 The user can provide primary options, then a double hyphen,
    167 and then secondary options.
    168 No special handling is needed if some or all of the options are
    169 omitted.
    170 The same technique can be used for any number of option sets
    171 in series.
    172 
    173 .B Multiple command lines:
    174 Before parsing a new
    175 .BR argv ,
    176 make sure to
    177 set
    178 .B sgoptind
    179 and
    180 .B sgoptpos
    181 back to
    182 1 and 0.
    183 .SH "PARSING STAGES"
    184 .B sgopt
    185 keeps track of its position in
    186 .I argv
    187 with
    188 .B sgoptind
    189 and
    190 .BR sgoptpos ,
    191 which are initialized to 1 and 0.
    192 It looks at
    193 .I argv\fB[sgoptind][sgoptpos]
    194 and following characters.
    195 
    196 .B sgopt
    197 indicates
    198 that no more options are available by
    199 returning
    200 .BR sgoptdone ,
    201 which is initialized to
    202 .BR SUBGETOPTDONE ,
    203 which is defined as \-1.
    204 
    205 .B sgopt
    206 begins by setting
    207 .B optarg
    208 to null.
    209 
    210 .B Ending conditions:
    211 If
    212 .I argv
    213 is null, or
    214 .B sgoptind
    215 is larger than
    216 .IR argc ,
    217 or the current cmdarg
    218 .I argv\fB[sgoptind]
    219 is null,
    220 then
    221 .B sgopt
    222 returns
    223 .BR optdone .
    224 
    225 .B Stage one:
    226 If the current character
    227 is zero,
    228 .B sgopt
    229 moves to the beginning of the next cmdarg.
    230 It then checks the ending conditions again.
    231 
    232 .B Stage two:
    233 If
    234 the current position is the begining of the cmdarg,
    235 .B sgopt
    236 checks whether
    237 the current character
    238 is a minus sign.
    239 If not it returns
    240 .BR optdone .
    241 It then
    242 moves
    243 to the next character.
    244 If that character is zero,
    245 .B sgopt
    246 moves
    247 back to the beginning of the cmdarg,
    248 and returns
    249 .BR sgoptdone .
    250 If the character is a minus sign,
    251 .B sgopt
    252 moves to the beginning of the next cmdarg,
    253 and returns
    254 .BR sgoptdone .
    255 
    256 .B Stage three:
    257 .B sgopt
    258 records the current character,
    259 .IR c ,
    260 and moves to the next character.
    261 There are three possibilities:
    262 (1)
    263 .I c
    264 is an option character without optarg in
    265 .IR opts ,
    266 or
    267 (2)
    268 .I c
    269 is an option character with optarg in
    270 .IR opts ,
    271 or
    272 (3)
    273 .I c
    274 does not appear in
    275 .IR opts .
    276 
    277 (1)
    278 If
    279 .I c
    280 appears as an option character without optarg in
    281 .IR opts ,
    282 .B sgopt
    283 returns
    284 .IR c .
    285 
    286 (2)
    287 If
    288 .I c
    289 appears as an option character with optarg in
    290 .IR opts ,
    291 .B sgopt
    292 sets
    293 .B sgoptarg
    294 to the current position,
    295 and moves to the next cmdarg.
    296 If
    297 .B sgoptarg
    298 is nonempty,
    299 .B sgopt
    300 returns
    301 .IR c .
    302 
    303 Then
    304 .B sgopt
    305 sets
    306 .B sgoptarg
    307 to
    308 the current cmdarg.
    309 If
    310 the current cmdarg is null,
    311 or past
    312 .IR argc ,
    313 .B sgopt
    314 sets
    315 .B sgoptproblem
    316 to
    317 .I c
    318 and returns ?.
    319 Otherwise
    320 .B sgopt
    321 moves to the next
    322 argument
    323 and returns
    324 .IR c .
    325 
    326 (2)
    327 If
    328 .I c
    329 does not appear in
    330 .IR opts ,
    331 .B sgopt
    332 sets
    333 .B sgoptproblem
    334 to
    335 .I c
    336 and returns ?.
    337 .SH "SYNTAX NOTE"
    338 .B sgopt
    339 is actually a macro abbreviation for
    340 .BR subgetopt .
    341 The external
    342 .B sg
    343 variables are also macros
    344 for
    345 .BR subget .
    346 These macros are defined in
    347 .BR <subgetopt.h> ,
    348 unless
    349 .B SUBGETOPTNOSHORT
    350 is defined
    351 when
    352 .B <subgetopt.h>
    353 is included.
    354 .SH VERSION
    355 subgetopt version 0.9, 931129.
    356 .SH AUTHOR
    357 Placed into the public domain by Daniel J. Bernstein.