Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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);

       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.

       The getsubopt() function	returns	the index of the matched token	string
       or -1 if	no token strings were matched.

       No errors are defined.

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

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

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

				  29 Sep 2005			 getsubopt(3C)

NAME | SYNOPSIS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getsubopt&sektion=3c&manpath=SunOS+5.10>

home | help