stdlib/getsubopt.3

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)getsubopt.3 8.1 (Berkeley) 6/9/93
  33 .\" $FreeBSD: src/lib/libc/stdlib/getsubopt.3,v 1.10 2004/02/23 03:32:10 ache Exp $
  34 .\"
  35 .Dd June 9, 1993
  36 .Dt GETSUBOPT 3
  37 .Os
  38 .Sh NAME
  39 .Nm getsubopt
  40 .Nd get sub options from an argument
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In stdlib.h
  45 .Vt extern char *suboptarg ;
  46 .Ft int
  47 .Fo getsubopt
  48 .Fa "char **optionp"
  49 .Fa "char *const *keylistp"
  50 .Fa "char **valuep"
  51 .Fc
  52 .Sh DESCRIPTION
  53 The
  54 .Fn getsubopt
  55 function
  56 parses a string containing tokens that are delimited
  57 by one or more tab, space, or comma
  58 .Pq Ql \&,
  59 characters.
  60 It is intended for use in parsing groups of option arguments
  61 that are provided as part of a utility command line.
  62 .Pp
  63 The argument
  64 .Fa optionp
  65 is a pointer to a pointer to the string.
  66 The argument
  67 .Fa keylistp
  68 is a pointer to a
  69 .Dv NULL Ns -terminated
  70 array of pointers to strings.
  71 .Pp
  72 The
  73 .Fn getsubopt
  74 function
  75 returns the zero-based offset of the pointer in the
  76 .Fa keylistp
  77 array, referencing a string which matches the first token in the string
  78  or \-1 if the string contains no tokens or
  79 .Fa keylistp
  80 does not contain a matching string.
  81 .Pp
  82 If the token is of the form ``name=value'', the location referenced by
  83 .Fa valuep
  84 will be set to point to the start of the ``value'' portion of the token.
  85 .Pp
  86 On return from
  87 .Fn getsubopt ,
  88 .Fa optionp
  89 will be set to point to the start of the next token in the string,
  90 or the null at the end of the string if no more tokens are present.
  91 The external variable
  92 .Fa suboptarg
  93 will be set to point to the start of the current token, or
  94 .Dv NULL
  95 if no
  96 tokens were present.
  97 The argument
  98 .Fa valuep
  99 will be set to point to the ``value'' portion of the token, or
 100 .Dv NULL
 101 if no ``value'' portion was present.
 102 .Sh EXAMPLES
 103 .Bd -literal -compact
 104 char *keylistp[] = {
 105         #define ONE     0
 106                 "one",
 107         #define TWO     1
 108                 "two",
 109         NULL
 110 };
 111
 112 \&...
 113
 114 extern char *optarg, *suboptarg;
 115 char *options, *value;
 116
 117 while ((ch = getopt(argc, argv, "ab:")) != \-1) {
 118         switch(ch) {
 119         case 'a':
 120                 /* process ``a'' option */
 121                 break;
 122         case 'b':
 123                 options = optarg;
 124                 while (*options) {
 125                         switch(getsubopt(&options, keylistp, &value)) {
 126                         case ONE:
 127                                 /* process ``one'' sub option */
 128                                 break;
 129                         case TWO:
 130                                 /* process ``two'' sub option */
 131                                 if (!value)
 132                                         error("no value for two");
 133                                 i = atoi(value);
 134                                 break;
 135                         case \-1:
 136                                 if (suboptarg)
 137                                         error("illegal sub option %s",
 138                                           suboptarg);
 139                                 else
 140                                         error("missing sub option");
 141                                 break;
 142                 }
 143                 break;
 144         }
 145 .Ed
 146 .Sh SEE ALSO
 147 .Xr getopt 3 ,
 148 .Xr strsep 3
 149 .Sh HISTORY
 150 The
 151 .Fn getsubopt
 152 function first appeared in
 153 .Bx 4.4 .