GETARG(3)                BSD Library Functions Manual                GETARG(3)

[1mNAME[0m
     [1mgetarg[22m, [1marg_printusage [22m-- collect command line options

[1mSYNOPSIS[0m
     [1m#include <getarg.h>[0m

     [4mint[0m
     [1mgetarg[22m([4mstruct[24m [4mgetargs[24m [4m*args[24m, [4msize_t[24m [4mnum_args[24m, [4mint[24m [4margc[24m, [4mchar[24m [4m**argv[24m,
         [4mint[24m [4m*optind[24m);

     [4mvoid[0m
     [1marg_printusage[22m([4mstruct[24m [4mgetargs[24m [4m*args[24m, [4msize_t[24m [4mnum_args[24m,
         [4mconst[24m [4mchar[24m [4m*progname[24m, [4mconst[24m [4mchar[24m [4m*extra_string[24m);

[1mDESCRIPTION[0m
     [1mgetarg[22m() collects any command line options given to a program in an eas-
     ily used way.  [1marg_printusage[22m() pretty-prints the available options, with
     a short help text.

     [4margs[24m is the option specification to use, and it's an array of [4mstruct[0m
     [4mgetargs[24m elements.  [4mnum_args[24m is the size of [4margs[24m (in elements).  [4margc[24m and
     [4margv[24m are the argument count and argument vector to extract option from.
     [4moptind[24m is a pointer to an integer where the index to the last processed
     argument is stored, it must be initialised to the first index (minus one)
     to process (normally 0) before the first call.

     [4marg_printusage[24m take the same [4margs[24m and [4mnum_args[24m as getarg; [4mprogname[24m is the
     name of the program (to be used in the help text), and [4mextra_string[24m is a
     string to print after the actual options to indicate more arguments. The
     usefulness of this function is realised only be people who has used pro-
     grams that has help strings that doesn't match what the code does.

     The [4mgetargs[24m struct has the following elements.

     struct getargs{
         const char *long_name;
         char short_name;
         enum { arg_integer,
                arg_string,
                arg_flag,
                arg_negative_flag,
                arg_strings,
                arg_double,
                arg_collect
         } type;
         void *value;
         const char *help;
         const char *arg_help;
     };

     [4mlong_name[24m is the long name of the option, it can be NULL, if you don't
     want a long name.  [4mshort_name[24m is the characted to use as short option, it
     can be zero. If the option has a value the [4mvalue[24m field gets filled in
     with that value interpreted as specified by the [4mtype[24m field.  [4mhelp[24m is a
     longer help string for the option as a whole, if it's NULL the help text
     for the option is omitted (but it's still displayed in the synopsis).
     [4marg_help[24m is a description of the argument, if NULL a default value will
     be used, depending on the type of the option:

     arg_integer        the argument is a signed integer, and [4mvalue[24m should
                        point to an [4mint[24m.

     [4marg_string[24m         the argument is a string, and [4mvalue[24m should point to a
                        [4mchar*[24m.

     [4marg_flag[24m           the argument is a flag, and [4mvalue[24m should point to a
                        [4mint[24m.  It gets filled in with either zero or one, de-
                        pending on how the option is given, the normal case
                        being one. Note that if the option isn't given, the
                        value isn't altered, so it should be initialised to
                        some useful default.

     [4marg_negative_flag[24m  this is the same as [4marg_flag[24m but it reverses the mean-
                        ing of the flag (a given short option clears the
                        flag), and the synopsis of a long option is negated.

     [4marg_strings[24m        the argument can be given multiple times, and the val-
                        ues are collected in an array; [4mvalue[24m should be a
                        pointer to a [4mstruct[24m [4mgetarg_strings[24m structure, which
                        holds a length and a string pointer.

     [4marg_double[24m         argument is a double precision floating point value,
                        and [4mvalue[24m should point to a [4mdouble[24m.

     [4marg_collect[24m        allows more fine-grained control of the option parsing
                        process.  [4mvalue[24m should be a pointer to a
                        [4mgetarg_collect_info[24m structure:

                        typedef int (*getarg_collect_func)(int short_opt,
                                                           int argc,
                                                           char **argv,
                                                           int *optind,
                                                           int *optarg,
                                                           void *data);

                        typedef struct getarg_collect_info {
                            getarg_collect_func func;
                            void *data;
                        } getarg_collect_info;

                        With the [4mfunc[24m member set to a function to call, and
                        [4mdata[24m to some application specific data. The parameters
                        to the collect function are:

                        [4mshort_flag[24m non-zero if this call is via a short option
                        flag, zero otherwise

                        [4margc[24m, [4margv[24m the whole argument list

                        [4moptind[24m pointer to the index in argv where the flag is

                        [4moptarg[24m pointer to the index in argv[*optind] where the
                        flag name starts

                        [4mdata[24m application specific data

                        You can modify [4m*optind[24m, and [4m*optarg[24m, but to do this
                        correct you (more or less) have to know about the in-
                        ner workings of getarg.

                        You can skip parts of arguments by increasing [4m*optarg[0m
                        (you could implement the [1m-z[4m[22m3[24m set of flags from [1mgzip[0m
                        with this), or whole argument strings by increasing
                        [4m*optind[24m (let's say you want a flag [1m-c [4m[22mx[24m [4my[24m [4mz[24m to specify
                        a coordinate); if you also have to set [4m*optarg[24m to a
                        sane value.

                        The collect function should return one of
                        ARG_ERR_NO_MATCH, ARG_ERR_BAD_ARG, ARG_ERR_NO_ARG,
                        ENOMEM on error, zero otherwise.

                        For your convenience there is a function,
                        [1mgetarg_optarg[22m(), that returns the traditional argument
                        string, and you pass it all arguments, sans data, that
                        where given to the collection function.

                        Don't use this more this unless you absolutely have
                        to.

     Option parsing is similar to what getopt uses. Short options without ar-
     guments can be compressed ([1m-xyz [22mis the same as [1m-x -y -z[22m), and short op-
     tions with arguments take these as either the rest of the argv-string or
     as the next option ([1m-o[4m[22mfoo[24m, or [1m-o [4m[22mfoo[24m).

     Long option names are prefixed with -- (double dash), and the value with
     a = (equal), [1m--foo=[4m[22mbar[24m.  Long option flags can either be specified as
     they are ([1m--help[22m), or with an (boolean parsable) option ([1m--help=[4m[22myes[24m,
     [1m--help=[4m[22mtrue[24m, or similar), or they can also be negated ([1m--no-help [22mis the
     same as [1m--help=[22mno), and if you're really confused you can do it multiple
     times ([1m--no-no-help=[4m[22mfalse[24m, or even [1m--no-no-help=[4m[22mmaybe[24m).

[1mEXAMPLE[0m
     #include <stdio.h>
     #include <string.h>
     #include <getarg.h>

     char *source = "Ouagadougou";
     char *destination;
     int weight;
     int include_catalog = 1;
     int help_flag;

     struct getargs args[] = {
         { "source",      's', arg_string,  &source,
           "source of shippment", "city" },
         { "destination", 'd', arg_string,  &destination,
           "destination of shippment", "city" },
         { "weight",      'w', arg_integer, &weight,
           "weight of shippment", "tons" },
         { "catalog",     'c', arg_negative_flag, &include_catalog,
           "include product catalog" },
         { "help",        'h', arg_flag, &help_flag }
     };

     int num_args = sizeof(args) / sizeof(args[0]); /* number of elements in args */

     const char *progname = "ship++";

     int
     main(int argc, char **argv)
     {
         int optind = 0;
         if (getarg(args, num_args, argc, argv, &optind)) {
             arg_printusage(args, num_args, progname, "stuff...");
             exit (1);
         }
         if (help_flag) {
             arg_printusage(args, num_args, progname, "stuff...");
             exit (0);
         }
         if (destination == NULL) {
             fprintf(stderr, "%s: must specify destination\n", progname);
             exit(1);
         }
         if (strcmp(source, destination) == 0) {
             fprintf(stderr, "%s: destination must be different from source\n");
             exit(1);
         }
         /* include more stuff here ... */
         exit(2);
     }

     The output help output from this program looks like this:

     $ ship++ --help
     Usage: ship++ [--source=city] [-s city] [--destination=city] [-d city]
        [--weight=tons] [-w tons] [--no-catalog] [-c] [--help] [-h] stuff...
     -s city, --source=city      source of shippment
     -d city, --destination=city destination of shippment
     -w tons, --weight=tons      weight of shippment
     -c, --no-catalog            include product catalog

[1mBUGS[0m
     It should be more flexible, so it would be possible to use other more
     complicated option syntaxes, such as what ps(1), and tar(1), uses, or the
     AFS model where you can skip the flag names as long as the options come
     in the correct order.

     Options with multiple arguments should be handled better.

     Should be integrated with SL.

     It's very confusing that the struct you pass in is called getargS.

[1mSEE ALSO[0m
     getopt(3)

ROKEN                         September 24, 1999                         ROKEN
