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

NAME

4     getarg, arg_printusage — collect command line options
5

SYNOPSIS

7     #include <getarg.h>
8
9     int
10     getarg(struct getargs *args, size_t num_args, int argc, char **argv,
11         int *optind);
12
13     void
14     arg_printusage(struct getargs *args, size_t num_args,
15         const char *progname, const char *extra_string);
16

DESCRIPTION

18     getarg() collects any command line options given to a program in an eas‐
19     ily used way.  arg_printusage() pretty-prints the available options, with
20     a short help text.
21
22     args is the option specification to use, and it's an array of struct
23     getargs elements.  num_args is the size of args (in elements).  argc and
24     argv are the argument count and argument vector to extract option from.
25     optind is a pointer to an integer where the index to the last processed
26     argument is stored, it must be initialised to the first index (minus one)
27     to process (normally 0) before the first call.
28
29     arg_printusage take the same args and num_args as getarg; progname is the
30     name of the program (to be used in the help text), and extra_string is a
31     string to print after the actual options to indicate more arguments. The
32     usefulness of this function is realised only be people who has used pro‐
33     grams that has help strings that doesn't match what the code does.
34
35     The getargs struct has the following elements.
36
37     struct getargs{
38         const char *long_name;
39         char short_name;
40         enum { arg_integer,
41                arg_string,
42                arg_flag,
43                arg_negative_flag,
44                arg_strings,
45                arg_double,
46                arg_collect
47         } type;
48         void *value;
49         const char *help;
50         const char *arg_help;
51     };
52
53     long_name is the long name of the option, it can be NULL, if you don't
54     want a long name.  short_name is the characted to use as short option, it
55     can be zero. If the option has a value the value field gets filled in
56     with that value interpreted as specified by the type field.  help is a
57     longer help string for the option as a whole, if it's NULL the help text
58     for the option is omitted (but it's still displayed in the synopsis).
59     arg_help is a description of the argument, if NULL a default value will
60     be used, depending on the type of the option:
61
62     arg_integer        the argument is a signed integer, and value should
63                        point to an int.
64
65     arg_string         the argument is a string, and value should point to a
66                        char*.
67
68     arg_flag           the argument is a flag, and value should point to a
69                        int.  It gets filled in with either zero or one,
70                        depending on how the option is given, the normal case
71                        being one. Note that if the option isn't given, the
72                        value isn't altered, so it should be initialised to
73                        some useful default.
74
75     arg_negative_flag  this is the same as arg_flag but it reverses the mean‐
76                        ing of the flag (a given short option clears the
77                        flag), and the synopsis of a long option is negated.
78
79     arg_strings        the argument can be given multiple times, and the val‐
80                        ues are collected in an array; value should be a
81                        pointer to a struct getarg_strings structure, which
82                        holds a length and a string pointer.
83
84     arg_double         argument is a double precision floating point value,
85                        and value should point to a double.
86
87     arg_collect        allows more fine-grained control of the option parsing
88                        process.  value should be a pointer to a
89                        getarg_collect_info structure:
90
91                        typedef int (*getarg_collect_func)(int short_opt,
92                                                           int argc,
93                                                           char **argv,
94                                                           int *optind,
95                                                           int *optarg,
96                                                           void *data);
97
98                        typedef struct getarg_collect_info {
99                            getarg_collect_func func;
100                            void *data;
101                        } getarg_collect_info;
102
103                        With the func member set to a function to call, and
104                        data to some application specific data. The parameters
105                        to the collect function are:
106
107                        short_flag non-zero if this call is via a short option
108                        flag, zero otherwise
109
110                        argc, argv the whole argument list
111
112                        optind pointer to the index in argv where the flag is
113
114                        optarg pointer to the index in argv[*optind] where the
115                        flag name starts
116
117                        data application specific data
118
119                        You can modify *optind, and *optarg, but to do this
120                        correct you (more or less) have to know about the
121                        inner workings of getarg.
122
123                        You can skip parts of arguments by increasing *optarg
124                        (you could implement the -z3 set of flags from gzip
125                        with this), or whole argument strings by increasing
126                        *optind (let's say you want a flag -c x y z to specify
127                        a coordinate); if you also have to set *optarg to a
128                        sane value.
129
130                        The collect function should return one of
131                        ARG_ERR_NO_MATCH, ARG_ERR_BAD_ARG, ARG_ERR_NO_ARG,
132                        ENOMEM on error, zero otherwise.
133
134                        For your convenience there is a function,
135                        getarg_optarg(), that returns the traditional argument
136                        string, and you pass it all arguments, sans data, that
137                        where given to the collection function.
138
139                        Don't use this more this unless you absolutely have
140                        to.
141
142     Option parsing is similar to what getopt uses. Short options without
143     arguments can be compressed (-xyz is the same as -x -y -z), and short
144     options with arguments take these as either the rest of the argv-string
145     or as the next option (-ofoo, or -o foo).
146
147     Long option names are prefixed with -- (double dash), and the value with
148     a = (equal), --foo=bar.  Long option flags can either be specified as
149     they are (--help), or with an (boolean parsable) option (--help=yes,
150     --help=true, or similar), or they can also be negated (--no-help is the
151     same as --help=no), and if you're really confused you can do it multiple
152     times (--no-no-help=false, or even --no-no-help=maybe).
153

EXAMPLE

155     #include <stdio.h>
156     #include <string.h>
157     #include <getarg.h>
158
159     char *source = "Ouagadougou";
160     char *destination;
161     int weight;
162     int include_catalog = 1;
163     int help_flag;
164
165     struct getargs args[] = {
166         { "source",      's', arg_string,  &source,
167           "source of shippment", "city" },
168         { "destination", 'd', arg_string,  &destination,
169           "destination of shippment", "city" },
170         { "weight",      'w', arg_integer, &weight,
171           "weight of shippment", "tons" },
172         { "catalog",     'c', arg_negative_flag, &include_catalog,
173           "include product catalog" },
174         { "help",        'h', arg_flag, &help_flag }
175     };
176
177     int num_args = sizeof(args) / sizeof(args[0]); /* number of elements in args */
178
179     const char *progname = "ship++";
180
181     int
182     main(int argc, char **argv)
183     {
184         int optind = 0;
185         if (getarg(args, num_args, argc, argv, &optind)) {
186             arg_printusage(args, num_args, progname, "stuff...");
187             exit (1);
188         }
189         if (help_flag) {
190             arg_printusage(args, num_args, progname, "stuff...");
191             exit (0);
192         }
193         if (destination == NULL) {
194             fprintf(stderr, "%s: must specify destination\n", progname);
195             exit(1);
196         }
197         if (strcmp(source, destination) == 0) {
198             fprintf(stderr, "%s: destination must be different from source\n");
199             exit(1);
200         }
201         /* include more stuff here ... */
202         exit(2);
203     }
204
205     The output help output from this program looks like this:
206
207     $ ship++ --help
208     Usage: ship++ [--source=city] [-s city] [--destination=city] [-d city]
209        [--weight=tons] [-w tons] [--no-catalog] [-c] [--help] [-h] stuff...
210     -s city, --source=city      source of shippment
211     -d city, --destination=city destination of shippment
212     -w tons, --weight=tons      weight of shippment
213     -c, --no-catalog            include product catalog
214

BUGS

216     It should be more flexible, so it would be possible to use other more
217     complicated option syntaxes, such as what ps(1), and tar(1), uses, or the
218     AFS model where you can skip the flag names as long as the options come
219     in the correct order.
220
221     Options with multiple arguments should be handled better.
222
223     Should be integrated with SL.
224
225     It's very confusing that the struct you pass in is called getargS.
226

SEE ALSO

228     getopt(3)
229
230ROKEN                         September 24, 1999                         ROKEN
Impressum