getsubopt(3) [bsd man page]
GETSUBOPT(3) Library Functions Manual GETSUBOPT(3) NAME
getsubopt - get sub options from an argument SYNOPSIS
#include <stdlib.h> extern char *suboptarg int getsubopt(optionp, tokens, valuep) char **optionp; char **tokens; char **valuep; DESCRIPTION
The getsubopt() function parses a string containing tokens delimited by one or more tab, space or comma (`,') characters. It is intended for use in parsing groups of option arguments provided as part of a utility command line. The argument optionp is a pointer to a pointer to the string. The argument tokens is a pointer to a NULL-terminated array of pointers to strings. The getsubopt() function returns the zero-based offset of the pointer in the tokens array referencing a string which matches the first token in the string, or, -1 if the string contains no tokens or tokens does not contain a matching string. If the token is of the form ``name=value'', the location referenced by valuep will be set to point to the start of the ``value'' portion of the token. On return from getsubopt(), optionp will be set to point to the start of the next token in the string, or the null at the end of the string if no more tokens are present. The external variable suboptarg will be set to point to the start of the current token, or NULL if no tokens were present. The argument valuep will be set to point to the ``value'' portion of the token, or NULL if no ``value'' portion was present. EXAMPLE
char *tokens[] = { #define ONE 0 "one", #define TWO 1 "two", NULL }; ... extern char *optarg, *suboptarg; char *options, *value; while ((ch = getopt(argc, argv, "ab:")) != -1) { switch(ch) { case 'a': /* process ``a'' option */ break; case 'b': options = optarg; while (*options) { switch(getsubopt(&options, tokens, &value)) { case ONE: /* process ``one'' sub option */ break; case TWO: /* process ``two'' sub option */ if (!value) error("no value for two"); i = atoi(value); break; case -1: if (suboptarg) error("illegal sub option %s", suboptarg); else error("missing sub option"); break; } break; } SEE ALSO
getopt(3), strsep(3) HISTORY
The getsubopt() function first appeared in 4.4BSD. 4.4 Berkeley Distribution January 12, 1996 GETSUBOPT(3)
Check Out this Related Man Page
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 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 is 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 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 (equivalently, no commas), getsubopt() updates *optionp to point to the null character at the end of the string. Otherwise, it isolates the suboption argument by replacing the comma separator with a null character and updates *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() 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 != ' ') { 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)