lib/libc/stdlib/getsubopt.3

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