1 GETOPT_LONG(3C)          Standard C Library Functions          GETOPT_LONG(3C)
   2 
   3 NAME
   4      getopt_long, getopt_long_only - get long options from command line
   5      argument list
   6 
   7 SYNOPSIS
   8      #include <getopt.h>
   9 
  10      extern char *optarg;
  11      extern int optind;
  12      extern int optopt;
  13      extern int opterr;
  14 
  15      int
  16      getopt_long(int argc, char * const *argv, const char *optstring,
  17          const struct option *longopts, int *longindex);
  18 
  19      int
  20      getopt_long_only(int argc, char * const *argv, const char *optstring,
  21          const struct option *longopts, int *longindex);
  22 
  23      int
  24      getopt_long_clip(int argc, char * const *argv, const char *optstring,
  25          const struct option *longopts, int *longindex);
  26 
  27 DESCRIPTION
  28      The getopt_long() function is similar to getopt(3C) but it accepts
  29      options in two forms: words and characters.  The getopt_long() function
  30      provides a superset of the functionality of getopt(3C).  The
  31      getopt_long() function can be used in two ways.
  32 
  33      In the first way, every long option understood by the program has a
  34      corresponding short option, and the option structure is only used to
  35      translate from long options to short options.  When used in this fashion,
  36      getopt_long() behaves identically to getopt(3C).  This is a good way to
  37      add long option processing to an existing program with the minimum of
  38      rewriting.
  39 
  40      In the second mechanism, a long option sets a flag in the option
  41      structure passed, or will store a pointer to the command line argument in
  42      the option structure passed to it for options that take arguments.
  43      Additionally, the long option's argument may be specified as a single
  44      argument with an equal sign, e.g.,
  45 
  46            myprogram --myoption=somevalue
  47 
  48      When a long option is processed, the call to getopt_long() will return 0.
  49      For this reason, long option processing without shortcuts is not
  50      backwards compatible with getopt(3C).
  51 
  52      It is possible to combine these methods, providing for long options
  53      processing with short option equivalents for some options.  Less
  54      frequently used options would be processed as long options only.
  55 
  56      In getopt_long() and getopt_long_only(), optstring acts similar to
  57      optstring in getopt(3C).  In addition, optstring can begin with `+' or
  58      `-'.  If optstring begins with `+', the first non-option terminates
  59      option processing.  This is equivalent to setting the environment
  60      variable POSIXLY_CORRECT.  If optstring begins with `-', non-options are
  61      treated as options to the argument `\1'.
  62 
  63      If optstring does not begin with `+' and POSIXLY_CORRECT is not set, if
  64      `W;' appears in optstring, `-W myoption' is treated the same as
  65      `--myoption' and optarg is set to `myoption'.
  66 
  67      In getopt_long_clip(), `+' and `-' are ignored at the beginning of a
  68      string.
  69 
  70      The getopt_long(), getopt_long_only(), and getopt_long_clip() functions
  71      require a structure to be initialized describing the long options.  The
  72      structure is:
  73 
  74            struct option {
  75                    char *name;
  76                    int has_arg;
  77                    int *flag;
  78                    int val;
  79            };
  80 
  81      The name field should contain the option name without the leading double
  82      dash.
  83 
  84      The has_arg field should be one of:
  85 
  86            no_argument            no argument to the option is expected
  87            required_argument      an argument to the option is required
  88            optional_argument      an argument to the option may be presented
  89 
  90      If flag is not NULL, then the integer pointed to by it will be set to the
  91      value in the val field and optopt will be set to 0.  If the flag field is
  92      NULL, then the val field will be returned and optopt is set to the value
  93      in the val field.  Setting flag to NULL and setting val to the
  94      corresponding short option will make this function act just like
  95      getopt(3C).
  96 
  97      If the longindex field is not NULL, then the integer pointed to by it
  98      will be set to the index of the long option relative to longopts.
  99 
 100      The last element of the longopts array has to be filled with zeroes.
 101 
 102      The getopt_long_only() function behaves identically to getopt_long() with
 103      the exception that long options may start with `-' in addition to `--'.
 104      If an option starting with `-' does not match a long option but does
 105      match a single-character option, the single-character option is returned.
 106 
 107      The getopt_long_clip() function is a variation of getopt_long() except
 108      that options must also adhere to the Sun CLIP specification.
 109      Specifically, the major differences from getopt_long() are:
 110 
 111            o   All option arguments are required (optional_argument is treated
 112                the same as required_argument).
 113 
 114            o   Long options cannot be abbreviated on the command line.
 115 
 116            o   Long options must use a double dash (`--').
 117 
 118            o   Option processing stops at the first non-option.
 119 
 120            o   All long options must have an eqivalent short option (single
 121                character) and vice-versa.
 122 
 123            o   A leading `+' or `-' in optstring is ignored.  optstring is
 124                treated as if it began after the leading `+' or `-'.
 125 
 126      On each call to getopt_long(), getopt_long_only(), or getopt_long(),
 127      optind is set to the argv index of the next argument to be processed.
 128      optind is initialized to 1 prior to the first invocation of
 129      getopt_long(), getopt_long_only(), or getopt_long_clip().
 130 
 131      If opterr is set to a non-zero value and optstring does not start with
 132      `:', getopt_long(), getopt_long_only(), and getopt_long_clip() will print
 133      an error message to stderr when an error or invalid option is
 134      encountered.
 135 
 136 RETURN VALUES
 137      If the flag field in struct option is NULL, getopt_long() and
 138      getopt_long_only() return the value specified in the val field, which is
 139      usually just the corresponding short option.  If flag is not NULL, these
 140      functions return 0 and store val in the location pointed to by flag.
 141      These functions return `:' if there was a missing option argument, `?' if
 142      the user specified an unknown or ambiguous option, and -1 when the
 143      argument list has been exhausted.
 144 
 145      If a long option to getopt_long_clip() is missing its equivalent short
 146      option (or vice-versa),-1 is returned on the first call to
 147      getopt_long_clip(), and errno is set to EINVAL.  If opterr is set to a
 148      non-zero value and optstring does not start with `:', an error message
 149      will be written to stderr.
 150 
 151      If optstring does not start with `:' and getopt_long(),
 152      getopt_long_only(), or getopt_long_clip() return `:' or `?', if opterr is
 153      set to a non-zero value, an error message is written to stderr.
 154 
 155 ENVIRONMENT
 156      The following environment variables can effect the execution of
 157      getopt_long, getopt_long_only, and getopt_long_clip: LANG, LC_ALL,
 158      LC_MESSAGES.  See environ(5).
 159 
 160      POSIXLY_CORRECT      If set, option processing stops when the first non-
 161                           option is found and a leading `-' or `+' in the
 162                           optstring is ignored.
 163 
 164 USAGE
 165      Similar to getopt(3C), since there is no unambiguous way to detect a
 166      missing option-argument except when the option is the last option on the
 167      command line, the getopt_long(), getopt_long_only(), and
 168      getopt_long_clip() functions cannot fully check for mandatory arguments.
 169      For example, the option string `ho:' with an input of `-o -h' will assume
 170      that `-h' is the required argument to -o instead of assuming that -o is
 171      missing its option-argument.
 172 
 173      Like getopt(3C), grouping options taking or requiring arguments with
 174      other options is a violation of the Basic Utility Command syntax standard
 175      (see Intro(1)).  For example, given the option string `cde:', running:
 176 
 177            cmd -cde ieio
 178 
 179      is incorrect.  Current versions of getopt_long, getopt_long_only, and
 180      getopt_long_clip accept this, however future versions may not support
 181      this.  The correct invocation would be:
 182 
 183            cmd -cd -e ieio
 184 
 185 EXAMPLES
 186      int bflag, ch, fd;
 187      int daggerset;
 188 
 189      /* options descriptor */
 190      static struct option longopts[] = {
 191              { "buffy",      no_argument,            NULL,           'b' },
 192              { "fluoride",   required_argument,      NULL,           'f' },
 193              { "daggerset",  no_argument,            &daggerset,     1 },
 194              { NULL,         0,                      NULL,           0 }
 195      };
 196 
 197      bflag = 0;
 198      while ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) {
 199              switch (ch) {
 200              case 'b':
 201                      bflag = 1;
 202                      break;
 203              case 'f':
 204                      if ((fd = open(optarg, O_RDONLY, 0)) == -1)
 205                              err(1, "unable to open %s", optarg);
 206                      break;
 207              case 0:
 208                      if (daggerset) {
 209                              fprintf(stderr,"Buffy will use her dagger to "
 210                                  "apply fluoride to dracula's teeth\n");
 211                      }
 212                      break;
 213              default:
 214                      usage();
 215              }
 216      }
 217      argc -= optind;
 218      argv += optind;
 219 
 220 ERRORS
 221      The getopt_long_clip() function will fail if:
 222 
 223      EINVAL  A short option is missing a corresponding long option, or vice-
 224              versa.
 225 
 226      There are no errors defined for getopt_long() and getopt_long_only().
 227 
 228 IMPLEMENTATION DIFFERENCES
 229      While the illumos implementations of getopt_long and getopt_long_only are
 230      broadly compatible with other implementations, the following edge cases
 231      have historically been known to vary among implementations:
 232 
 233      o   The setting of optopt for long options with flag != NULL in struct
 234          option.  In illumos, optopt is set to 0 (since val would never be
 235          returned).
 236 
 237      o   The setting of optarg for long options without an argument that are
 238          invoked via `-W' (`W;' in optstring).  illumos sets optarg to the
 239          option name (the argument of `-W').
 240 
 241      o   The handling of `-W' with an argument that is not (a prefix to) a
 242          known long option (`W;' in optstring).  illumos treats this as an
 243          error (unknown option) and returns `?' with optopt set to 0 and
 244          optarg set to NULL.
 245 
 246      o   illumos may not permute the argument vector at the same points in the
 247          calling sequence as other implementations.  The aspects normally used
 248          by the caller (ordering after -1 is returned, the value of optind
 249          relative to current positions) are the same, though.  (We often do
 250          fewer variable swaps.)
 251 
 252 INTERFACE STABILITY
 253      Committed
 254 
 255 MT-LEVEL
 256      Unsafe
 257 
 258 SEE ALSO
 259      getopt(3C)
 260 
 261 BUGS
 262      The argv argument is not really const as its elements may be permuted
 263      (unless POSIXLY_CORRECT is set).
 264 
 265 illumos                          July 17, 2018                         illumos