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.