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$ 30.\" 31.Dd December 25, 2011 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 stdlib.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 } 136 break; 137 } 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