illumos: manual page: getsubopt.3c

GETSUBOPT(3C) Standard C Library Functions 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 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.
Subsequent 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.

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(8) 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