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