Man Pages

getsubopt(3p) - phpMan getsubopt(3p) - phpMan

Command: man perldoc info search(apropos)  


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 dif-
       fer (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  argu-
       ments  shall  be separated by commas and each may consist of either a single token, or a token-value pair sepa-
       rated 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  pro-
       cessed,  if  there  are  one  or  more equal signs in a suboption string, the first equal sign in any suboption
       string shall be interpreted as a separator between a token and a value. Subsequent equal signs in  a  suboption
       string shall be interpreted as part of the value.

       If  the  string  at  *optionp contains only one suboption argument (equivalently, no commas), getsubopt() shall
       update *optionp to point to the null character at the end of the string.  Otherwise, it shall isolate the  sub-
       option  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, con-
       tains  an  equal sign), getsubopt() shall update *valuep to point to the value's first character. Otherwise, it
       shall set *valuep to a null pointer. The calling application may use this information 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, Stan-
       dard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base  Specifica-
       tions  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 Stan-
       dard,  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)