lib/libcr/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.5.2.4 2001/12/14 18:33:58 ru Exp $
  34 .\" $DragonFly: src/lib/libcr/stdlib/Attic/getsubopt.3,v 1.2 2003/06/17 04:26:46 dillon Exp $
  35 .\"
  36 .Dd June 9, 1993
  37 .Dt GETSUBOPT 3
  38 .Os
  39 .Sh NAME
  40 .Nm getsubopt
  41 .Nd get sub options from an argument
  42 .Sh LIBRARY
  43 .Lb libc
  44 .Sh SYNOPSIS
  45 .In unistd.h
  46 .Vt extern char *suboptarg ;
  47 .Ft int
  48 .Fn getsubopt "char **optionp" "char * const *tokens" "char **valuep"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn getsubopt
  52 function
  53 parses a string containing tokens delimited by one or more tab, space or
  54 comma
  55 .Pq Ql \&,
  56 characters.
  57 It is intended for use in parsing groups of option arguments provided
  58 as part of a utility command line.
  59 .Pp
  60 The argument
  61 .Fa optionp
  62 is a pointer to a pointer to the string.
  63 The argument
  64 .Fa tokens
  65 is a pointer to a
  66 .Dv NULL Ns -terminated
  67 array of pointers to strings.
  68 .Pp
  69 The
  70 .Fn getsubopt
  71 function
  72 returns the zero-based offset of the pointer in the
  73 .Fa tokens
  74 array referencing a string which matches the first token
  75 in the string, or, \-1 if the string contains no tokens or
  76 .Fa tokens
  77 does not contain a matching string.
  78 .Pp
  79 If the token is of the form ``name=value'', the location referenced by
  80 .Fa valuep
  81 will be set to point to the start of the ``value'' portion of the token.
  82 .Pp
  83 On return from
  84 .Fn getsubopt ,
  85 .Fa optionp
  86 will be set to point to the start of the next token in the string,
  87 or the null at the end of the string if no more tokens are present.
  88 The external variable
  89 .Fa suboptarg
  90 will be set to point to the start of the current token, or
  91 .Dv NULL
  92 if no
  93 tokens were present.
  94 The argument
  95 .Fa valuep
  96 will be set to point to the ``value'' portion of the token, or
  97 .Dv NULL
  98 if no ``value'' portion was present.
  99 .Sh EXAMPLES
 100 .Bd -literal -compact
 101 char *tokens[] = {
 102         #define ONE     0
 103                 "one",
 104         #define TWO     1
 105                 "two",
 106         NULL
 107 };
 108
 109 \&...
 110
 111 extern char *optarg, *suboptarg;
 112 char *options, *value;
 113
 114 while ((ch = getopt(argc, argv, "ab:")) != \-1) {
 115         switch(ch) {
 116         case 'a':
 117                 /* process ``a'' option */
 118                 break;
 119         case 'b':
 120                 options = optarg;
 121                 while (*options) {
 122                         switch(getsubopt(&options, tokens, &value)) {
 123                         case ONE:
 124                                 /* process ``one'' sub option */
 125                                 break;
 126                         case TWO:
 127                                 /* process ``two'' sub option */
 128                                 if (!value)
 129                                         error("no value for two");
 130                                 i = atoi(value);
 131                                 break;
 132                         case \-1:
 133                                 if (suboptarg)
 134                                         error("illegal sub option %s",
 135                                           suboptarg);
 136                                 else
 137                                         error("missing sub option");
 138                                 break;
 139                 }
 140                 break;
 141         }
 142 .Ed
 143 .Sh SEE ALSO
 144 .Xr getopt 3 ,
 145 .Xr strsep 3
 146 .Sh HISTORY
 147 The
 148 .Fn getsubopt
 149 function first appeared in
 150 .Bx 4.4 .