Commit | Line | Data |
---|---|---|
ae59e04c | 1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
4704bf30 KB |
2 | .\" All rights reserved. |
3 | .\" | |
4 | .\" %sccs.include.redist.man% | |
5 | .\" | |
924afea1 | 6 | .\" @(#)getsubopt.3 5.7 (Berkeley) %G% |
4704bf30 | 7 | .\" |
ae59e04c CL |
8 | .Dd |
9 | .Dt GETSUBOPT 3 | |
10 | .Os | |
11 | .Sh NAME | |
12 | .Nm getsubopt | |
13 | .Nd get sub options from an argument | |
14 | .Sh SYNOPSIS | |
924afea1 | 15 | .Fd #include <stdlib.h> |
f2e01635 | 16 | .Vt extern char *suboptarg |
ae59e04c CL |
17 | .Ft int |
18 | .Fn getsubopt "char **optionp" "char * const *tokens" "char **valuep" | |
19 | .Sh DESCRIPTION | |
20 | The | |
21 | .Fn getsubopt | |
924afea1 | 22 | function |
4704bf30 | 23 | parses a string containing tokens delimited by one or more tab, space or |
ae59e04c CL |
24 | comma |
25 | .Pq Ql \&, | |
26 | characters. | |
4704bf30 KB |
27 | It is intended for use in parsing groups of option arguments provided |
28 | as part of a utility command line. | |
ae59e04c CL |
29 | .Pp |
30 | The argument | |
31 | .Fa optionp | |
4704bf30 | 32 | is a pointer to a pointer to the string. |
ae59e04c CL |
33 | The argument |
34 | .Fa tokens | |
35 | is a pointer to a | |
36 | .Dv NULL Ns -terminated | |
37 | array of pointers to strings. | |
38 | .Pp | |
39 | The | |
40 | .Fn getsubopt | |
41 | function | |
4704bf30 | 42 | returns the zero-based offset of the pointer in the |
ae59e04c | 43 | .Fa tokens |
4704bf30 | 44 | array referencing a string which matches the first token |
ae59e04c CL |
45 | in the string, or, \-1 if the string contains no tokens or |
46 | .Fa tokens | |
4704bf30 | 47 | does not contain a matching string. |
ae59e04c | 48 | .Pp |
4704bf30 | 49 | If the token is of the form ``name=value'', the location referenced by |
ae59e04c | 50 | .Fa valuep |
4704bf30 | 51 | will be set to point to the start of the ``value'' portion of the token. |
ae59e04c | 52 | .Pp |
4704bf30 | 53 | On return from |
ae59e04c CL |
54 | .Fn getsubopt , |
55 | .Fa optionp | |
4704bf30 KB |
56 | will be set to point to the start of the next token in the string, |
57 | or the null at the end of the string if no more tokens are present. | |
58 | The external variable | |
ae59e04c CL |
59 | .Fa suboptarg |
60 | will be set to point to the start of the current token, or | |
61 | .Dv NULL | |
62 | if no | |
4704bf30 | 63 | tokens were present. |
ae59e04c CL |
64 | The argument |
65 | .Fa valuep | |
66 | will be set to point to the ``value'' portion of the token, or | |
67 | .Dv NULL | |
4704bf30 | 68 | if no ``value'' portion was present. |
ae59e04c | 69 | .Sh EXAMPLE |
48dd900b | 70 | .Bd -literal -compact |
4704bf30 KB |
71 | char *tokens[] = { |
72 | #define ONE 0 | |
73 | "one", | |
74 | #define TWO 1 | |
75 | "two", | |
76 | NULL | |
77 | }; | |
78 | ||
79 | \&... | |
80 | ||
81 | extern char *optarg, *suboptarg; | |
82 | char *options, *value; | |
83 | ||
ae59e04c | 84 | while ((ch = getopt(argc, argv, "ab:")) != \-1) { |
4704bf30 KB |
85 | switch(ch) { |
86 | case 'a': | |
87 | /* process ``a'' option */ | |
88 | break; | |
89 | case 'b': | |
90 | options = optarg; | |
91 | while (*options) { | |
92 | switch(getsubopt(&options, tokens, &value)) { | |
93 | case ONE: | |
94 | /* process ``one'' sub option */ | |
95 | break; | |
96 | case TWO: | |
97 | /* process ``two'' sub option */ | |
98 | if (!value) | |
99 | error("no value for two"); | |
100 | i = atoi(value); | |
101 | break; | |
ae59e04c | 102 | case \-1: |
4704bf30 KB |
103 | if (suboptarg) |
104 | error("illegal sub option %s", | |
ae59e04c | 105 | suboptarg); |
4704bf30 KB |
106 | else |
107 | error("missing sub option"); | |
108 | break; | |
109 | } | |
110 | break; | |
111 | } | |
ae59e04c CL |
112 | .Ed |
113 | .Sh SEE ALSO | |
114 | .Xr getopt 3 , | |
115 | .Xr strsep 3 | |
116 | .Sh HISTORY | |
117 | The | |
118 | .Fn getsubopt | |
119 | function is | |
120 | .Ud . |