getsubopt man page on SmartOS

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

GETSUBOPT(3C)							 GETSUBOPT(3C)

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 parses suboption arguments in a flag argument.
       Such options often result from the use of getopt(3C).

       The getsubopt() argument optionp is a  pointer  to  a  pointer  to  the
       option argument string. The suboption arguments are separated by commas
       and each can consist of either a single token  or  a  token-value  pair
       separated by an equal sign.

       The  keylistp  argument is 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 com‐
       mas 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 is interpreted as a suboption separa‐
       tor. 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 is interpreted as a separator between a token and a value.  Sub‐
       sequent	equal  signs  in a suboption string are interpreted as part of
       the value.

       If the string at *optionp contains only one suboption argument (equiva‐
       lently,	no  commas), getsubopt() updates *optionp to point to the null
       character at the end of the string. Otherwise, it isolates  the	subop‐
       tion  argument  by  replacing the comma separator with a null character
       and updates *optionp to point to the start of the next suboption	 argu‐
       ment.  If the suboption argument has an associated value (equivalently,
       contains an equal sign), getsubopt() updates *valuep to	point  to  the
       value's	first character. Otherwise, it sets *valuep to a null pointer.
       The calling application can 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 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 VALUES
       The getsubopt() function returns the index of the matched token	string
       or -1 if no token strings were matched.

ERRORS
       No errors are defined.

EXAMPLES
       Example 1 Use getsubopt() to process options.

       The  following  example	demonstrates  the processing of options to the
       mount(1M) utility using getsubopt().

	 #include <stdlib.h>

	 char *myopts[] = {
	 #define READONLY     0
		     "ro",
	 #define READWRITE    1
		     "rw",
	 #define WRITESIZE    2
		     "wsize",
	 #define READSIZE     3
		     "rsize",
		     NULL};

	 main(argc, argv)
	     int  argc;
	     char **argv;
	 {
	     int sc, c, errflag;
	     char *options, *value;
	     extern char *optarg;
	     extern int optind;
	     .
	     .
	     .
	     while((c = getopt(argc, argv, "abf:o:")) != -1) {
		 switch (c) {
		 case 'a': /* process a option */
		     break;
		 case 'b': /* process b option */
		     break;
		 case 'f':
		     ofile = optarg;
		     break;
		 case '?':
		     errflag++;
		     break;
		 case 'o':
		     options = optarg;
		     while (*options != '\0') {
			 switch(getsubopt(&options,myopts,&value)){
			 case READONLY : /* process ro option */
			     break;
			 case READWRITE : /* process rw option */
			     break;
			 case WRITESIZE : /* process wsize option */
			     if (value == NULL) {
				 error_no_arg();
				 errflag++;
			     } else
				 write_size = atoi(value);
			     break;
			 case READSIZE : /* process rsize option */
			     if (value == NULL) {
				 error_no_arg();
				 errflag++;
			     } else
				 read_size = atoi(value);
			     break;
			 default :
			     /* process unknown token */
			     error_bad_token(value);
			     errflag++;
			     break;
			    }
		     }
		       break;
		 }
	     }
	     if (errflag) {
		 /* print usage instructions etc. */
	     }
	     for (; optind<argc; optind++) {
		 /* process remaining arguments */
	     }
	     .
	     .
	     .
	 }

       Example 2 Parse suboptions.

       The following example uses the getsubopt() function to  parse  a	 value
       argument	 in  the  optarg  external  variable  returned	by  a  call to
       getopt(3C).

	 #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;
	 ...
	     }
	 }

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Standard	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ MT-Safe	      │
       └────────────────────┴─────────────────┘

SEE ALSO
       mount(1M), getopt(3C), attributes(5), standards(5)

				 Sep 29, 2005			 GETSUBOPT(3C)
[top]

List of man pages available for SmartOS

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