getoptions(3)
NAME
getoptions - Parse command line options like Perl's Getopt::Long
SYNOPSIS
#include <getoptions.h>
rc = getoptions( &argc, &argv,
"v|verbose+", &verbose,
"d|debug!", &debug,
"s|sums=i@10", vals, &num_vals,
"h|help&", help
);
if( rc != 0 ) { // Error handling }
DESCRIPTION
The getoptions() function parses command line arguments. Its arguments
are pointers to argc and argv (which will be updated to reflect the
non-option arguments remaining), and a set of option descriptor,
variable tuples.
The option descriptors are very similar to those described in
Getopt::Long,
with some concessions made for C's lack of introspection. There are two
types of options, those that take arguments and those that are booleans.
No-argument options
Boolean arguments are ones that are true (or false) simply by appearing
on the command line. If your program has a runtime debugging option,
you could pass in the option "--debug" to enable it. "--no-debug" would
disable it if it had been specified ealier. The other type of boolean
is the incrementing variable, such as a verbosity option that increases
in value for each time "-v" or "--verbose" is specified on the command
line. The last no-argument option is one that runs a handler if the
option is specified, such as "--help".
Option descriptors for these three examples would be written as:
int help_function( void ) { ... }
int debug = 0;
int verbose = 0;
getoptions( &argc, &argv,
"d|debug!", &debug,
"v|verbose+", &verbose,
"h|?|help&", help_function
);
No-argument options may be specified as many times as desired on the
command line with no ill-effect. The last one is the one that actually
takes effect.
One-argument options
The one argument options are those that expect an (optional) string
on the command line. They can interpret this as a string, an integer,
float, double or by a user specified handler.
If your program expects a string argument for the "--host" option,
you would write the option descriptor like this and pass in the
char ** argument place holder:
char * host_name = 0;
...
getoptions( &argc, &argv,
"host=s", &host_name
);
The "host_name" pointer will be set to point to the string in argv[]
if the "--host" option is specified on the command line. You do not
need to allocate or free the memory associated with this string,
but it is not guaranteed to be writeable by ANSI.
If the option descriptor was "host:s", then the string argument to the
option would be optional. getoptions() looks at the next argument to
see if it has a leading - to determine if it is a new option or an
argument to this option.
The other type specifiers are i for integer, which expects an int *,
f for float (float *), d for double (double *) and & for handler,
which expects an int (*)( char * ) function pointer.
One-argument options may be specified as many times as desired on the
command line with no ill-effect. The last one is the one that's value
is actually stored. The "--foo=bar" style is not yet supported.
Array options
You can also specify that an option accepts an arbitrary number of
arguments by adding "@N" to the one-argument option descriptor. This
tells getoptions() that the pointer is actually an array of N elements.
You must also pass in a pointer to an integer that will be returned
with the number of elements used in the array. If your "--host" argument
could be specified up to 10 times, you would say:
char * host_names[10];
int num_hosts = 0;
...
getoptions( &argc, &argv,
"host=s@10", host_names, &num_hosts
);
This would allow the user to specify on the command line:
program --host foo --host bar --host baz --host ...
Special note about handlers
If you have a user supplied callback for either no-argument or one-argument
cases, a non-zero return from the callback will abort the parsing and return
the value to the caller of getoptions(). If the special value
"GETOPTIONS_NOMATCH" is returned by the handler, getoptions will continue
looking in the argument descriptors for a match.
Special note about arrays
If you run out of array space for a specific option, getoptions will
continue looking in the list of option descriptors. This allows you to
do something like:
int host_overflow( char *hostname ) { ... }
...
getoptions( &argc, &argv,
"hosts=s@10", host_names, &num_hosts,
"hosts=s&", host_overflow
);
RETURN VALUE
On success, getoptions() returns 0. For unknown options, -1 is
returned. If a user handler returns anything other than 0 or GETOPTIONS_NOMATCH,
that value is propagated to the caller of getoptions().
CONFORMING TO
Nothing. I just made it up myself.
SEE ALSO
getopt(3), getopt_long(3), Getopt::Long
BUGS
- Ignores the current locale for comparisons.
- Can not bundle single character options.
- Can not distinguish between single and long options.
- Lots of others
AUTHOR
Trammell Hudson
DOWNLOAD