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