Unix/Linux Go Back    


Linux 2.6 - man page for getsubopt (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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 sin-
       gle 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 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 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 *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, 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				     GETSUBOPT(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 07:47 AM.