unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

GETSUBOPT(3)               Library Functions Manual               GETSUBOPT(3)



NAME
       getsubopt - parse sub options from a string.

SYNOPSIS
       int getsubopt(optionp, tokens, valuep)
       char **optionp;
       char *tokens[];
       char **valuep;

DESCRIPTION
       getsubopt()  is  a function to parse suboptions in a flag argument that
       was initially parsed by getopt(3).  These suboptions are  separated  by
       commas  and may consist of either a single token, or a token-value pair
       separated by an equal sign.  Since commas  delimit  suboptions  in  the
       option  string  they are not allowed to be part of the suboption or the
       value of a suboption.  An example command  that  uses  this  syntax  is
       mount(8),  which  allows  you  to  specify mount parameters with the -o
       switch as follows :
            pepper % 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 vec-
       tor 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 subobtion, getsubopt() updates *optionp to point to
       the NUL at the end of the string, otherwise it isolates  the  suboption
       by  replacing  the  comma seperator with a NUL, 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-termi-
       nated  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 may use this informa-
       tion to determine if the presence or lack of a value for this subobtion
       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.

DIAGNOSTICS
       getsubopt() returns -1 when the token 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 NUL character if there are no more options.

EXAMPLE
       The following code fragment shows how you might process options to  the
       mount(8) command using getsubopt(3).

       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;
            char *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 != '\0') {
                           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<&lt;argc; optind++) {
                 /* process remaining arguments */
            }
            .
            .
            .
       }

SEE ALSO
       getopt(3)

NOTES
       During parsing, commas in the option input string are changed to nulls.

       White  space  in tokens or token-value pairs must be protected from the
       shell by quotes.



                                6 October 1987                    GETSUBOPT(3)