GETSUBOPT(3P) - phpMan

GETSUBOPT(3P)              POSIX Programmer's Manual             GETSUBOPT(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
NAME
       getsubopt - parse suboption arguments from a string
SYNOPSIS
       #include <stdlib.h>
       int getsubopt(char **optionp, char * const *keylistp, char **valuep);

DESCRIPTION
       The getsubopt() function shall parse  suboption  arguments  in  a  flag
       argument. Such options often result from the use of getopt().
       The  getsubopt()  argument  optionp  is  a  pointer to a pointer to the
       option argument string. The suboption arguments shall be  separated  by
       commas  and each may consist of either a single token, or a token-value
       pair separated by an equal sign.
       The keylistp argument shall be a pointer to a vector of  strings.   The
       end  of  the vector is identified by a null pointer.  Each entry in the
       vector is one of the possible tokens that might be found  in  *optionp.
       Since  commas  delimit  suboption arguments in optionp, they should not
       appear in any of the strings pointed to by keylistp. Similarly, because
       an  equal sign separates a token from its value, the application should
       not include an equal sign in any of the strings pointed to by keylistp.
       The valuep argument is the address of a value string pointer.
       If a comma appears in optionp, it shall be interpreted as  a  suboption
       separator.  After  commas have been processed, if there are one or more
       equal signs in a suboption string, the first equal sign in  any  subop-
       tion  string  shall be interpreted as a separator between a token and a
       value. Subsequent equal signs in a suboption  string  shall  be  inter-
       preted as part of the value.
       If the string at *optionp contains only one suboption argument (equiva-
       lently, no commas), getsubopt() shall update *optionp to point  to  the
       null  character  at the end of the string.  Otherwise, it shall isolate
       the suboption argument by replacing the comma  separator  with  a  null
       character,  and shall update *optionp to point to the start of the next
       suboption argument. If the suboption argument has an  associated  value
       (equivalently,  contains an equal sign), getsubopt() shall update *val-
       uep to point to the value's first character. Otherwise,  it  shall  set
       *valuep  to a null pointer. The calling application may use this infor-
       mation to determine whether the presence or absence of a value for  the
       suboption is an error.
       Additionally,  when  getsubopt()  fails to match the suboption argument
       with a token in the keylistp  array,  the  calling  application  should
       decide  if  this  is  an error, or if the unrecognized option should be
       processed in another way.
RETURN VALUE
       The getsubopt() function shall return the index of  the  matched  token
       string, or -1 if no token strings were matched.
ERRORS
       No errors are defined.
       The following sections are informative.
EXAMPLES
              #include <stdio.h>
              #include <stdlib.h>

              int do_all;
              const char *type;
              int read_size;
              int write_size;
              int read_only;

              enum
              {
                  RO_OPTION = 0,
                  RW_OPTION,
                  READ_SIZE_OPTION,
                  WRITE_SIZE_OPTION
              };

              const char *mount_opts[] =
              {
                  [RO_OPTION] = "ro",
                  [RW_OPTION] = "rw",
                  [READ_SIZE_OPTION] = "rsize",
                  [WRITE_SIZE_OPTION] = "wsize",
                  NULL
              };

              int
              main(int argc, char *argv[])
              {
                  char *subopts, *value;
                  int opt;

                  while ((opt = getopt(argc, argv, "at:o:")) != -1)
                      switch(opt)
                          {
                          case 'a':
                              do_all = 1;
                              break;
                          case 't':
                              type = optarg;
                              break;
                          case 'o':
                              subopts = optarg;
                              while (*subopts != '\0')
                                  switch(getsubopt(&subopts, mount_opts, &value))
                              {
                              case RO_OPTION:
                                  read_only = 1;
                                  break;
                              case RW_OPTION:
                                  read_only = 0;
                                  break;
                              case READ_SIZE_OPTION:
                                  if (value == NULL)
                                      abort();
                                  read_size = atoi(value);
                                  break;
                              case WRITE_SIZE_OPTION:
                                  if (value == NULL)
                                      abort();
                                  write_size = atoi(value);
                                  break;
                              default:
                                  /* Unknown suboption. */
                                  printf("Unknown suboption `%s'\n", value);
                                  break;
                              }
                          break;
                      default:
                          abort();
                      }

                  /* Do the real work. */

                  return 0;
              }
   Parsing Suboptions
       The  following  example  uses the getsubopt() function to parse a value
       argument in  the  optarg  external  variable  returned  by  a  call  to
       getopt().

              #include <stdlib.h>
              ...
              char *tokens[] = {"HOME", "PATH", "LOGNAME", (char *) NULL };
              char *value;
              int opt, index;

              while ((opt = getopt(argc, argv, "e:")) != -1) {
                  switch(opt)  {
                  case 'e' :
                      while ((index = getsubopt(&optarg, tokens, &value)) != -1) {
                          switch(index) {
              ...
                      }
                      break;
              ...
                  }
              }
              ...
APPLICATION USAGE
       None.
RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       getopt(),   the   Base   Definitions  volume  of  IEEE Std 1003.1-2001,
       <stdlib.h>
COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                        GETSUBOPT(3P)