HP-UX Reference (11i v3 07/02) - 3 Library Functions A-M (vol 6)

g
getsubopt(3C) 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 were initially parsed by
getopt() (see
getopt(3C)). These suboptions are separated by commas, and may consist of either a single token, or a
token-value pair separated by an equal sign. Because commas delimit suboptions in the option string, they
are not allowed to be part of the suboption or the value of a suboption. Similarly, because the equal sign
separates a token from its value, a token must not contain an equals sign. An example command that uses
this syntax is
mount. mount allows parameters to be specified with the
- switch 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,
getsu-
bopt()
updates *optionp to point to the null at the end of the string, otherwise it isolates the suboption
by replacing the comma separator with a null, and updates *optionp to point to the start of the next subop-
tion. If the suboption has an associated value, getsubopt() updates *valuep to point to the value of the
first character. Otherwise it sets *valuep to NULL.
The token vector is organized as a series of pointers to NULL-terminated strings. The end of the token
vector is identified by NULL.
When getsubopt() returns, if *valuep is not NULL then the suboption processed included a value. The
calling program can 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 on to
another program.
EXTERNAL INFLUENCES
Locale
The
LC_CTYPE category determines the interpretation of option letters as single and/or multi-byte charac-
ters.
International Code Set Support
Single- and multi-byte character code sets are supported with the exception of multi-byte-character file
names.
EXAMPLES
The following code fragment shows how options can be processed to the mount command by using getsu-
bopt()
.
char *myopts[] = {
#define READONLY 0
"ro",
#define READWRITE 1
"rw",
#define WRITESIZE 2
"wsize",
#define READSIZE 3
"rsize",
NULL};
main (int argc, char **argv)
{
int sc, c, errflag;
HP-UX 11i Version 3: February 2007 − 1 − Hewlett-Packard Company 573