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