1 /** @file  ../include/getopt.h

     2 @internalComponent

     3 */

     4 

     5 /** @fn  getopt_long(int argc, char * const *argv, const char *optstring, const struct option *longopts, int *longindex)

     6 @param argc

     7 @param argv

     8 @param optstring

     9 @param longopts

    10 @param longindex

    11 @return   If the flag field in struct option

    12 is NULL, getopt_long returns the value specified in the val field, which is usually just the corresponding short option.

    13 If flag is not NULL, this function returns 0 and stores val in the location pointed to by flag. This function returns ' : '

    14 if there was a missing option argument, ' ? '

    15 if the user specified an unknown or ambiguous option, and

    16 -1 when the argument list has been exhausted.

    17 

    18 

    19   The getopt_long function is similar to getopt but it accepts options in two forms: words and characters.

    20 The getopt_long function provides a superset of the functionality of getopt .

    21 The getopt_long function

    22 can be used in two ways.

    23 In the first way, every long option understood

    24 by the program has a corresponding short option, and the option

    25 structure is only used to translate from long options to short

    26 options.

    27 When used in this fashion, getopt_long behaves identically to getopt .

    28 This is a good way to add long option processing to an existing program

    29 with the minimum of rewriting.

    30 

    31  In the second mechanism, a long option sets a flag in the option

    32 structure passed, or will store a pointer to the command line argument

    33 in the option

    34 structure passed to it for options that take arguments.

    35 Additionally,

    36 the long option's argument may be specified as a single argument with

    37 an equal sign, e.g.,

    38 

    39 @code

    40 myprogram --myoption=somevalue 

    41 @endcode

    42     

    43 When a long option is processed, the call to getopt_long will return 0.

    44 For this reason, long option processing without

    45 shortcuts is not backwards compatible with getopt . It is possible to combine these methods, providing for long options

    46 processing with short option equivalents for some options.

    47 Less

    48 frequently used options would be processed as long options only. The getopt_long call requires a structure to be initialized describing the long

    49 options.

    50 @code

    51 The structure is: struct option {

    52 char *name;

    53 int has_arg;

    54 int *flag;

    55 int val;

    56 };

    57 @endcode

    58  The name field should contain the option name without the leading double dash.

    59 

    60  The has_arg field should be one of:

    61 

    62  no argument no argument to the option is expect required_argument  

    63  an argument to the option is required optional_argument  an argument to the option may be presented.

    64 

    65  If flag is not NULL, then the integer pointed to by it will be set to the

    66 value in the val field.

    67 If the flag field is NULL, then the val field will be returned.

    68 Setting flag to NULL and setting val to the corresponding short option will make this function act just

    69 like getopt .

    70 

    71  If the longindex field is not NULL, then the integer pointed to by it will be set to the index of the long

    72 option relative to longopts.

    73 

    74  The last element of the longopts array has to be filled with zeroes.

    75 

    76 

    77 

    78 Examples:

    79 @code

    80 #include <unistd.h>

    81 #include <stdio.h>

    82 #include <fcntl.h>

    83 #include <getopt.h>

    84 #include <errno.h>

    85 int main()

    86 {

    87     int bflag, ch, fd;

    88     int daggerset;            

    89           

    90     int argc = 3;

    91          

    92     char *argv[] = { "getopt", "--daggerset","hi" };   

    93         

    94     struct option  longopts[] = {    

    95       { "buffy",      no_argument,            NULL,           'b' },

    96       { "fluoride",   required_argument,      NULL,           'f' },

    97       { "daggerset",  no_argument,           &daggerset;,   1 },

    98       { NULL,         0,                      NULL,           0 }       

    99     };

   100          

   101     bflag = 0;

   102        

   103     while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) {      

   104         switch (ch) {

   105           

   106                 case 'b':

   107                     printf("option is \"buffy\"

   108 ");

   109                 bflag = 1;

   110                 break;

   111                  

   112                 case 'f':

   113                     printf("option is \"fluoride\"

   114 ");

   115                 if ((fd = open(optarg, O_RDONLY, 0)) == -1)

   116                         printf("unable to open %s", optarg);

   117                 break;

   118                 

   119                 case 0:

   120                 if (daggerset) {

   121                         fprintf(stderr,"Buffy will use her dagger to apply 

   122 fluoride to dracula's teeth

   123 ");

   124                 }

   125                 break;

   126           default:

   127                 printf("unknown option

   128 ");

   129                 

   130         }//end of switch

   131     }//end of while

   132  

   133 return 0;

   134 }

   135 

   136 @endcode

   137  Output

   138 @code

   139 Buffy will use her dagger to apply fluoride to dracula's teeth

   140 

   141 @endcode

   142 @see getopt()

   143 

   144 

   145  

   146 

   147 @publishedAll

   148 @externallyDefinedApi

   149 */

   150 

   151 /** @fn  getopt(int argc, char * const argv[], const char *optstring)

   152 @param argc

   153 @param argv[]

   154 @param optstring

   155 @return   The getopt function returns the next known option character in optstring. If getopt encounters a character not found in optstring or if it detects a missing option argument, it returns ' ? ' (question mark). If optstring has a leading ' : ' then a missing option argument causes ' : ' to be returned instead of ' ?. ' In either case, the variable optopt is set to the character that caused the error. The getopt function returns -1 when the argument list is exhausted.

   156 

   157   The getopt function incrementally parses a command line argument list argv and returns the next known option character.

   158 An option character is known if it has been specified in the string of accepted option characters, optstring.

   159 

   160  The option string optstring may contain the following elements: individual characters 

   161   and characters followed by a colon to indicate an option argument is to follow. 

   162   For example, an option string x recognizes an option "- x ", and an option string x: recognizes an option and argument "- x argument. " It does not matter to getopt if a following argument has leading white space.

   163 

   164  On return from getopt, optarg points to an option argument, if it is anticipated,

   165 and the variable optind contains the index to the next argv argument for a subsequent call

   166 to getopt. The variable optopt saves the last known option character returned by getopt.

   167 

   168  The variables opterr and optind are both initialized to 1.

   169 The optind variable may be set to another value before a set of calls to getopt in order to skip over more or less argv entries.

   170 

   171  In order to use getopt to evaluate multiple sets of arguments, or to evaluate a single set of

   172 arguments multiple times,

   173 the variable optreset must be set to 1 before the second and each additional set of calls to getopt, and the variable optind must be reinitialized.

   174 

   175  The getopt function returns -1 when the argument list is exhausted.

   176 The interpretation of options in the argument list may be cancelled

   177 by the option ' -- '

   178 (double dash) which causes getopt to signal the end of argument processing and return -1.

   179 When all options have been processed (i.e., up to the first non-option

   180 argument), getopt returns -1.

   181 

   182 

   183 

   184 Examples:

   185 @code

   186 #include <unistd.h>

   187 #include <stdio.h>

   188 #include <fcntl.h>

   189 #include <errno.h>

   190 #include <string.h>

   191  

   192 int main()

   193 {

   194         int argc = 3;

   195          

   196         char *argv[] =

   197          {

   198                  "getopt","-f","hi"

   199          };

   200         

   201         int bflag, ch, fd;

   202         bflag = 0;

   203          

   204         while ((ch = getopt(argc, argv, "bf:")) != -1) {

   205         

   206         switch (ch) {

   207         case 'b':

   208                 bflag = 1;

   209                 printf("option is 'b' \n");

   210                 break;

   211         case 'f':

   212                 printf("option is 'f' \n");

   213                 if ((fd = open(optarg, O_RDONLY, 0)) != 0) {

   214                         (void)fprintf(stderr,

   215                            "myname: %s: %s\n", optarg, strerror(errno));                

   216                 }                             

   217                 break;

   218         case '?':

   219                 printf("missing option!");

   220         default:

   221                 printf("unknown option!");

   222         }

   223        

   224 }

   225 argc -= optind;

   226 return 0;

   227 }

   228 

   229 

   230 @endcode

   231  Output

   232 @code

   233 option is 'f'

   234 myname: hi: No such file or directory

   235 

   236 @endcode

   237 Diagnostics:

   238  If the getopt function encounters a character not found in the string optstring or detects

   239 a missing option argument it writes an error message to the stderr and returns ' ?. '

   240 Setting opterr to a zero will disable these error messages.

   241 If optstring has a leading ' : '

   242 then a missing option argument causes a ' : '

   243 to be returned in addition to suppressing any error messages. Option arguments are allowed to begin with "-";

   244 this is reasonable but reduces the amount of error checking possible.

   245 @see getopt_long()

   246 

   247 

   248 Bugs:

   249 

   250  The getopt function was once specified to return EOF instead of -1.

   251 This was changed by -p1003.2-92 to decouple getopt from \#include \< stdio.h \> A single dash "-" may be specified as a character in optstring, however it should never have an argument associated with it. This allows getopt to be used with programs that expect "-" as an option flag. This practice is wrong and should not be used in any 

   252   current development. It is provided for backward compatibility only. Care should be taken not to use ' - ' as the first character in optstring to avoid a semantic conflict with GNU getopt, which assigns different meaning to an optstring that begins with a ' -. ' By default, a single dash causes getopt to return -1. It is also possible to handle digits as option letters.

   253 This allows getopt to be used with programs that expect a number ("-3")

   254 as an option.

   255 This practice is wrong, and should not be used in any current development.

   256 It is provided for backward compatibility only. The following code fragment works in most cases.

   257 @code

   258 int ch;

   259 long length;

   260 char *p, *ep;

   261 while ((ch = getopt(argc, argv, "0123456789")) != -1)

   262         switch (ch) {

   263         case ’0’: case ’1’: case ’2’: case ’3’: case ’4’:

   264         case ’5’: case ’6’: case ’7’: case ’8’: case ’9’:

   265                 p = argv[optind - 1];

   266                 if (p[0] == ’-’ Am]Am] p[1] == ch Am]Am] !p[2]) {

   267                         length = ch - ’0’;

   268                         ep = "";

   269                 } else if (argv[optind] Am]Am] argv[optind][1] == ch) {

   270                         length = strtol((p = argv[optind] + 1),

   271                             Am]ep, 10);

   272                         optind++;

   273                         optreset = 1;

   274                 } else

   275                         usage();

   276                 if (*ep != ’\0’)

   277                         errx(EX_USAGE, "illegal number -- %s", p);

   278                 break;

   279         }

   280 

   281 

   282 @endcode

   283  

   284  

   285 

   286 @publishedAll

   287 @externallyDefinedApi

   288 */

   289 

   290 

   291 /** @def optopt

   292 

   293 getopt(3) external variables. character checked for validity.

   294 

   295 @publishedAll

   296 @externallyDefinedApi

   297 */

   298 

   299 /** @def opterr

   300 

   301 getopt(3) external variables. if error message should be printed.

   302 

   303 @publishedAll

   304 @externallyDefinedApi

   305 */

   306 

   307 /** @def optind

   308 

   309 getopt(3) external variables. index into parent argv vector.

   310 

   311 @publishedAll

   312 @externallyDefinedApi

   313 */

   314 

   315 /** @def optarg

   316 

   317 argument associated with option

   318 

   319 @publishedAll

   320 @externallyDefinedApi

   321 */

   322 

   323 /** @def optreset

   324 

   325 reset getopt

   326 

   327 @publishedAll

   328 @externallyDefinedApi

   329 */

   330 

   331 /** @def no_argument 

   332 

   333 no argument required

   334 

   335 @publishedAll

   336 @released

   337 */

   338 

   339 /** @def required_argument

   340 

   341 argument is required

   342 

   343 @publishedAll

   344 @released

   345 */

   346 

   347 /** @def optional_argument

   348 

   349 argument is optional

   350 

   351 @publishedAll

   352 @released

   353 */

   354 

   355 /** @struct option

   356 

   357 Includes following members,

   358 

   359 @publishedAll

   360 @released

   361 */

   362 

   363 /** @var option::name

   364 name of long option 

   365 */

   366 

   367 /** @var option::has_arg

   368 one of no_argument, required_argument, and optional_argument: whether option takes an argument

   369 */

   370 

   371 /** @var option::flag

   372 if not NULL, set flag to val when option found

   373 */

   374 

   375 /** @var option::val

   376 if flag not NULL, value to set flag to; else return value

   377 */