'\"macro stdmacro
.if n .pH g3c.getsubopt @(#)getsubopt	40.7 of 10/26/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} getsubopt 3C "" "\&"
.if \nX=1 .ds x} getsubopt 3C ""
.if \nX=2 .ds x} getsubopt 3C "" "\&"
.if \nX=3 .ds x} getsubopt "" "" "\&"
.TH \*(x}
.SH NAME
\f4getsubopt\fP \- parse suboptions from a string
.SH SYNOPSIS
.P
\f4#include <stdlib.h>
.P
.nf
\f4int getsubopt (char \(**\(**optionp, char \(** const \(**tokens, char \(**\(**valuep);\f1
.fi
.SH DESCRIPTION
\f4getsubopt\fP
parses suboptions in a flag argument that was initially
parsed by 
\f4getopt\fP.
These suboptions are separated by commas and may consist of either
a single token
or a token-value pair separated by an equal sign. 
Since commas \%delimit suboptions in the option string, they are not allowed 
to be part of the suboption or the value of a suboption.
A command that uses this syntax is 
\f4mount\fP(1M),
which allows
the user to specify mount parameters with the \f4-o\fP option as follows:
.RS
.sp .5
\f4 mount \-o rw,hard,bg,wsize=1024 speed:/usr /usr\fP
.sp .5
.RE
In this example there are four suboptions:
\f4rw\fP,
\f4hard\fP,
\f4bg\fP,
and \f4wsize\fP,
the last of which has an associated value of 1024.
.LP
\f4getsubopt\fP
takes the address of a pointer to the option string,
a vector of possible tokens,
and the address of a value string pointer.
It returns the index of the token that matched the suboption in the
input string or \-1 if there was no match.
If the option string at 
\f2optionp\fP
contains only one subobtion,
\f4getsubopt\fP
updates 
\f2optionp\fP
to point to the null character at the end of the string;
otherwise it isolates the suboption by replacing the comma separator with
a null character,
and updates
\f2optionp\fP
to point to the start of the next suboption.
If the suboption has an associated value,
\f4getsubopt\fP
updates
\f2valuep\fP
to point to the value's first character. 
Otherwise it sets
\f2valuep\fP
to \f4NULL\f1.
.LP
The token vector is organized as a series of pointers to null
strings.  The end of the token vector is identified by a null pointer.
.LP
When 
\f4getsubopt\fP
returns,
if 
\f2valuep\fP
is not \f4NULL\f1, then the suboption processed included a value.
The calling program may use this information to determine if the
presence or lack of a value for this subobtion is an error.
.LP
Additionally, 
when 
\f4getsubopt\fP
fails to match the suboption with the tokens in the 
\f2tokens\fP
array,
the calling program should decide if this is an error,
or if the unrecognized option should be passed to another
program.
.SH EXAMPLE
The following code fragment shows how to process options to the 
\f4mount\fP command using 
\f4getsubopt\fP.
.LP
\f4
.nf
#include <stdlib.h> 

char \(**myopts[] = {
#define READONLY 	0
			"ro",
#define READWRITE	1
			"rw",
.bp
#define WRITESIZE	2
			"wsize",
#define READSIZE 	3
			"rsize",
			NULL};

main(argc, argv)
	int  argc;
	char \(**\(**argv;
{
	int sc, c, errflag;
	char \(**options, \(**value;
	extern char \(**optarg;
	extern int optind;
	.
	.
	.
	while((c = getopt(argc, argv, "abf:o:")) != -1) {
		switch (c) {
		case 'a': /\(** process a option \(**/
			break;
		case 'b': /\(** process b option \(**/
			break;
		case 'f':
			ofile = optarg;
			break; 
		case '?': 
			errflag++;
			break;
		case 'o': 
			options = optarg;
			while (\(**options != '\e0') {
				switch(getsubopt(&options,myopts,&value) {
				case READONLY : /\(** process ro option \(**/
					break;
				case READWRITE : /\(** process rw option \(**/
					break;
				case WRITESIZE : /\(** process wsize option \(**/
					if (value == NULL) {
						error_no_arg();
						errflag++;
					} else 
						write_size = atoi(value);
					break;
				case READSIZE : /\(** process rsize option \(**/
					if (value == NULL) {
						error_no_arg();
						errflag++;
					} else 
						read_size = atoi(value);
					break;
				default : 
					/\(** process unknown token \(**/
					error_bad_token(value);
					errflag++;
					break;
			   	}
			}
		  	break;
		}
	}
	if (errflag) {
		/\(** print usage instructions etc. \(**/
	}
	for (; optind<argc; optind++) {
		/\(** process remaining arguments \(**/
	}
	.
	.
	.
}
\fP
.fi 
.SH SEE ALSO
\f4getopt\fP(3C).
.SH DIAGNOSTICS
\f4getsubopt\fP
returns \-1 when the token it is scanning is not in the token vector.
The variable addressed by 
\f2valuep\fP
contains a pointer to the first character of the 
token
that was not recognized rather than a pointer to a value for that token.
.LP
The variable addressed by
\f2optionp\fP
points to the next option to be parsed, 
or a null character if there are no more options.
.SH NOTES
During parsing, commas in the option input string are changed to null characters.
White space in tokens or token-value pairs must be protected from
the shell by quotes.
