getsubopt(S-osr5)

getsubopt -- parse suboptions from a string

Syntax

cc ...-lc

#include <stdlib.h>

int getsubopt (char **optionp, char *const *tokens, char **valuep);

Description

getsubopt(S-osr5) parses suboptions in a flag argument that was initially parsed by getopt(S-osr5). These suboptions are separated by commas. They can be either a single token or a token-value pair separated by an equal sign.

Since commas delimit suboptions in the option string, they can not be part of the suboption or the value of a suboption. Similarly, a token must not contain an equal sign.

A command that uses this syntax is mount(ADM), which lets you specify NFS options using the -fNFS option, as follows:

mount -fNFS soft,bg,wsize=1024 speed:/usr /usr

In this example there are three suboptions: soft, bg, and wsize, 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 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 to another program.

Parsing

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.

Return values

getsubopt( ) returns the index of the matched token string, or -1 when the token that 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.

Diagnostics

This function does not set errno.

Examples

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, write_size, read_size;
      char *ofile, *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 != ' ') {
                           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) {
                                           error_no_arg();
                                           errflag++;
                                   } else
                                           write_size = atoi(value);
                                   break;
                           case READSIZE : /* process rsize option */
                                   if (value == NULL) {
                                           error_no_arg();
                                           errflag++;
                                   } else
                                           read_size = atoi(value);
                                   break;
                           default :
                                   /* process unknown token */
                                   error_bad_token(value);
                                   errflag++;
                                   break;
                           }
                   }
                   break;
           }
      }
      if (errflag) {
           /* print usage instructions etc. */
      }
      for (; optind<argc; optind++) {
           /* process remaining arguments */
      }
      .
      .
      .
   }

Standards conformance

getsubopt(S-osr5) is conformant with:

X/Open CAE Specification, System Interfaces and Headers, Issue 4, Version 2.