1GETARG(3) BSD Library Functions Manual GETARG(3)
2
4 getarg, arg_printusage — collect command line options
5
7 #include <getarg.h>
8 int
10 getarg(struct getargs *args, size_t num_args, int argc, char **argv,
11 int *optind);
12 void
14 arg_printusage(struct getargs *args, size_t num_args,
15 const char *progname, const char *extra_string);
16
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 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 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 The getargs struct has the following elements.
36 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 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 arg_integer the argument is a signed integer, and value should
63 point to an int.
64 arg_string the argument is a string, and value should point to a
66 char*.
67 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 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 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 arg_double argument is a double precision floating point value,
85 and value should point to a double.
86 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 typedef int (*getarg_collect_func)(int short_opt,
92 int argc,
93 char **argv,
94 int *optind,
95 int *optarg,
96 void *data);
97 typedef struct getarg_collect_info {
99 getarg_collect_func func;
100 void *data;
101 } getarg_collect_info;
102 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 short_flag non-zero if this call is via a short option
108 flag, zero otherwise
109 argc, argv the whole argument list
111 optind pointer to the index in argv where the flag is
113 optarg pointer to the index in argv[*optind] where the
115 flag name starts
116 data application specific data
118 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 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 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 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 Don't use this more this unless you absolutely have
140 to.
141 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 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
155 #include <stdio.h>
156 #include <string.h>
157 #include <getarg.h>
158 char *source = "Ouagadougou";
160 char *destination;
161 int weight;
162 int include_catalog = 1;
163 int help_flag;
164 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 int num_args = sizeof(args) / sizeof(args[0]); /* number of elements in args */
178 const char *progname = "ship++";
180 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 The output help output from this program looks like this:
206 $ 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
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 Options with multiple arguments should be handled better.
222 Should be integrated with SL.
224 It's very confusing that the struct you pass in is called getargS.
226
228 getopt(3)
229ROKEN September 24, 1999 ROKEN