usr/src/man/man3c/getsubopt.3c

   1 '\" te
   2 .\" Copyright (c) 1989 AT&T.
   3 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
   4 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   8 .\"  This notice shall appear on any product containing this material.
   9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  12 .TH GETSUBOPT 3C "Sep 29, 2005"
  13 .SH NAME
  14 getsubopt \- parse suboption arguments from a string
  15 .SH SYNOPSIS
  16 .LP
  17 .nf
  18 #include <stdlib.h>
  19
  20 \fBint\fR \fBgetsubopt\fR(\fBchar **\fR\fIoptionp\fR, \fBchar * const *\fR\fIkeylistp\fR, \fBchar **\fR\fIvaluep\fR);
  21 .fi
  22
  23 .SH DESCRIPTION
  24 .sp
  25 .LP
  26 The \fBgetsubopt()\fR function parses suboption arguments in a flag argument.
  27 Such options often result from the use of \fBgetopt\fR(3C).
  28 .sp
  29 .LP
  30 The \fBgetsubopt()\fR argument \fIoptionp\fR is a pointer to a pointer to the
  31 option argument string. The suboption arguments are separated by commas and
  32 each can consist of either a single token or a token-value pair separated by an
  33 equal sign.
  34 .sp
  35 .LP
  36 The \fIkeylistp\fR argument is a pointer to a vector of strings. The end of the
  37 vector is identified by a null pointer. Each entry in the vector is one of the
  38 possible tokens that might be found in *\fIoptionp\fR. Since commas delimit
  39 suboption arguments in \fIoptionp\fR, they should not appear in any of the
  40 strings pointed to by \fIkeylistp\fR. Similarly, because an equal sign
  41 separates a token from its value, the application should not include an equal
  42 sign in any of the strings pointed to by \fIkeylistp\fR.
  43 .sp
  44 .LP
  45 The \fIvaluep\fR argument is the address of a value string pointer.
  46 .sp
  47 .LP
  48 If a comma appears in \fIoptionp\fR, it is interpreted as a suboption
  49 separator. After commas have been processed, if there are one or more equal
  50 signs in a suboption string, the first equal sign in any suboption string is
  51 interpreted as a separator between a token and a value. Subsequent equal signs
  52 in a suboption string are interpreted as part of the value.
  53 .sp
  54 .LP
  55 If the string at *\fIoptionp\fR contains only one suboption argument
  56 (equivalently, no commas), \fBgetsubopt()\fR updates *\fIoptionp\fR to point to
  57 the null character at the end of the string. Otherwise, it isolates the
  58 suboption argument by replacing the comma separator with a null character and
  59 updates *\fIoptionp\fR to point to the start of the next suboption argument. If
  60 the suboption argument has an associated value (equivalently, contains an equal
  61 sign), \fBgetsubopt()\fR updates *\fIvaluep\fR to point to the value's first
  62 character. Otherwise, it sets *\fIvaluep\fR to a null pointer. The calling
  63 application can use this information to determine whether the presence or
  64 absence of a value for the suboption is an error.
  65 .sp
  66 .LP
  67 Additionally, when \fBgetsubopt()\fR fails to match the suboption with a token
  68 in the \fIkeylistp\fR array, the calling application should decide if this is
  69 an error or if the unrecognized option should be processed in another way.
  70 .SH RETURN VALUES
  71 .sp
  72 .LP
  73 The \fBgetsubopt()\fR function returns the index of the matched token string or
  74 -1 if no token strings were matched.
  75 .SH ERRORS
  76 .sp
  77 .LP
  78 No errors are defined.
  79 .SH EXAMPLES
  80 .LP
  81 \fBExample 1 \fRUse \fBgetsubopt()\fR to process options.
  82 .sp
  83 .LP
  84 The following example demonstrates the processing of options to the
  85 \fBmount\fR(1M) utility using \fBgetsubopt()\fR.
  86
  87 .sp
  88 .in +2
  89 .nf
  90 #include <stdlib.h>
  91
  92 char *myopts[] = {
  93 #define READONLY     0
  94             "ro",
  95 #define READWRITE    1
  96             "rw",
  97 #define WRITESIZE    2
  98             "wsize",
  99 #define READSIZE     3
 100             "rsize",
 101             NULL};
 102
 103 main(argc, argv)
 104     int  argc;
 105     char **argv;
 106 {
 107     int sc, c, errflag;
 108     char *options, *value;
 109     extern char *optarg;
 110     extern int optind;
 111     .
 112     .
 113     .
 114     while((c = getopt(argc, argv, "abf:o:")) != -1) {
 115         switch (c) {
 116         case 'a': /* process a option */
 117             break;
 118         case 'b': /* process b option */
 119             break;
 120         case 'f':
 121             ofile = optarg;
 122             break;
 123         case '?':
 124             errflag++;
 125             break;
 126         case 'o':
 127             options = optarg;
 128             while (*options != '\e0') {
 129                 switch(getsubopt(&options,myopts,&value)){
 130                 case READONLY : /* process ro option */
 131                     break;
 132                 case READWRITE : /* process rw option */
 133                     break;
 134                 case WRITESIZE : /* process wsize option */
 135                     if (value == NULL) {
 136                         error_no_arg();
 137                         errflag++;
 138                     } else
 139                         write_size = atoi(value);
 140                     break;
 141                 case READSIZE : /* process rsize option */
 142                     if (value == NULL) {
 143                         error_no_arg();
 144                         errflag++;
 145                     } else
 146                         read_size = atoi(value);
 147                     break;
 148                 default :
 149                     /* process unknown token */
 150                     error_bad_token(value);
 151                     errflag++;
 152                     break;
 153                    }
 154             }
 155               break;
 156         }
 157     }
 158     if (errflag) {
 159         /* print usage instructions etc. */
 160     }
 161     for (; optind<argc; optind++) {
 162         /* process remaining arguments */
 163     }
 164     .
 165     .
 166     .
 167 }
 168 .fi
 169 .in -2
 170
 171 .LP
 172 \fBExample 2 \fRParse suboptions.
 173 .sp
 174 .LP
 175 The following example uses the \fBgetsubopt()\fR function to parse a value
 176 argument in the \fIoptarg\fR external variable returned by a call to
 177 \fBgetopt\fR(3C).
 178
 179 .sp
 180 .in +2
 181 .nf
 182 #include <stdlib.h>
 183 \&...
 184 char *tokens[] = {"HOME", "PATH", "LOGNAME", (char *) NULL };
 185 char *value;
 186 int opt, index;
 187 while ((opt = getopt(argc, argv, "e:")) != -1) {
 188     switch(opt) {
 189     case 'e' :
 190         while ((index = getsubopt(&optarg, tokens, &value)) != -1) {
 191             switch(index) {
 192 \&...
 193         }
 194         break;
 195 \&...
 196     }
 197 }
 198 .fi
 199 .in -2
 200
 201 .SH ATTRIBUTES
 202 .sp
 203 .LP
 204 See \fBattributes\fR(5) for descriptions of the following attributes:
 205 .sp
 206
 207 .sp
 208 .TS
 209 box;
 210 c | c
 211 l | l .
 212 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 213 _
 214 Interface Stability     Standard
 215 _
 216 MT-Level        MT-Safe
 217 .TE
 218
 219 .SH SEE ALSO
 220 .sp
 221 .LP
 222 \fBmount\fR(1M), \fBgetopt\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)