doc/man3/parse_opts.3

.\"
.\" $Id: parse_opts.3,v 1.3 2000/08/31 18:40:28 nstraz Exp $
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of version 2 of the GNU General Public License as
.\" published by the Free Software Foundation.
.\"
.\" This program is distributed in the hope that it would be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\" Further, this software is distributed without any warranty that it is
.\" free of the rightful claim of any third person regarding infringement
.\" or the like.  Any license provided herein, whether implied or
.\" otherwise, applies only to this software file.  Patent licenses, if
.\" any, provided herein do not apply to combinations of this program with
.\" other software, or any other product whatsoever.
.\"
.\" You should have received a copy of the GNU General Public License along
.\" with this program; if not, write the Free Software Foundation, Inc.,
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
.\" Mountain View, CA  94043, or:
.\"
.\" http://www.sgi.com
.\"
.\" For further information regarding this notice, see:
.\"
.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
.\"
.TH PARSE_OPTS 3 "21 Jan 2011" "LTP" "Linux Test Project"
.SH NAME
parse_opts \- parse standard and user options for LTP test programs
.SH SYNOPSIS
.nf
.B #include \(rqtest.h\(rq
.B #include \(rqusctest.h\(rq
.sp
.BI "char *parse_opts(int " argc ", char *" argv[] ", "
.BI "                 option_t " option_array[] ","
.BI "                 void (*" user_help_func ")());"
.fi
.SH DESCRIPTION
The \fBparse_opts()\fP routine parses options from the command line, looking
for user specified options or standard options (see below). Its arguments
\fIargc\fP and \fIargv\fP are the argument count and array as passed to the
main() function on program invocation. User options may be specified in the
\fIoption_array\fR argument. A help function may be specified in the
\fIuser_help_func\fP argument.
.sp
\fIoption_array\fP is a pointer to the first element of an array of
\fBoption_t\fP.  If no additional options are needed, pass NULL.
\fBoption_t\fR is declared in \fBusctest.h\fP as
.nf
.sp
.in 10
typedef struct {
.in 14
char	*option;
int	*flag;
char	**arg;
.in 10
} option_t;
.fi
.PP
The meanings of the different fields are:
.TP
.I option
is a valid option string to be given to getopt().
.TP
.I flag
is a pointer to an integer location to set true if option is given in
\fIargv\fR.  This can be NULL if the option doesn't require an argument.
.TP
.I arg
is a pointer to a character pointer variable that will be set with the option
argument if the option is present in argv.  This pointer MUST be provided if
the option can take an argument.  Failure to provide a location will cause
\fBparse_opts()\fR to return an error.
.PP
.I user_help_func
is a pointer to a function that will be called when the \-h option is found.
This function should print help messages for the options in \fIoption_array\fR
to standard out. The standard help messages are formatted such that the option
designator starts in column 3 and the description starts in column 11.
.sp
.SH "STANDARD OPTIONS"
Below is a list of the standard options defined in \fBparse_opts()\fR:
.TP
.BI \-c " n"
Run \fIn\fR copies of the test in parallel.  This is done by forking \fIn\fR
times and running the test as usual.  If \-i or \-I are specified, each process
will run for that amount of time.
.TP
.B \-e
Turn on logging all errno's received.  This option is to facilitate security
audit testing for MLS.
.TP
.B \-f
Suppresses functional testing messages.
.TP
.B \-h
Print help message.  The standard options will be printed first, then a call to
.I user_help_func()
will be made.
.TP
.BI \-i " n"
Run for \fIn\fR iterations. A value of 0 makes the test loop infinitely.
(default 1)
.TP
.BI \-I " x"
The test will loop until \fIx\fR seconds have passed. (default 0.0)
.TP
.B \-p
Pause for SIGUSR1 before testing. The test will pause where you place
TEST_PAUSE.  \fIWarning\fR: The test will also fork at this point if \-c is
used.
.TP
.BI \-P " x"
This option will do a delay of \fIx\fR seconds after each iteration. (default 0.0)
.TP
.B \-t
Produce timing statistics. *NOT IMPLEMENTED*
.PP
.sp
The STD_* flags are used by system call test macros defined in usctest.h
(see \fBusctest(3)\fR), or may be used in the user's code.
.SH "RETURN VALUE"
.B parse_opts()
returns a NULL pointer upon successful completion.  If an error occurs a
pointer to an error message is returned.
.SH "EXAMPLE"
The following example defines two options, one with an argument, one without.
.sp
.nf
int fflag, Tflag;	/* binary flags: opt or not */
char *Topt;		/* option arguments */

option_t options[] = {
	{ "F", &fflag, NULL },		/* No argument */
	{ "T:",	&Tflag, &Topt },	/* argument required */
	{ NULL, NULL, NULL }		/* NULL required to end array */
};

void help()
{
	printf("  -F       An option with no argument\\n");
	printf("  -T opt   An option that requires an argument\\n");
}

int main(int argc, char *argv[])
{
	char *msg;

	if ((msg = parse_opts(argc, argv, options, &help)) != NULL)
		error_exit(msg);

	return 0;
}
.fi
.sp
The following example shows how to use \fBparse_opts()\fR without defining new options.
.sp
.nf
int main(int argc, char *argv[])
{
	char *msg;

	if ((msg = parse_opts(argc, argv, NULL, NULL)) != NULL)
		error_exit(msg);

	return 0;
}
.fi
.SH "SEE ALSO"
usctest(3), getopt(3).