sl@0: /** @file  ../include/getopt.h
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: /** @fn  getopt_long(int argc, char * const *argv, const char *optstring, const struct option *longopts, int *longindex)
sl@0: @param argc
sl@0: @param argv
sl@0: @param optstring
sl@0: @param longopts
sl@0: @param longindex
sl@0: @return   If the flag field in struct option
sl@0: is NULL, getopt_long returns the value specified in the val field, which is usually just the corresponding short option.
sl@0: If flag is not NULL, this function returns 0 and stores val in the location pointed to by flag. This function returns ' : '
sl@0: if there was a missing option argument, ' ? '
sl@0: if the user specified an unknown or ambiguous option, and
sl@0: -1 when the argument list has been exhausted.
sl@0: 
sl@0: 
sl@0:   The getopt_long function is similar to getopt but it accepts options in two forms: words and characters.
sl@0: The getopt_long function provides a superset of the functionality of getopt .
sl@0: The getopt_long function
sl@0: can be used in two ways.
sl@0: In the first way, every long option understood
sl@0: by the program has a corresponding short option, and the option
sl@0: structure is only used to translate from long options to short
sl@0: options.
sl@0: When used in this fashion, getopt_long behaves identically to getopt .
sl@0: This is a good way to add long option processing to an existing program
sl@0: with the minimum of rewriting.
sl@0: 
sl@0:  In the second mechanism, a long option sets a flag in the option
sl@0: structure passed, or will store a pointer to the command line argument
sl@0: in the option
sl@0: structure passed to it for options that take arguments.
sl@0: Additionally,
sl@0: the long option's argument may be specified as a single argument with
sl@0: an equal sign, e.g.,
sl@0: 
sl@0: @code
sl@0: myprogram --myoption=somevalue 
sl@0: @endcode
sl@0:     
sl@0: When a long option is processed, the call to getopt_long will return 0.
sl@0: For this reason, long option processing without
sl@0: shortcuts is not backwards compatible with getopt . It is possible to combine these methods, providing for long options
sl@0: processing with short option equivalents for some options.
sl@0: Less
sl@0: frequently used options would be processed as long options only. The getopt_long call requires a structure to be initialized describing the long
sl@0: options.
sl@0: @code
sl@0: The structure is: struct option {
sl@0: char *name;
sl@0: int has_arg;
sl@0: int *flag;
sl@0: int val;
sl@0: };
sl@0: @endcode
sl@0:  The name field should contain the option name without the leading double dash.
sl@0: 
sl@0:  The has_arg field should be one of:
sl@0: 
sl@0:  no argument no argument to the option is expect required_argument  
sl@0:  an argument to the option is required optional_argument  an argument to the option may be presented.
sl@0: 
sl@0:  If flag is not NULL, then the integer pointed to by it will be set to the
sl@0: value in the val field.
sl@0: If the flag field is NULL, then the val field will be returned.
sl@0: Setting flag to NULL and setting val to the corresponding short option will make this function act just
sl@0: like getopt .
sl@0: 
sl@0:  If the longindex field is not NULL, then the integer pointed to by it will be set to the index of the long
sl@0: option relative to longopts.
sl@0: 
sl@0:  The last element of the longopts array has to be filled with zeroes.
sl@0: 
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <unistd.h>
sl@0: #include <stdio.h>
sl@0: #include <fcntl.h>
sl@0: #include <getopt.h>
sl@0: #include <errno.h>
sl@0: int main()
sl@0: {
sl@0:     int bflag, ch, fd;
sl@0:     int daggerset;            
sl@0:           
sl@0:     int argc = 3;
sl@0:          
sl@0:     char *argv[] = { "getopt", "--daggerset","hi" };   
sl@0:         
sl@0:     struct option  longopts[] = {    
sl@0:       { "buffy",      no_argument,            NULL,           'b' },
sl@0:       { "fluoride",   required_argument,      NULL,           'f' },
sl@0:       { "daggerset",  no_argument,           &daggerset;,   1 },
sl@0:       { NULL,         0,                      NULL,           0 }       
sl@0:     };
sl@0:          
sl@0:     bflag = 0;
sl@0:        
sl@0:     while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) {      
sl@0:         switch (ch) {
sl@0:           
sl@0:                 case 'b':
sl@0:                     printf("option is \"buffy\"
sl@0: ");
sl@0:                 bflag = 1;
sl@0:                 break;
sl@0:                  
sl@0:                 case 'f':
sl@0:                     printf("option is \"fluoride\"
sl@0: ");
sl@0:                 if ((fd = open(optarg, O_RDONLY, 0)) == -1)
sl@0:                         printf("unable to open %s", optarg);
sl@0:                 break;
sl@0:                 
sl@0:                 case 0:
sl@0:                 if (daggerset) {
sl@0:                         fprintf(stderr,"Buffy will use her dagger to apply 
sl@0: fluoride to dracula's teeth
sl@0: ");
sl@0:                 }
sl@0:                 break;
sl@0:           default:
sl@0:                 printf("unknown option
sl@0: ");
sl@0:                 
sl@0:         }//end of switch
sl@0:     }//end of while
sl@0:  
sl@0: return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  Output
sl@0: @code
sl@0: Buffy will use her dagger to apply fluoride to dracula's teeth
sl@0: 
sl@0: @endcode
sl@0: @see getopt()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  getopt(int argc, char * const argv[], const char *optstring)
sl@0: @param argc
sl@0: @param argv[]
sl@0: @param optstring
sl@0: @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.
sl@0: 
sl@0:   The getopt function incrementally parses a command line argument list argv and returns the next known option character.
sl@0: An option character is known if it has been specified in the string of accepted option characters, optstring.
sl@0: 
sl@0:  The option string optstring may contain the following elements: individual characters 
sl@0:   and characters followed by a colon to indicate an option argument is to follow. 
sl@0:   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.
sl@0: 
sl@0:  On return from getopt, optarg points to an option argument, if it is anticipated,
sl@0: and the variable optind contains the index to the next argv argument for a subsequent call
sl@0: to getopt. The variable optopt saves the last known option character returned by getopt.
sl@0: 
sl@0:  The variables opterr and optind are both initialized to 1.
sl@0: 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.
sl@0: 
sl@0:  In order to use getopt to evaluate multiple sets of arguments, or to evaluate a single set of
sl@0: arguments multiple times,
sl@0: 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.
sl@0: 
sl@0:  The getopt function returns -1 when the argument list is exhausted.
sl@0: The interpretation of options in the argument list may be cancelled
sl@0: by the option ' -- '
sl@0: (double dash) which causes getopt to signal the end of argument processing and return -1.
sl@0: When all options have been processed (i.e., up to the first non-option
sl@0: argument), getopt returns -1.
sl@0: 
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <unistd.h>
sl@0: #include <stdio.h>
sl@0: #include <fcntl.h>
sl@0: #include <errno.h>
sl@0: #include <string.h>
sl@0:  
sl@0: int main()
sl@0: {
sl@0:         int argc = 3;
sl@0:          
sl@0:         char *argv[] =
sl@0:          {
sl@0:                  "getopt","-f","hi"
sl@0:          };
sl@0:         
sl@0:         int bflag, ch, fd;
sl@0:         bflag = 0;
sl@0:          
sl@0:         while ((ch = getopt(argc, argv, "bf:")) != -1) {
sl@0:         
sl@0:         switch (ch) {
sl@0:         case 'b':
sl@0:                 bflag = 1;
sl@0:                 printf("option is 'b' \n");
sl@0:                 break;
sl@0:         case 'f':
sl@0:                 printf("option is 'f' \n");
sl@0:                 if ((fd = open(optarg, O_RDONLY, 0)) != 0) {
sl@0:                         (void)fprintf(stderr,
sl@0:                            "myname: %s: %s\n", optarg, strerror(errno));                
sl@0:                 }                             
sl@0:                 break;
sl@0:         case '?':
sl@0:                 printf("missing option!");
sl@0:         default:
sl@0:                 printf("unknown option!");
sl@0:         }
sl@0:        
sl@0: }
sl@0: argc -= optind;
sl@0: return 0;
sl@0: }
sl@0: 
sl@0: 
sl@0: @endcode
sl@0:  Output
sl@0: @code
sl@0: option is 'f'
sl@0: myname: hi: No such file or directory
sl@0: 
sl@0: @endcode
sl@0: Diagnostics:
sl@0:  If the getopt function encounters a character not found in the string optstring or detects
sl@0: a missing option argument it writes an error message to the stderr and returns ' ?. '
sl@0: Setting opterr to a zero will disable these error messages.
sl@0: If optstring has a leading ' : '
sl@0: then a missing option argument causes a ' : '
sl@0: to be returned in addition to suppressing any error messages. Option arguments are allowed to begin with "-";
sl@0: this is reasonable but reduces the amount of error checking possible.
sl@0: @see getopt_long()
sl@0: 
sl@0: 
sl@0: Bugs:
sl@0: 
sl@0:  The getopt function was once specified to return EOF instead of -1.
sl@0: 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 
sl@0:   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.
sl@0: This allows getopt to be used with programs that expect a number ("-3")
sl@0: as an option.
sl@0: This practice is wrong, and should not be used in any current development.
sl@0: It is provided for backward compatibility only. The following code fragment works in most cases.
sl@0: @code
sl@0: int ch;
sl@0: long length;
sl@0: char *p, *ep;
sl@0: while ((ch = getopt(argc, argv, "0123456789")) != -1)
sl@0:         switch (ch) {
sl@0:         case ’0’: case ’1’: case ’2’: case ’3’: case ’4’:
sl@0:         case ’5’: case ’6’: case ’7’: case ’8’: case ’9’:
sl@0:                 p = argv[optind - 1];
sl@0:                 if (p[0] == ’-’ Am]Am] p[1] == ch Am]Am] !p[2]) {
sl@0:                         length = ch - ’0’;
sl@0:                         ep = "";
sl@0:                 } else if (argv[optind] Am]Am] argv[optind][1] == ch) {
sl@0:                         length = strtol((p = argv[optind] + 1),
sl@0:                             Am]ep, 10);
sl@0:                         optind++;
sl@0:                         optreset = 1;
sl@0:                 } else
sl@0:                         usage();
sl@0:                 if (*ep != ’\0’)
sl@0:                         errx(EX_USAGE, "illegal number -- %s", p);
sl@0:                 break;
sl@0:         }
sl@0: 
sl@0: 
sl@0: @endcode
sl@0:  
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @def optopt
sl@0: 
sl@0: getopt(3) external variables. character checked for validity.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def opterr
sl@0: 
sl@0: getopt(3) external variables. if error message should be printed.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def optind
sl@0: 
sl@0: getopt(3) external variables. index into parent argv vector.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def optarg
sl@0: 
sl@0: argument associated with option
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def optreset
sl@0: 
sl@0: reset getopt
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def no_argument 
sl@0: 
sl@0: no argument required
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @def required_argument
sl@0: 
sl@0: argument is required
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @def optional_argument
sl@0: 
sl@0: argument is optional
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @struct option
sl@0: 
sl@0: Includes following members,
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 
sl@0: /** @var option::name
sl@0: name of long option 
sl@0: */
sl@0: 
sl@0: /** @var option::has_arg
sl@0: one of no_argument, required_argument, and optional_argument: whether option takes an argument
sl@0: */
sl@0: 
sl@0: /** @var option::flag
sl@0: if not NULL, set flag to val when option found
sl@0: */
sl@0: 
sl@0: /** @var option::val
sl@0: if flag not NULL, value to set flag to; else return value
sl@0: */