getsubopt(3C) SDK R4.11 getsubopt(3C)
NAME
getsubopt - parse suboptions from a string
SYNOPSIS
#include <stdlib.h>
int getsubopt (char **optionp, char * const *tokens, char **valuep);
DESCRIPTION
getsubopt parses suboptions in a flag argument that was initially
parsed by getopt. These suboptions are separated by commas and may
consist of either a single token or a token-value pair separated by
an equal sign. Since commas delimit suboptions in the option string,
they are not allowed to be part of the suboption or the value of a
suboption. A command that uses this syntax is mount(1M), which
allows the user to specify mount parameters with the -o option as
follows:
mount -o rw,hard,bg,wsize=1024 speed:/usr /usr
In this example there are four suboptions: rw, hard, bg, and wsize,
the last of which has an associated value of 1024.
getsubopt takes the address of a pointer to the option string, a
vector of possible tokens, and the address of a value string pointer.
It returns the index of the token that matched the suboption in the
input string or -1 if there was no match. If the option string at
optionp contains only one suboption, getsubopt updates optionp to
point to the null character at the end of the string; otherwise it
isolates the suboption by replacing the comma separator with a null
character, and updates optionp to point to the start of the next
suboption. If the suboption has an associated value, getsubopt
updates valuep to point to the value's first character. Otherwise it
sets valuep to NULL.
The token vector is organized as a series of pointers to null
strings. The end of the token vector is identified by a null
pointer.
When getsubopt returns, if valuep is not NULL, then the suboption
processed included a value. The calling program may use this
information to determine if the presence or lack of a value for this
suboption is an error.
Additionally, when getsubopt fails to match the suboption with the
tokens in the tokens array, the calling program should decide if this
is an error, or if the unrecognized option should be passed to
another program.
Considerations for Threads Programming
+----------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+----------+-----------------------------+
|getsubopt | Y N N |
+----------+-----------------------------+
optarg, optind, opterr and optopt are global to all threads in a
process. Changes to this information occurs immediately for all
threads in a process. getopt calls should be made when other threads
will not be impacted by the call or can handle a change in the getopt
extern variables.
EXAMPLE
The following code fragment shows how to process options to the mount
command 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) {
errornoarg();
errflag++;
} else
writesize = atoi(value);
break;
case READSIZE : /* process rsize option */
if (value == NULL) {
errornoarg();
errflag++;
} else
readsize = atoi(value);
break;
default :
/* process unknown token */
errorbadtoken(value);
errflag++;
break;
}
}
break;
}
}
if (errflag) {
/* print usage instructions etc. */
}
for (; optind<argc; optind++) {
/* process remaining arguments */
}
.
.
.
}
SEE ALSO
reentrant(3), getopt(3C).
DIAGNOSTICS
getsubopt returns -1 when the token it is scanning is not in the
token vector. The variable addressed by valuep contains a pointer to
the first character of the token that was not recognized rather than
a pointer to a value for that token.
The variable addressed by optionp points to the next option to be
parsed, or a null character if there are no more options.
NOTES
During parsing, commas in the option input string are changed to null
characters. White space in tokens or token-value pairs must be
protected from the shell by quotes.
Licensed material--property of copyright holder(s)