The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.

#### NAME

> getsubopt - parse suboption arguments from a string

#### SYNOPSIS

> ``[XSI] #include <stdlib.h>
> int getsubopt(char **`optionp`, char * const *`keylistp`, char **`valuep`);``
> `
> `

#### DESCRIPTION

> The getsubopt() function shall parse suboption arguments in a flag argument. Such options often result from the use of getopt().

> The getsubopt() argument optionp is a pointer to a pointer to the option argument string. The suboption arguments shall be separated by commas and each may consist of either a single token, or a token-value pair separated by an equal sign.

> The keylistp argument shall be 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 commas 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 shall be interpreted as a suboption separator. 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 shall be interpreted as a separator between a token and a value. Subsequent equal signs in a suboption string shall be interpreted as part of the value.

> If the string at *optionp contains only one suboption argument (equivalently, no commas), getsubopt() shall update *optionp to point to the null character at the end of the string. Otherwise, it shall isolate the suboption argument by replacing the comma separator with a null character, and shall update *optionp to point to the start of the next suboption argument. If the suboption argument has an associated value (equivalently, contains an equal sign), getsubopt() shall update *valuep to point to the value's first character. Otherwise, it shall set *valuep to a null pointer. The calling application may 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 argument 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 VALUE

> The getsubopt() function shall return the index of the matched token string, or -1 if no token strings were matched.

#### ERRORS

> No errors are defined.

The following sections are informative.

#### EXAMPLES

>     #include <stdio.h>
>     #include <stdlib.h>

>     int do_all;
>     const char *type;
>     int read_size;
>     int write_size;
>     int read_only;

>     enum
>     {
>         RO_OPTION = 0,
>         RW_OPTION,
>         READ_SIZE_OPTION,
>         WRITE_SIZE_OPTION
>     };

>     const char *mount_opts[] =
>     {
>         [RO_OPTION] = "ro",
>         [RW_OPTION] = "rw",
>         [READ_SIZE_OPTION] = "rsize",
>         [WRITE_SIZE_OPTION] = "wsize",
>         NULL
>     };

>     int
>     main(int argc, char *argv[])
>     {
>         char *subopts, *value;
>         int opt;

>         while ((opt = getopt(argc, argv, "at:o:")) != -1)
>             switch(opt)
>                 {
>                 case 'a':
>                     do_all = 1;
>                     break;
>                 case 't':
>                     type = optarg;
>                     break;
>                 case 'o':
>                     subopts = optarg;
>                     while (*subopts != '\0')
>                         switch(getsubopt(&subopts, mount_opts, &value))
>                     {
>                     case RO_OPTION:
>                         read_only = 1;
>                         break;
>                     case RW_OPTION:
>                         read_only = 0;
>                         break;
>                     case READ_SIZE_OPTION:
>                         if (value == NULL)
>                             abort();
>                         read_size = atoi(value);
>                         break;
>                     case WRITE_SIZE_OPTION:
>                         if (value == NULL)
>                             abort();
>                         write_size = atoi(value);
>                         break;
>                     default:
>                         /* Unknown suboption. */
>                         printf("Unknown suboption `%s'\n", value);
>                         break;
>                     }
>                 break;
>             default:
>                 abort();
>             }

>         /* Do the real work. */

>         return 0;
>     }

> ##### Parsing Suboptions

> The following example uses the getsubopt() function to parse a value argument in the optarg external variable returned by a call to getopt().

>     #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;
>     ...
>         }
>     }
>     ...

#### APPLICATION USAGE

> None.

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> getopt(), the Base Definitions volume of IEEE Std 1003.1-2001, <stdlib.h>

#### CHANGE HISTORY

> First released in Issue 4, Version 2.

#### Issue 5

> Moved from X/OPEN UNIX extension to BASE.

#### Issue 6

> IEEE Std 1003.1-2001/Cor 1-2002, item XSH/TC1/D6/26 is applied, correcting an editorial error in the SYNOPSIS.

End of informative text.

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT ]