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