2 GETARG(3) UNIX Programmer's Manual GETARG(3)
5 g
\bge
\bet
\bta
\bar
\brg
\bg, a
\bar
\brg
\bg_
\b_p
\bpr
\bri
\bin
\bnt
\btu
\bus
\bsa
\bag
\bge
\be - collect command line options
7 S
\bSY
\bYN
\bNO
\bOP
\bPS
\bSI
\bIS
\bS
9 g
\bge
\bet
\bta
\bar
\brg
\bg(_
\bs_
\bt_
\br_
\bu_
\bc_
\bt _
\bg_
\be_
\bt_
\ba_
\br_
\bg_
\bs _
\b*_
\ba_
\br_
\bg_
\bs, _
\bs_
\bi_
\bz_
\be_
\b__
\bt _
\bn_
\bu_
\bm_
\b__
\ba_
\br_
\bg_
\bs, _
\bi_
\bn_
\bt _
\ba_
\br_
\bg_
\bc, _
\bc_
\bh_
\ba_
\br _
\b*_
\b*_
\ba_
\br_
\bg_
\bv,
10 _
\bi_
\bn_
\bt _
\b*_
\bo_
\bp_
\bt_
\bi_
\bn_
\bd)
13 a
\bar
\brg
\bg_
\b_p
\bpr
\bri
\bin
\bnt
\btu
\bus
\bsa
\bag
\bge
\be(_
\bs_
\bt_
\br_
\bu_
\bc_
\bt _
\bg_
\be_
\bt_
\ba_
\br_
\bg_
\bs _
\b*_
\ba_
\br_
\bg_
\bs, _
\bs_
\bi_
\bz_
\be_
\b__
\bt _
\bn_
\bu_
\bm_
\b__
\ba_
\br_
\bg_
\bs,
14 _
\bc_
\bo_
\bn_
\bs_
\bt _
\bc_
\bh_
\ba_
\br _
\b*_
\bp_
\br_
\bo_
\bg_
\bn_
\ba_
\bm_
\be, _
\bc_
\bo_
\bn_
\bs_
\bt _
\bc_
\bh_
\ba_
\br _
\b*_
\be_
\bx_
\bt_
\br_
\ba_
\b__
\bs_
\bt_
\br_
\bi_
\bn_
\bg)
16 D
\bDE
\bES
\bSC
\bCR
\bRI
\bIP
\bPT
\bTI
\bIO
\bON
\bN
17 g
\bge
\bet
\bta
\bar
\brg
\bg() collects any command line options given to a program in an easi-
18 ly used way. a
\bar
\brg
\bg_
\b_p
\bpr
\bri
\bin
\bnt
\btu
\bus
\bsa
\bag
\bge
\be() pretty-prints the available options, with
21 _
\ba_
\br_
\bg_
\bs is the option specification to use, and it's an array of _
\bs_
\bt_
\br_
\bu_
\bc_
\bt
22 _
\bg_
\be_
\bt_
\ba_
\br_
\bg_
\bs elements. _
\bn_
\bu_
\bm_
\b__
\ba_
\br_
\bg_
\bs is the size of _
\ba_
\br_
\bg_
\bs (in elements). _
\ba_
\br_
\bg_
\bc and
23 _
\ba_
\br_
\bg_
\bv are the argument count and argument vector to extract option from.
24 _
\bo_
\bp_
\bt_
\bi_
\bn_
\bd is a pointer to an integer where the index to the last processed
25 argument is stored, it must be initialised to the first index (minus one)
26 to process (normally 0) before the first call.
28 _
\ba_
\br_
\bg_
\b__
\bp_
\br_
\bi_
\bn_
\bt_
\bu_
\bs_
\ba_
\bg_
\be take the same _
\ba_
\br_
\bg_
\bs and _
\bn_
\bu_
\bm_
\b__
\ba_
\br_
\bg_
\bs as getarg; _
\bp_
\br_
\bo_
\bg_
\bn_
\ba_
\bm_
\be is the
29 name of the program (to be used in the help text), and _
\be_
\bx_
\bt_
\br_
\ba_
\b__
\bs_
\bt_
\br_
\bi_
\bn_
\bg is a
30 string to print after the actual options to indicate more arguments. The
31 usefulness of this function is realised only be people who has used pro-
32 grams that has help strings that doesn't match what the code does.
34 The _
\bg_
\be_
\bt_
\ba_
\br_
\bg_
\bs struct has the following elements.
37 const char *long_name;
52 _
\bl_
\bo_
\bn_
\bg_
\b__
\bn_
\ba_
\bm_
\be is the long name of the option, it can be NULL, if you don't
53 want a long name. _
\bs_
\bh_
\bo_
\br_
\bt_
\b__
\bn_
\ba_
\bm_
\be is the characted to use as short option, it
54 can be zero. If the option has a value the _
\bv_
\ba_
\bl_
\bu_
\be field gets filled in
55 with that value interpreted as specified by the _
\bt_
\by_
\bp_
\be field. _
\bh_
\be_
\bl_
\bp is a
56 longer help string for the option as a whole, if it's NULL the help text
57 for the option is omitted (but it's still displayed in the synopsis).
58 _
\ba_
\br_
\bg_
\b__
\bh_
\be_
\bl_
\bp is a description of the argument, if NULL a default value will
59 be used, depending on the type of the option:
61 arg_integer the argument is a signed integer, and _
\bv_
\ba_
\bl_
\bu_
\be should
62 point to an _
\bi_
\bn_
\bt.
64 _
\ba_
\br_
\bg_
\b__
\bs_
\bt_
\br_
\bi_
\bn_
\bg the argument is a string, and _
\bv_
\ba_
\bl_
\bu_
\be should point to a
68 _
\ba_
\br_
\bg_
\b__
\bf_
\bl_
\ba_
\bg the argument is a flag, and _
\bv_
\ba_
\bl_
\bu_
\be should point to a
69 _
\bi_
\bn_
\bt. It gets filled in with either zero or one, de-
70 pending 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
75 _
\ba_
\br_
\bg_
\b__
\bn_
\be_
\bg_
\ba_
\bt_
\bi_
\bv_
\be_
\b__
\bf_
\bl_
\ba_
\bg this is the same as _
\ba_
\br_
\bg_
\b__
\bf_
\bl_
\ba_
\bg 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.
79 _
\ba_
\br_
\bg_
\b__
\bs_
\bt_
\br_
\bi_
\bn_
\bg_
\bs the argument can be given multiple times, and the val-
80 ues are collected in an array; _
\bv_
\ba_
\bl_
\bu_
\be should be a
81 pointer to a _
\bs_
\bt_
\br_
\bu_
\bc_
\bt _
\bg_
\be_
\bt_
\ba_
\br_
\bg_
\b__
\bs_
\bt_
\br_
\bi_
\bn_
\bg_
\bs structure, which
82 holds a length and a string pointer.
84 _
\ba_
\br_
\bg_
\b__
\bd_
\bo_
\bu_
\bb_
\bl_
\be argument is a double precision floating point value,
85 and _
\bv_
\ba_
\bl_
\bu_
\be should point to a _
\bd_
\bo_
\bu_
\bb_
\bl_
\be.
87 _
\ba_
\br_
\bg_
\b__
\bc_
\bo_
\bl_
\bl_
\be_
\bc_
\bt allows more fine-grained control of the option parsing
88 process. _
\bv_
\ba_
\bl_
\bu_
\be should be a pointer to a
89 _
\bg_
\be_
\bt_
\ba_
\br_
\bg_
\b__
\bc_
\bo_
\bl_
\bl_
\be_
\bc_
\bt_
\b__
\bi_
\bn_
\bf_
\bo structure:
91 typedef int (*getarg_collect_func)(int short_opt,
98 typedef struct getarg_collect_info {
99 getarg_collect_func func;
101 } getarg_collect_info;
103 With the _
\bf_
\bu_
\bn_
\bc member set to a function to call, and
104 _
\bd_
\ba_
\bt_
\ba to some application specific data. The parameters
105 to the collect function are:
107 _
\bs_
\bh_
\bo_
\br_
\bt_
\b__
\bf_
\bl_
\ba_
\bg non-zero if this call is via a short option
110 _
\ba_
\br_
\bg_
\bc, _
\ba_
\br_
\bg_
\bv the whole argument list
112 _
\bo_
\bp_
\bt_
\bi_
\bn_
\bd pointer to the index in argv where the flag is
114 _
\bo_
\bp_
\bt_
\ba_
\br_
\bg pointer to the index in argv[*optind] where the
117 _
\bd_
\ba_
\bt_
\ba application specific data
119 You can modify _
\b*_
\bo_
\bp_
\bt_
\bi_
\bn_
\bd, and _
\b*_
\bo_
\bp_
\bt_
\ba_
\br_
\bg, but to do this
120 correct you (more or less) have to know about the in-
121 ner workings of getarg.
123 You can skip parts of arguments by increasing _
\b*_
\bo_
\bp_
\bt_
\ba_
\br_
\bg
124 (you could implement the -
\b-z
\bz_
\b3 set of flags from g
\bgz
\bzi
\bip
\bp
125 with this), or whole argument strings by increasing
126 _
\b*_
\bo_
\bp_
\bt_
\bi_
\bn_
\bd (let's say you want a flag -
\b-c
\bc _
\bx _
\by _
\bz to specify
127 a coordinate); if you also have to set _
\b*_
\bo_
\bp_
\bt_
\ba_
\br_
\bg to a
130 The collect function should return one of
131 ARG_ERR_NO_MATCH, ARG_ERR_BAD_ARG, ARG_ERR_NO_ARG on
132 error, zero otherwise.
134 For your convenience there is a function,
135 g
\bge
\bet
\bta
\bar
\brg
\bg_
\b_o
\bop
\bpt
\bta
\bar
\brg
\bg(), that returns the traditional argument
136 string, and you pass it all arguments, sans data, that
137 where given to the collection function.
139 Don't use this more this unless you absolutely have
142 Option parsing is similar to what getopt uses. Short options without ar-
143 guments can be compressed (-
\b-x
\bxy
\byz
\bz is the same as -
\b-x
\bx -
\b-y
\by -
\b-z
\bz), and short op-
144 tions with arguments take these as either the rest of the argv-string or
145 as the next option (-
\b-o
\bo_
\bf_
\bo_
\bo, or -
\b-o
\bo _
\bf_
\bo_
\bo).
147 Long option names are prefixed with -- (double dash), and the value with
148 a = (equal), -
\b--
\b-f
\bfo
\boo
\bo=
\b=_
\bb_
\ba_
\br. Long option flags can either be specified as they
149 are (-
\b--
\b-h
\bhe
\bel
\blp
\bp), or with an (boolean parsable) option (-
\b--
\b-h
\bhe
\bel
\blp
\bp=
\b=_
\by_
\be_
\bs,
150 -
\b--
\b-h
\bhe
\bel
\blp
\bp=
\b=_
\bt_
\br_
\bu_
\be, or similar), or they can also be negated (-
\b--
\b-n
\bno
\bo-
\b-h
\bhe
\bel
\blp
\bp is the
151 same as -
\b--
\b-h
\bhe
\bel
\blp
\bp=
\b=no), and if you're really confused you can do it multiple
152 times (-
\b--
\b-n
\bno
\bo-
\b-n
\bno
\bo-
\b-h
\bhe
\bel
\blp
\bp=
\b=_
\bf_
\ba_
\bl_
\bs_
\be, or even -
\b--
\b-n
\bno
\bo-
\b-n
\bno
\bo-
\b-h
\bhe
\bel
\blp
\bp=
\b=_
\bm_
\ba_
\by_
\bb_
\be).
154 E
\bEX
\bXA
\bAM
\bMP
\bPL
\bLE
\bE
159 char *source = "Ouagadougou";
162 int include_catalog = 1;
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 }
177 int num_args = sizeof(args) / sizeof(args[0]); /* number of elements in args */
179 const char *progname = "ship++";
182 main(int argc, char **argv)
185 if (getarg(args, num_args, argc, argv, &optind)) {
186 arg_printusage(args, num_args, progname, "stuff...");
190 arg_printusage(args, num_args, progname, "stuff...");
193 if (destination == NULL) {
194 fprintf(stderr, "%s: must specify destination\n", progname);
197 if (strcmp(source, destination) == 0) {
198 fprintf(stderr, "%s: destination must be different from source\n");
201 /* include more stuff here ... */
205 The output help output from this program looks like this:
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
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
218 the AFS model where you can skip the flag names as long as the options
219 come in the correct order.
221 Options with multiple arguments should be handled better.
223 Should be integreated with SL.
225 It's very confusing that the struct you pass in is called getargS.
227 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
230 ROKEN September 24, 1999 4