2 This file is part of GNUnet.
3 Copyright (C) 2001-2013 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
22 * @author Christian Grothoff
25 * Command line parsing and --help formatting
27 * @defgroup getopt Getopt library
28 * Command line parsing and --help formatting
32 #ifndef GNUNET_GETOPT_LIB_H
33 #define GNUNET_GETOPT_LIB_H
38 #if 0 /* keep Emacsens' auto-indent happy */
43 #include "gnunet_configuration_lib.h"
46 * @brief General context for command line processors.
48 struct GNUNET_GETOPT_CommandLineProcessorContext
52 * Name of the application
54 const char *binaryName;
57 * Name of application with option summary
59 const char *binaryOptions;
62 * Array with all command line options.
64 const struct GNUNET_GETOPT_CommandLineOption *allOptions;
67 * Original command line
72 * Total number of argv's.
79 unsigned int currentArgument;
85 * @brief Process a command line option
87 * @param ctx context for all options
88 * @param scls specific closure (for this processor)
89 * @param option long name of the option (i.e. "config" for --config)
90 * @param value argument, NULL if none was given
91 * @return #GNUNET_OK to continue processing other options, #GNUNET_SYSERR to abort
94 (*GNUNET_GETOPT_CommandLineOptionProcessor) (struct
95 GNUNET_GETOPT_CommandLineProcessorContext *ctx,
102 * @brief Definition of a command line option.
104 struct GNUNET_GETOPT_CommandLineOption
108 * Short name of the option.
110 const char shortName;
113 * Long name of the option (may not be NULL)
118 * Name of the argument for the user in help text
120 const char *argumentHelp;
123 * Help text for the option (description)
125 const char *description;
128 * Is an argument required? #GNUNET_NO (includes optional) or
129 * #GNUNET_YES (required)
131 int require_argument;
134 * Is the presence of this option mandatory?
136 int option_mandatory;
139 * Handler for the option.
141 GNUNET_GETOPT_CommandLineOptionProcessor processor;
144 * Function to call on @e scls to clean up after processing all
145 * the arguments. Can be NULL.
147 void (*cleaner)(void *cls);
150 * Specific closure to pass to the processor.
158 * Defining the option to print the command line
159 * help text (-h option).
161 * @param about string with brief description of the application
163 struct GNUNET_GETOPT_CommandLineOption
164 GNUNET_GETOPT_option_help (const char *about);
168 * Define the option to print the version of
169 * the application (-v option)
171 * @param version string with the version number
173 struct GNUNET_GETOPT_CommandLineOption
174 GNUNET_GETOPT_option_version (const char *version);
179 * Allow user to specify log file name (-l option)
181 * @param[out] logfn set to the name of the logfile
183 struct GNUNET_GETOPT_CommandLineOption
184 GNUNET_GETOPT_option_logfile (char **logfn);
188 * Allow user to specify a string.
190 * @param shortName short name of the option
191 * @param name long name of the option
192 * @param argumentHelp help text for the option argument
193 * @param description long help text for the option
194 * @param[out] str set to the string
196 struct GNUNET_GETOPT_CommandLineOption
197 GNUNET_GETOPT_option_string (char shortName,
199 const char *argumentHelp,
200 const char *description,
204 * Allow user to specify a filename (automatically path expanded).
206 * @param shortName short name of the option
207 * @param name long name of the option
208 * @param argumentHelp help text for the option argument
209 * @param description long help text for the option
210 * @param[out] str set to the string
212 struct GNUNET_GETOPT_CommandLineOption
213 GNUNET_GETOPT_option_filename (char shortName,
215 const char *argumentHelp,
216 const char *description,
221 * Allow user to specify a binary value using Crockford
224 * @param shortName short name of the option
225 * @param name long name of the option
226 * @param argumentHelp help text for the option argument
227 * @param description long help text for the option
228 * @param[out] val binary value decoded from Crockford Base32-encoded argument
229 * @param val_size size of @a val in bytes
231 struct GNUNET_GETOPT_CommandLineOption
232 GNUNET_GETOPT_option_base32_fixed_size (char shortName,
234 const char *argumentHelp,
235 const char *description,
241 * Allow user to specify a binary value using Crockford
242 * Base32 encoding where the size of the binary value is
243 * automatically determined from its type.
245 * @param shortName short name of the option
246 * @param name long name of the option
247 * @param argumentHelp help text for the option argument
248 * @param description long help text for the option
249 * @param[out] val binary value decoded from Crockford Base32-encoded argument;
250 * size is determined by type (sizeof (*val)).
252 #define GNUNET_GETOPT_option_base32_auto(shortName,name,argumentHelp,description,val) \
253 GNUNET_GETOPT_option_base32_fixed_size(shortName,name,argumentHelp,description,val,sizeof(*val))
257 * Allow user to specify a flag (which internally means setting
258 * an integer to 1/#GNUNET_YES/#GNUNET_OK.
260 * @param shortName short name of the option
261 * @param name long name of the option
262 * @param description long help text for the option
263 * @param[out] val set to 1 if the option is present
265 struct GNUNET_GETOPT_CommandLineOption
266 GNUNET_GETOPT_option_flag (char shortName,
268 const char *description,
273 * Allow user to specify an `unsigned int`.
275 * @param shortName short name of the option
276 * @param name long name of the option
277 * @param argumentHelp help text for the option argument
278 * @param description long help text for the option
279 * @param[out] val set to the value specified at the command line
281 struct GNUNET_GETOPT_CommandLineOption
282 GNUNET_GETOPT_option_uint (char shortName,
284 const char *argumentHelp,
285 const char *description,
290 * Allow user to specify an uint16_t.
292 * @param shortName short name of the option
293 * @param name long name of the option
294 * @param argumentHelp help text for the option argument
295 * @param description long help text for the option
296 * @param[out] val set to the value specified at the command line
298 struct GNUNET_GETOPT_CommandLineOption
299 GNUNET_GETOPT_option_uint16 (char shortName,
301 const char *argumentHelp,
302 const char *description,
307 * Allow user to specify an `unsigned long long`.
309 * @param shortName short name of the option
310 * @param name long name of the option
311 * @param argumentHelp help text for the option argument
312 * @param description long help text for the option
313 * @param[out] val set to the value specified at the command line
315 struct GNUNET_GETOPT_CommandLineOption
316 GNUNET_GETOPT_option_ulong (char shortName,
318 const char *argumentHelp,
319 const char *description,
320 unsigned long long *val);
324 * Allow user to specify a `struct GNUNET_TIME_Relative`
325 * (using human-readable "fancy" time).
327 * @param shortName short name of the option
328 * @param name long name of the option
329 * @param argumentHelp help text for the option argument
330 * @param description long help text for the option
331 * @param[out] val set to the time specified at the command line
333 struct GNUNET_GETOPT_CommandLineOption
334 GNUNET_GETOPT_option_relative_time (char shortName,
336 const char *argumentHelp,
337 const char *description,
338 struct GNUNET_TIME_Relative *val);
342 * Allow user to specify a `struct GNUNET_TIME_Absolute`
343 * (using human-readable "fancy" time).
345 * @param shortName short name of the option
346 * @param name long name of the option
347 * @param argumentHelp help text for the option argument
348 * @param description long help text for the option
349 * @param[out] val set to the time specified at the command line
351 struct GNUNET_GETOPT_CommandLineOption
352 GNUNET_GETOPT_option_absolute_time (char shortName,
354 const char *argumentHelp,
355 const char *description,
356 struct GNUNET_TIME_Absolute *val);
360 * Increment @a val each time the option flag is given by one.
362 * @param shortName short name of the option
363 * @param name long name of the option
364 * @param argumentHelp help text for the option argument
365 * @param description long help text for the option
366 * @param[out] val set to 1 if the option is present
368 struct GNUNET_GETOPT_CommandLineOption
369 GNUNET_GETOPT_option_increment_uint (char shortName,
371 const char *description,
376 * Define the '-L' log level option. Note that we do not check
377 * that the log level is valid here.
379 * @param[out] level set to the log level
381 struct GNUNET_GETOPT_CommandLineOption
382 GNUNET_GETOPT_option_loglevel (char **level);
386 * Define the '-V' verbosity option. Using the option more
387 * than once increments @a level each time.
389 * @param[out] level set to the verbosity level
391 struct GNUNET_GETOPT_CommandLineOption
392 GNUNET_GETOPT_option_verbose (unsigned int *level);
396 * Allow user to specify log file name (-l option)
398 * @param[out] logfn set to the name of the logfile
400 struct GNUNET_GETOPT_CommandLineOption
401 GNUNET_GETOPT_option_logfile (char **logfn);
405 * Allow user to specify configuration file name (-c option)
407 * @param[out] fn set to the name of the configuration file
409 struct GNUNET_GETOPT_CommandLineOption
410 GNUNET_GETOPT_option_cfgfile (char **fn);
414 * Make the given option mandatory.
416 * @param opt option to modify
417 * @return @a opt with the mandatory flag set.
419 struct GNUNET_GETOPT_CommandLineOption
420 GNUNET_GETOPT_option_mandatory (struct GNUNET_GETOPT_CommandLineOption opt);
424 * Marker for the end of the list of options.
426 #define GNUNET_GETOPT_OPTION_END \
427 { '\0', NULL, NULL, NULL, 0, 0, NULL, NULL, NULL }
431 * Parse the command line.
433 * @param binaryOptions Name of application with option summary
434 * @param allOptions defined options and handlers
435 * @param argc number of arguments in @a argv
436 * @param argv actual arguments
437 * @return index into argv with first non-option
438 * argument, or #GNUNET_SYSERR on error
441 GNUNET_GETOPT_run (const char *binaryOptions,
442 const struct GNUNET_GETOPT_CommandLineOption *allOptions,
447 #if 0 /* keep Emacsens' auto-indent happy */
454 /* ifndef GNUNET_GETOPT_LIB_H */
457 /** @} */ /* end of group getopt */
459 /* end of gnunet_getopt_lib.h */