1ALL_OPT(3) LAM INTERNALS ALL_OPT(3)
2
6 all_opt - general purpose command-line options parsing (LAM)
7
9 #include <all_opt.h>
10 char *ao_argv0(OPT *aod);
12 OPT *ao_init(void);
13 char *ao_chosen(OPT *od, const char *opt);
14 void ao_free(OPT *od);
15 int ao_intparam(OPT *od, const char *opt,
16 int inst, int idx, int *inum);
17 int ao_ninsts(OPT *od, const char *opt);
18 int ao_nparams(OPT *od, const char *opt, int inst);
19 int ao_ntaken(OPT *od);
20 char *ao_param(OPT *od, const char *opt, int inst, int idx);
21 int ao_parse(OPT *od, int *argc, char **argv);
22 int ao_setflags(OPT *aod, int flags);
23 int ao_setopt(OPT *od, const char *opt,
24 const char *mutex, int nparams, int flags);
25 int ao_setopt1(OPT *od, const char *opt,
26 const char *mutex, int nparams, int flags);
27 int ao_tail(OPT *od, int *tailc, char ***tailv);
28 int ao_taken(OPT *od, const char *opt);
29 int ao_unused(OPT *aod, int *unusedc, char ***unusedv);
30
32 The all_opt package provides general purpose command-line option pars‐
33 ing. It parses multi-letter option strings with varying numbers of
34 parameters and invocations. Options can be made mandatory as well as
35 grouped into mutually exclusive sets. all_opt can handle multiple com‐
36 mand-line parsing invocations by maintaining a separate option descrip‐
37 tor for each one.
38 An option descriptor is created and initialized by the ao_init() func‐
40 tion. It returns a pointer to a new descriptor, typedef OPT (defined
41 in <all_opt.h>). This descriptor pointer is used as the first argument
42 to all the other functions. When no longer needed, a descriptor can be
43 destroyed by calling ao_free().
44 Once a descriptor is created, the user declares each valid command-line
46 option string by calling ao_setopt(). The function's arguments are:
47 ad, the option descriptor; opt, the option string being declared;
48 mutex, an option string in the set of mutually exclusive options (or
49 NULL if not used); nparams, the number of parameters expected to follow
50 this option (or AOVARNUM if variable); and flags, a bit-mapped field of
51 flags controlling other characteristics of the option. The flags value
52 is constructed by ORing flags from the following list:
53 AOINT All arguments following the option are integers.
55 AOMUST The option is mandatory and must be taken. If the option is
57 part of a mutually exclusive set, all options in the set must
58 also have this flag set.
59 ao_setopt1() is a convenience function that interprets the opt argument
61 as a string of single letter options and calls ao_setopt() for each
62 letter with the other arguments given.
63 The option string "#" is reserved to represent the special case of the
65 "-#" option (i.e. a dash followed by an integer). The integer can be
66 either decimal, octal, or hexadecimal. This option implies that the
67 AOINT flag is set and that the nparams argument is 1.
68 Optional flags may be set on the descriptor with ao_setflags(). Cur‐
70 rently, the only flag that is supported is:
71 AOPRESERVE_ARGV
73 When this flag is set, the argc and argv that are passed into
74 ao_parse() (see below) are not modified. Instead, a copy is
75 made of argv and its results are stored internally in the
76 descriptor. All operations are then performed on that inter‐
77 nal copy. Using this flag also enables the use of the
78 ao_unused() function, which will return the unused tokens
79 after parsing (i.e., tokens that were not recognized options
80 and were not part of the tail).
81 After all valid options are declared, the command line arguments are
83 parsed by calling ao_parse(). The argc and argv parameters are those
84 passed to main(). Note that argc is passed by reference. Option
85 strings in the command-line (prefixed with the dash character '-') and
86 any parameters following them, are parsed and deleted from the argc,
87 argv structure, leaving in it any additional strings that are neither
88 options nor parameters. Options can be invoked multiple times,
89 ao_parse() maintains a count of these instances as well as potential
90 parameters for each option. A "--" argument notifies ao_parse() to
91 avoid processing the arguments that follow it. These unprocessed argu‐
92 ments at the tail end of the command-line can be retrieved by calling
93 ao_tail(). ao_parse() checks the command-line for invalid options and
94 parameters, and verifies that mutual exclusion is satisfied and manda‐
95 tory options are taken. Once the command-line options are parsed, the
96 user can make queries to check which options were actually taken and
97 what parameters were supplied.
98 Option Queries
100 The function ao_ntaken() returns the number of options taken, i.e. that
101 appeared on the command-line. ao_taken() checks if the given option
102 opt was taken, returning 1 (true) or 0 (false). The ao_chosen() func‐
103 tion simplifies the task of locating the single option taken in a mutu‐
104 ally exclusive set. The set is identified by setting opt to any of
105 member options in it. ao_chosen() returns the option taken or NULL if
106 none was chosen.
107 ao_ninsts() returns the number of times (instances) an option was
109 invoked on the command-line. This number can be helpful if an option
110 accepts parameters. It allows the user to request the different param‐
111 eters of each instance. Instances are numbered sequentially starting
112 with 0. If the option accepts a variable number of parameters,
113 ao_nparams() returns the number of parameters provided for an option's
114 given instance number inst. Parameters are identified by sequential
115 index values starting with 0. If the option takes integer parameters,
116 ao_intparam() can be used to retrieve a specific parameter given its
117 instance number inst and its index value idx. The parameter is
118 returned by reference in the inum variable. If the option parameters
119 are strings, ao_param() is used to return a specific parameter given
120 its instance and index values.
121 The tail end of the command-line, formed by all arguments to the right
123 of the "--" special option, can be retrieved by calling IR ao_tail() .
124 The tail is returned in the standard argc, argv format through the
125 tailc and tailv parameters passed by reference.
126
128 The following example code demonstrates how all_opt can be used to
129 parse command-lines. The hypothetical tool accepts two mutually exclu‐
130 sive options: "foo", "bar". The "foo" option requires 2 string parame‐
131 ters and can only be invoked once. For simplicity, error checking is
132 not done.
133 #include <all_opt.h>
135 main(int argc, char *argv[])
137 {
138 OPT *ad;
139 char *opt;
140 ad = ao_init();
142 ao_setopt(ad, "foo", NULL, 2, 0);
143 ao_setopt(ad, "bar", "foo", 0, 0);
144 ao_parse(ad, &argc, argv);
146 opt = ao_chosen(ad, "foo");
148 if (strcmp(opt, "foo") == 0) {
150 if (ao_ninsts(ad, "foo") > 1) { /* error */ }
152 printf("foo chosen: %s %s\n",
154 ao_param(ad, "foo", 0, 0),
155 ao_param(ad, "foo", 0, 1));
156 } else {
157 printf("bar taken %d times\n",
158 ao_ninsts(ad, "bar"));
159 }
160 ao_free(ad);
162 }
163
165 In case of an error, ao_init() returns a NULL descriptor, ao_chosen()
166 and ao_param() return NULL strings, and ao_intparam(), ao_parse(),
167 ao_setopt(), ao_setopt1(), and ao_tail() return -1. In addition, the
168 global variable errno is set to indicate the error.
169
171 EUSAGE The command-line violates the option rules.
172 EBADASCIINUMB A string representing an integer has an invalid format.
174LAM 7.1.2 March, 2006 ALL_OPT(3)