getsubopt(3C) Standard C Library Functions getsubopt(3C)NAMEgetsubopt - 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 ALSOmount(1M), getopt(3C), attributes(5), standards(5)SunOS 5.10 29 Sep 2005 getsubopt(3C)
