summaryrefslogtreecommitdiffstats
path: root/crypto/heimdal/lib/roken/getarg.3
blob: e2f041283566456dc0e07b70721b26ff1e341239 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
.\" Copyright (c) 1999 - 2002 Kungliga Tekniska Högskolan
.\" (Royal Institute of Technology, Stockholm, Sweden). 
.\" All rights reserved. 
.\"
.\" Redistribution and use in source and binary forms, with or without 
.\" modification, are permitted provided that the following conditions 
.\" are met: 
.\"
.\" 1. Redistributions of source code must retain the above copyright 
.\"    notice, this list of conditions and the following disclaimer. 
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright 
.\"    notice, this list of conditions and the following disclaimer in the 
.\"    documentation and/or other materials provided with the distribution. 
.\"
.\" 3. Neither the name of the Institute nor the names of its contributors 
.\"    may be used to endorse or promote products derived from this software 
.\"    without specific prior written permission. 
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 
.\" SUCH DAMAGE. 
.\" 
.\" $Id: getarg.3,v 1.7 2003/04/16 13:58:24 lha Exp $
.Dd September 24, 1999
.Dt GETARG 3
.Os ROKEN
.Sh NAME
.Nm getarg ,
.Nm arg_printusage
.Nd collect command line options
.Sh SYNOPSIS
.In getarg.h
.Ft int
.Fn getarg "struct getargs *args" "size_t num_args" "int argc" "char **argv" "int *optind"
.Ft void
.Fn arg_printusage "struct getargs *args" "size_t num_args" "const char *progname" "const char *extra_string"
.Sh DESCRIPTION
.Fn getarg
collects any command line options given to a program in an easily used way.
.Fn arg_printusage
pretty-prints the available options, with a short help text.
.Pp
.Fa args
is the option specification to use, and it's an array of
.Fa struct getargs
elements.
.Fa num_args
is the size of
.Fa args
(in elements).
.Fa argc
and
.Fa argv
are the argument count and argument vector to extract option from.
.Fa optind
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.
.Pp
.Fa arg_printusage
take the same
.Fa args
and
.Fa num_args
as getarg;
.Fa progname
is the name of the program (to be used in the help text), and
.Fa extra_string
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 programs that has help strings that doesn't match what
the code does.
.Pp
The
.Fa getargs
struct has the following elements.
.Bd -literal
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;
};
.Ed
.Pp
.Fa long_name
is the long name of the option, it can be
.Dv NULL ,
if you don't want a long name.
.Fa short_name
is the characted to use as short option, it can be zero. If the option
has a value the
.Fa value
field gets filled in with that value interpreted as specified by the
.Fa type
field.
.Fa help
is a longer help string for the option as a whole, if it's
.Dv NULL
the help text for the option is omitted (but it's still displayed in
the synopsis).
.Fa arg_help
is a description of the argument, if
.Dv NULL
a default value will be used, depending on the type of the option:
.Pp
.Bl -hang -width arg_negative_flag
.It arg_integer
the argument is a signed integer, and
.Fa value
should point to an
.Fa int .
.It Fa arg_string
the argument is a string, and
.Fa value
should point to a
.Fa char* .
.It Fa arg_flag
the argument is a flag, and
.Fa value
should point to a
.Fa int .
It gets filled in with either zero or one, depending 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.
.It Fa arg_negative_flag
this is the same as
.Fa arg_flag
but it reverses the meaning of the flag (a given short option clears
the flag), and the synopsis of a long option is negated.
.It Fa arg_strings
the argument can be given multiple times, and the values are collected
in an array;
.Fa value
should be a pointer to a
.Fa struct getarg_strings
structure, which holds a length and a string pointer.
.It Fa arg_double
argument is a double precision floating point value, and
.Fa value
should point to a
.Fa double .
.It Fa arg_collect
allows more fine-grained control of the option parsing process.
.Fa value
should be a pointer to a
.Fa getarg_collect_info
structure:
.Bd -literal
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;
.Ed
.Pp
With the
.Fa func
member set to a function to call, and
.Fa data
to some application specific data. The parameters to the collect function are:
.Bl -inset
.It Fa short_flag
non-zero if this call is via a short option flag, zero otherwise
.It Fa argc , argv
the whole argument list
.It Fa optind
pointer to the index in argv where the flag is
.It Fa optarg
pointer to the index in argv[*optind] where the flag name starts
.It Fa data
application specific data
.El
.Pp
You can modify
.Fa *optind ,
and
.Fa *optarg ,
but to do this correct you (more or less) have to know about the inner
workings of getarg.
.Pp
You can skip parts of arguments by increasing
.Fa *optarg
(you could
implement the
.Fl z Ns Ar 3
set of flags from
.Nm gzip
with this), or whole argument strings by increasing
.Fa *optind
(let's say you want a flag
.Fl c Ar x y z
to specify a coordinate); if you also have to set
.Fa *optarg
to a sane value.
.Pp
The collect function should return one of
.Dv ARG_ERR_NO_MATCH , ARG_ERR_BAD_ARG , ARG_ERR_NO_ARG
on error, zero otherwise.
.Pp
For your convenience there is a function,
.Fn getarg_optarg ,
that returns the traditional argument string, and you pass it all
arguments, sans data, that where given to the collection function.
.Pp
Don't use this more this unless you absolutely have to.
.El
.Pp
Option parsing is similar to what
.Xr getopt
uses. Short options without arguments can be compressed
.Pf ( Fl xyz
is the same as
.Fl x y z ) ,
and short
options with arguments take these as either the rest of the
argv-string or as the next option
.Pf ( Fl o Ns Ar foo ,
or
.Fl o Ar foo ) .
.Pp
Long option names are prefixed with -- (double dash), and the value
with a = (equal),
.Fl -foo= Ns Ar bar .
Long option flags can either be specified as they are
.Pf ( Fl -help ) ,
or with an (boolean parsable) option
.Pf ( Fl -help= Ns Ar yes ,
.Fl -help= Ns Ar true ,
or similar), or they can also be negated
.Pf ( Fl -no-help
is the same as
.Fl -help= Ns no ) ,
and if you're really confused you can do it multiple times
.Pf ( Fl -no-no-help= Ns Ar false ,
or even
.Fl -no-no-help= Ns Ar maybe ) .
.Sh EXAMPLE
.Bd -literal
#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\en", progname);
	exit(1);
    }
    if (strcmp(source, destination) == 0) {
	fprintf(stderr, "%s: destination must be different from source\en");
	exit(1);
    }
    /* include more stuff here ... */
    exit(2);
}
.Ed
.Pp
The output help output from this program looks like this:
.Bd -literal
$ 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
.Ed
.Sh BUGS
It should be more flexible, so it would be possible to use other more
complicated option syntaxes, such as what
.Xr ps 1 ,
and
.Xr tar 1 ,
uses, or the AFS model where you can skip the flag names as long as
the options come in the correct order.
.Pp
Options with multiple arguments should be handled better.
.Pp
Should be integreated with SL.
.Pp
It's very confusing that the struct you pass in is called getargS.
.Sh SEE ALSO
.Xr getopt 3
OpenPOWER on IntegriCloud