[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

getsubopt Subroutine


Parse suboptions from a string.


Standard C Library (libc.a)


#include <stdlib.h>
int getsubopt (char **optionp,
char * const * tokens,
char ** valuep) 


The getsubopt subroutine parses suboptions in a flag parameter that were initially parsed by the getopt subroutine. 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 equal sign.

The getsubopt subroutine 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, the getsubopt subroutine updates *optionp to point to the start of the next suboption. It the suboption has an associated value, the getsubopt subroutine 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 the getsubopt subroutine returns, if *valuep is not a NULL pointer 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 the getsubopt subroutine 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.

Return Values

The getsubopt subroutine returns the index of the matched token string, or -1 if no token strings were matched.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The getopt (getopt Subroutine) subroutine.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]