PARSEOPTIONS(3) Library Functions Manual PARSEOPTIONS(3)
NAME
ParseOptions, UsageOptions, HelpOptions, Num_Opts - Parse command line options
SYNOPSIS
#include "/usr/local/include/options.h"
int ParseOptions(options, num_options, argc, argv)
OptionDescRec *options;
int num_options;
int argc;
char **argv;
void UsageOptions(options, num_options, badoption)
OptionDescRec *options;
int num_options;
char *badoption;
void HelpOptions(options, num_options, message)
OptionDescRec *options;
int num_options;
char **message;
int Num_Opts(options)
OptionDescRec *options;
extern char *OptionChars;
extern char *ProgramName;
DESCRIPTION
ParseOptions() parses a given set of options found in argv. The argc parameter is the count of the number of string pointers in argv.
Both argc and argv are typically passed directly from a main() function. The argv parameter should contain an array of strings that need
to be parsed. ParseOptions() returns the number of entries in argv that were successfully parsed or -1 upon error.
The options structure should contain a valid description list of options. The type OptionDescRec is defined as the following in the
options.h header file:
typedef struct {
char *option; /* Option string in argv */
int flags; /* Flag bits */
int (*cvtarg)(); /* Function to convert argument */
caddr_t valp; /* Variable to set */
caddr_t value; /* Default value to provide */
char *usage; /* Usage message */
char *desc; /* Description message */
} OptionDescRec, *OptionDescList;
The order of options is important because the first partial match found in options is used. This allows abbreviations (except if the
option is a StickArg [see below]). For instance, a user may specify only "-n" for "-number" provided that "-n" is unique to options or
that "-number" is placed before any other "-n*" options in options.
The option member of OptionDescRec is the string name of the option. This is typically something like
"-c"
"+c"
"-file"
The first character of option is special. It must be one of the characters know to be the start of an option. The default list of start-
ing option characters is "-+". This indicates that an option can start with either a "-" or a "+". This list of characters may be changed
by setting the variable OptionChars to point to a string of custom starting option characters.
The flags member is used to set bits to describe how an option is to be interpreted. Valid flags are defined in the options.h header file:
NoArg No argument for this option. Use the value in OptionDescRec.value to set the value in the valp member of OptionDescRec.
IsArg Value is the option string itself.
SepArg Value is in next argument in argv.
StickyArg
Value is the characters immediately following the option.
SkipArg
Ignore this option and the next argument in argv.
SkipLine
Ignore this option and the rest of argv.
SkipNArgs
Ignore this option and the next OptionDescRes.value arguments in argv.
ArgHidden
Don't show this option in usage or help messages.
The next member of OptionDescRec is cvtarg. This should be a pointer to a function that knows how to convert the given argument into the
correct type. The predefined functions are as follows:
OptBool
Converts a boolean.
OptInt Converts an integer.
OptShort
Converts a short.
OptLong
Converts a long.
OptStr Converts a string.
The valp member should be a pointer to the variable that needs to be set. valp should accept whatever type cvtarg is expected to return.
The value member should contain a default value to be used if no value is given for an option or this type of option does not require an
argument (according to the flags bits). If value is NULL then an argument for this option is optional.
usage is used to build usage and help messages. It should be a string containing a description of any arguments that may be used for this
option. The option string itself should not be a part of usage. The UsageOptions() and HelpOptions() functions combine the option field
with usage and interpret the flags bits to build a usage string. If this field is NULL, then just the option field itself is used for
usage and help messages.
The desc member is used to build a help message for this option. This should be a string containing a brief description on what this
option does.
The num_options parameter should be the number of OptionDescRec's found in options. The function Num_Opts() will return the number of
OptionDescRec's.
The UsageOptions() function prints a usage message. If badoption is not NULL, then an initial message is displayed indicating that badop-
tion is not a valid option.
The HelpOptions() function prints a nicely formatted message describing all options. If message is not NULL it is taken to be a message
that is displayed in the output of a "-help" option.
EXAMPLE
Here is an example program:
#include "options.h"
char *filename = NULL;
int number = -1;
int foo = -1;
int I = -1;
long L = -1;
short S = -1;
OptionDescRec opts[] = {
{"-foo", NoArg, OptBool, (caddr_t) &foo, "0",
(char *)NULL, "Disable foo bar"},
{"+foo", NoArg, OptBool, (caddr_t) &foo, "1",
(char *)NULL, "Enable foo bar"},
{"-I", StickyArg, OptInt, (caddr_t) &I, (caddr_t) NULL,
(char *)NULL, "Set value of I"},
{"-L", StickyArg, OptLong, (caddr_t) &L, (caddr_t) NULL,
(char *)NULL, "Set value of L"},
{"-S", SepArg, OptShort, (caddr_t) &S, (caddr_t) NULL,
(char *)NULL, "Set value of S"},
{"-C", StickyArg, OptStr, (caddr_t) &filename, (caddr_t) NULL,
(char *)NULL, "Alternate file to use"},
{"-number", SepArg, OptInt, (caddr_t) &number, "66",
"interval", NULL},
{"-file", SepArg, OptStr, (caddr_t) &filename, (caddr_t) NULL,
"filename", "Specify alternate file to use"},
};
main(argc, argv)
int argc;
char **argv;
{
int c;
c = ParseOptions(opts, Num_Opts(opts), argc, argv);
printf("Count = %d of %d0, c, argc);
}
RETURN VALUES
ParseOptions() returns the number of arguments parsed or -1 upon error.
NOTES
The -help option is automatically built into ParseOptions().
All error messages are sent to stderr.
An option may be both StickyArg and SepArg. If both are set for one option, preference is given to SepArg parsing. Also, no appreviations
are allowed.
AUTHOR
Michael A. Cooper,
University Computing Services,
University of Southern California.
30 October 1990 PARSEOPTIONS(3)