getsubopt() — Parse suboption arguments
Standards
| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
XPG4.2
Single UNIX Specification, Version 3 |
both |
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <stdlib.h>
int getsubopt(char **optionp, char *const *tokens, char **valuep);General description
The getsubopt() function parses suboption arguments in a flag argument that was initially parsed by getopt(). These suboption arguments must be separated by commas and may consist of either a single token, or a token-value pair separated by an equal sign. Because commas delimit suboption arguments in the option string, they are not allowed to be part of the suboption arguments or the value of a suboption argument. Similarly, because the equal sign separates a token from its value, a token must not contain an equal sign.
The getsubopt() function takes the address of a pointer to the option argument string, a vector of possible tokens, and the address of a value string pointer. If the option argument string at optionp contains only one suboption argument, getsubopt() updates optionp to point to the NULL at the end of the string. Otherwise, it isolates the suboption argument by replacing the comma separator with a NULL, and updates optionp to point to the start of the next suboption argument. If the suboption argument has an associated value, getsubopt() updates valuep to point to the value's first character. Otherwise it sets valuep to a NULL pointer.
The token vector is organized as a series of pointers to strings. The end of the token vector is identified by a NULL pointer.
When getsubopt() returns, if valuep is not a NULL pointer, then the suboption argument processed included a value. The calling program may use this information to determine if the presence or lack of a value for the suboption is an error.
Additionally, when getsubopt() fails to match the suboption argument 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.
Because the getsubopt() function returns thread-specific data the getsubopt() function can be used safely from a multithreaded application.
Returned value
If successful, getsubopt() returns the index of the matched token string.
If no token strings were matched, getsubopt() returns -1.
getsubopt() does not return any errno values.