Grid Community Toolkit  6.2.1541705016
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 
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
29 extern "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 
74 typedef 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 
95 typedef 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 
116 typedef 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 
160 int
161 globus_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 
183 void
184 globus_args_option_instance_list_free( globus_list_t ** list );
185 
186 
187 /* provided predicate functions */
188 
189 
190 int
191 globus_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 
204 typedef 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 
220 int
221 globus_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 */
235 int
236 globus_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.
List data type.
Definition: globus_list.h:43