globus_common  17.11
globus_args.h
Go to the documentation of this file.
1 
7 #ifndef GLOBUS_ARGS_H
8 #define GLOBUS_ARGS_H
9 
10 #include "globus_module.h"
11 #include "globus_list.h"
12 
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16 
17 #define GLOBUS_ARGS_HELP -2 /* for -help and -usage */
18 #define GLOBUS_ARGS_VERSION -3 /* for -version and -versions */
19 
20 
21 /* globus_args.h : a Globus-style argument option parser
22 
23  The API implements the following behavior:
24 
25  (1) Valid flags are detected as one '-' followed by any character that is
26  not '-'.
27 
28  (2) A flag may have zero or more predicates (values) associated with it,
29  but for any given flag the number of those (the arity) is fixed.
30 
31  (3) If a flag has arity of k>0, then the k arguments following the flag
32  are taken verbatim as the predicates associated with the flag,
33  including leading '-', if any.
34 
35  (4) Flagged arguments must not be combined (i.e., "-fg" is never the same
36  as "-f -g".
37 
38  (5) The end of flagged arguments will be detected either implicitly (with
39  the first unrecognized or non-flagged argument) or explicitly (when
40  "--" is detected when scanning for the next argument flag).
41 
42  (6) When scanning for the next argument flag, an error is detected if the
43  detected argument begins with "--*", where '*' is any character.
44 
45  (7) The argument flags "-help", "-usage", "-version", and "-versions" are
46  reserved, and if they are detected the library will create an
47  appropriate message and signal an error.
48 
49  (8) If an error is detected, then the library will create an error message.
50 
51  (9) A created error message will be written to stderr, unless dictated
52  otherwise by the user (in which case the error message will be passed
53  back to the user).
54 */
55 
56 
57 /* prototype definition of the predicate test function */
58 
59 typedef int (*globus_args_valid_predicate_t) (char * arg_value,
60  void * validation_value,
61  char ** error_msg);
62 
63 
64 /* option specification datatype
65 
66  An option can have several names: "-foo" or "-f" for short, etc.
67  The parsing library therefore identifies an option trough its
68  id_number. The user must ensure that the id_number is unique for
69  each descriptor_t.
70 
71  The arity of an option is defined as its number of predicates
72  (following arguments): "-debug" has arity 0, "-foo xyz 123"
73  has arity 2, etc.
74 
75  The array of predicate test functions, "tests", may be or contain
76  GLOBUS_NULL. Any non-null entry in the tests array must have a
77  non-null entry in the "test_parms" array.
78 */
79 
80 typedef struct globus_args_option_descriptor_s
81 {
82  int id_number; /* unique integer */
83  char ** names; /* null-terminated array */
84  int arity; /* number of arguments */
85  globus_args_valid_predicate_t * tests; /* array of size "arity" */
86  void ** test_parms; /* test function parms */
87 } globus_args_option_descriptor_t;
88 
89 
90 /* option instance datatype
91 
92  when a correctly specified argument option is found, an instance of it
93  is recorded and returned on the format specified in this struct. The
94  'arity' is provided for user-level consistency checks.
95 
96  'value' is an array of pointers to the option's predicates: these are
97  pointers to entries in argv[], and should therefore be treated as
98  read-only, to conform with POSIX standard.
99 */
100 
101 typedef struct globus_args_option_instance_s
102 {
103  int id_number;
104  int arity;
105  char ** values;
106 } globus_args_option_instance_t;
107 
108 
109 
110 /* globus_args_scan() -- the parsing function
111 
112  This function scans the argument list 'argv', validates the
113  arguments as appropriate, and builds an ordered list with the
114  successfully validated argument options.
115 
116  An option is successfully validated if it is found in the
117  'options' array, and the predicate values associated with it
118  passes the predicate test functions associated with the same
119  option.
120 
121  If 'error_msg' is null, messages will be written to
122  stderr. Otherwise, it will be pointed to an allocated buffer which
123  must be freed by the user, containing the error message.
124 
125  A 'reserved option' is one of the 0-arity options "-help",
126  "-usage", "-version", or "-versions". When detected, a message is created
127  (and written to stderr if error_msg is null), containing the
128  appropriate information. A reserved option will terminate the
129  argument scanning and return.
130 
131  The successfully validated options are removed from the 'argv' list
132  unless an error is detected. 'argc' is updated accordingly. The
133  argc/argv convention with argv[0] being the name of the executable
134  is maintained.
135 
136  Returns:
137  -> The number of successfully identified and validated options.
138  -> -1 if an error was detected
139  -> GLOBUS_ARGS_HELP or GLOBUS_ARGS_VERSION
140  if the corresponding reserved option was detected
141  (all < 0)
142 
143 */
144 
145 int
146 globus_args_scan( int * argc,
147  char *** argv,
148  int option_count,
149  globus_args_option_descriptor_t * options,
150  const char * name,
151  const globus_version_t * version,
152  const char * oneline_usage,
153  const char * long_usage,
154  globus_list_t ** options_found,
155  char ** error_msg );
156 
157 
158 /* globus_args_destroy_option_instance_list()
159 
160  globus_args_destroy_option_instance_list() correctly destroys the
161  list of globus_args_option_instance_t, created by
162  globus_args_scan(). It takes into account the dynamically allocated
163  elements in the struct : just calling globus_list_destroy() will
164  cause memory leaks.
165 
166  */
167 
168 void
169 globus_args_option_instance_list_free( globus_list_t ** list );
170 
171 
172 /* provided predicate functions */
173 
174 
175 int
176 globus_validate_int( char * value,
177  void * parms,
178  char ** error_msg );
179 
180 /* globus_args_validate_int() verifies that value is a valid integer (in
181  octal, decimal, or hexadecimal format) and does further validation based
182  on the values in *parms, which is of the following range check type */
183 
184 #define GLOBUS_VALIDATE_INT_NOCHECK 0x00
185 #define GLOBUS_VALIDATE_INT_MIN 0x01
186 #define GLOBUS_VALIDATE_INT_MAX 0x02
187 #define GLOBUS_VALIDATE_INT_MINMAX 0x03 /* 3 == (min | max) */
188 
189 typedef struct globus_validate_int_parms_s
190 {
191  int range_type; /* one of GLOBUS_VALIDATE_INT_* */
192  int range_min; /* inclusive min value */
193  int range_max; /* inclusive max value */
194 } globus_validate_int_parms_t;
195 
196 
197 
198 /* globus_validate_filename() verifies that value is a valid file (and
199  path), based on *parms, which is an int with one or several values of
200  the standard O_RDONLY, O_RDWR, O_CREAT, O_WRONLY, O_APPEND.
201 
202  NOTE: the validation is done by actually trying to open the file in
203  the mode described by *parms. */
204 
205 int
206 globus_validate_filename( char * value,
207  void * parms,
208  char ** error_msg );
209 
210 
211 /* ----------------------------------------------------------------------------
212  globus_bytestr_to_num()
213 
214  converts a string such as 40M, 256K, 2G to an equivalent off_t.
215  Valid multipliers are G,g, M,m, K,k, B,b.
216 
217  Returns 0 on success, nonzero on error.
218 
219 */
220 int
221 globus_args_bytestr_to_num(
222  const char * str,
223  globus_off_t * out);
224 
225 #ifdef __cplusplus
226 }
227 #endif
228 
229 #endif /* ifndef GLOBUS_ARGS_H */
Linked List.
Reference Counting Module Activation and Deactivation.
List data type.
Definition: globus_list.h:29