Tribblix: 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