getsubopt man page on RedHat

Man page or keyword search:  
man Server   29550 pages
apropos Keyword Search (all sections)
Output format
RedHat logo
[printable version]

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)
[top]

List of man pages available for RedHat

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net