| .\" |
| .\" $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., 59 |
| .\" Temple Place - Suite 330, Boston MA 02111-1307, 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). |