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