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
37 #if 0 /* keep Emacsens' auto-indent happy */
42 #include "gnunet_configuration_lib.h"
45 * @brief General context for command line processors.
47 struct GNUNET_GETOPT_CommandLineProcessorContext
50 * Name of the application
52 const char *binaryName;
55 * Name of application with option summary
57 const char *binaryOptions;
60 * Array with all command line options.
62 const struct GNUNET_GETOPT_CommandLineOption *allOptions;
65 * Original command line
70 * Total number of argv's.
77 unsigned int currentArgument;
82 * @brief Process a command line option
84 * @param ctx context for all options
85 * @param scls specific closure (for this processor)
86 * @param option long name of the option (i.e. "config" for --config)
87 * @param value argument, NULL if none was given
88 * @return #GNUNET_OK to continue processing other options, #GNUNET_SYSERR to abort
90 typedef int (*GNUNET_GETOPT_CommandLineOptionProcessor) (
91 struct GNUNET_GETOPT_CommandLineProcessorContext *ctx,
98 * @brief Definition of a command line option.
100 struct GNUNET_GETOPT_CommandLineOption
103 * Short name of the option.
105 const char shortName;
108 * Long name of the option (may not be NULL)
113 * Name of the argument for the user in help text
115 const char *argumentHelp;
118 * Help text for the option (description)
120 const char *description;
123 * Is an argument required? #GNUNET_NO (includes optional) or
124 * #GNUNET_YES (required)
126 int require_argument;
129 * Is the presence of this option mandatory?
131 int option_mandatory;
134 * Is the option exclusive?
136 int option_exclusive;
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.
157 * Defining the option to print the command line
158 * help text (-h option).
160 * @param about string with brief description of the application
162 struct GNUNET_GETOPT_CommandLineOption
163 GNUNET_GETOPT_option_help (const char *about);
167 * Allow user to specify a `long long` with an offset to add to the current
168 * system time to construct the time seen by the application. Used for
169 * debugging / testing.
171 * @param shortName short name of the option
172 * @param name long name of the option
173 * @param[out] val set to the time specified at the command line
175 struct GNUNET_GETOPT_CommandLineOption
176 GNUNET_GETOPT_option_timetravel (char shortName,
181 * Define the option to print the version of
182 * the application (-v option)
184 * @param version string with the version number
186 struct GNUNET_GETOPT_CommandLineOption
187 GNUNET_GETOPT_option_version (const char *version);
191 * Allow user to specify log file name (-l option)
193 * @param[out] logfn set to the name of the logfile
195 struct GNUNET_GETOPT_CommandLineOption
196 GNUNET_GETOPT_option_logfile (char **logfn);
200 * Allow user to specify a string.
202 * @param shortName short name of the option
203 * @param name long name of the option
204 * @param argumentHelp help text for the option argument
205 * @param description long help text for the option
206 * @param[out] str set to the string
208 struct GNUNET_GETOPT_CommandLineOption
209 GNUNET_GETOPT_option_string (char shortName,
211 const char *argumentHelp,
212 const char *description,
216 * Allow user to specify a filename (automatically path expanded).
218 * @param shortName short name of the option
219 * @param name long name of the option
220 * @param argumentHelp help text for the option argument
221 * @param description long help text for the option
222 * @param[out] str set to the string
224 struct GNUNET_GETOPT_CommandLineOption
225 GNUNET_GETOPT_option_filename (char shortName,
227 const char *argumentHelp,
228 const char *description,
233 * Allow user to specify a binary value using Crockford
236 * @param shortName short name of the option
237 * @param name long name of the option
238 * @param argumentHelp help text for the option argument
239 * @param description long help text for the option
240 * @param[out] val binary value decoded from Crockford Base32-encoded argument
241 * @param val_size size of @a val in bytes
243 struct GNUNET_GETOPT_CommandLineOption
244 GNUNET_GETOPT_option_base32_fixed_size (char shortName,
246 const char *argumentHelp,
247 const char *description,
253 * Allow user to specify a binary value using Crockford
254 * Base32 encoding where the size of the binary value is
255 * automatically determined from its type.
257 * @param shortName short name of the option
258 * @param name long name of the option
259 * @param argumentHelp help text for the option argument
260 * @param description long help text for the option
261 * @param[out] val binary value decoded from Crockford Base32-encoded argument;
262 * size is determined by type (sizeof (*val)).
264 #define GNUNET_GETOPT_option_base32_auto(shortName, \
269 GNUNET_GETOPT_option_base32_fixed_size (shortName, \
278 * Allow user to specify a flag (which internally means setting
279 * an integer to 1/#GNUNET_YES/#GNUNET_OK.
281 * @param shortName short name of the option
282 * @param name long name of the option
283 * @param description long help text for the option
284 * @param[out] val set to 1 if the option is present
286 struct GNUNET_GETOPT_CommandLineOption
287 GNUNET_GETOPT_option_flag (char shortName,
289 const char *description,
294 * Allow user to specify an `unsigned int`.
296 * @param shortName short name of the option
297 * @param name long name of the option
298 * @param argumentHelp help text for the option argument
299 * @param description long help text for the option
300 * @param[out] val set to the value specified at the command line
302 struct GNUNET_GETOPT_CommandLineOption
303 GNUNET_GETOPT_option_uint (char shortName,
305 const char *argumentHelp,
306 const char *description,
311 * Allow user to specify an uint16_t.
313 * @param shortName short name of the option
314 * @param name long name of the option
315 * @param argumentHelp help text for the option argument
316 * @param description long help text for the option
317 * @param[out] val set to the value specified at the command line
319 struct GNUNET_GETOPT_CommandLineOption
320 GNUNET_GETOPT_option_uint16 (char shortName,
322 const char *argumentHelp,
323 const char *description,
328 * Allow user to specify an `unsigned long long`.
330 * @param shortName short name of the option
331 * @param name long name of the option
332 * @param argumentHelp help text for the option argument
333 * @param description long help text for the option
334 * @param[out] val set to the value specified at the command line
336 struct GNUNET_GETOPT_CommandLineOption
337 GNUNET_GETOPT_option_ulong (char shortName,
339 const char *argumentHelp,
340 const char *description,
341 unsigned long long *val);
345 * Allow user to specify a `struct GNUNET_TIME_Relative`
346 * (using human-readable "fancy" time).
348 * @param shortName short name of the option
349 * @param name long name of the option
350 * @param argumentHelp help text for the option argument
351 * @param description long help text for the option
352 * @param[out] val set to the time specified at the command line
354 struct GNUNET_GETOPT_CommandLineOption
355 GNUNET_GETOPT_option_relative_time (char shortName,
357 const char *argumentHelp,
358 const char *description,
359 struct GNUNET_TIME_Relative *val);
363 * Allow user to specify a `struct GNUNET_TIME_Absolute`
364 * (using human-readable "fancy" time).
366 * @param shortName short name of the option
367 * @param name long name of the option
368 * @param argumentHelp help text for the option argument
369 * @param description long help text for the option
370 * @param[out] val set to the time specified at the command line
372 struct GNUNET_GETOPT_CommandLineOption
373 GNUNET_GETOPT_option_absolute_time (char shortName,
375 const char *argumentHelp,
376 const char *description,
377 struct GNUNET_TIME_Absolute *val);
381 * Increment @a val each time the option flag is given by one.
383 * @param shortName short name of the option
384 * @param name long name of the option
385 * @param argumentHelp help text for the option argument
386 * @param description long help text for the option
387 * @param[out] val set to 1 if the option is present
389 struct GNUNET_GETOPT_CommandLineOption
390 GNUNET_GETOPT_option_increment_uint (char shortName,
392 const char *description,
397 * Define the '-L' log level option. Note that we do not check
398 * that the log level is valid here.
400 * @param[out] level set to the log level
402 struct GNUNET_GETOPT_CommandLineOption
403 GNUNET_GETOPT_option_loglevel (char **level);
407 * Define the '-V' verbosity option. Using the option more
408 * than once increments @a level each time.
410 * @param[out] level set to the verbosity level
412 struct GNUNET_GETOPT_CommandLineOption
413 GNUNET_GETOPT_option_verbose (unsigned int *level);
417 * Allow user to specify log file name (-l option)
419 * @param[out] logfn set to the name of the logfile
421 struct GNUNET_GETOPT_CommandLineOption
422 GNUNET_GETOPT_option_logfile (char **logfn);
426 * Allow user to specify configuration file name (-c option)
428 * @param[out] fn set to the name of the configuration file
430 struct GNUNET_GETOPT_CommandLineOption
431 GNUNET_GETOPT_option_cfgfile (char **fn);
435 * Make the given option mandatory.
437 * @param opt option to modify
438 * @return @a opt with the mandatory flag set.
440 struct GNUNET_GETOPT_CommandLineOption
441 GNUNET_GETOPT_option_mandatory (struct GNUNET_GETOPT_CommandLineOption opt);
445 * Make the given option mutually exclusive with other options.
447 * @param opt option to modify
448 * @return @a opt with the exclusive flag set.
450 struct GNUNET_GETOPT_CommandLineOption
451 GNUNET_GETOPT_option_exclusive (struct GNUNET_GETOPT_CommandLineOption opt);
455 * Marker for the end of the list of options.
457 #define GNUNET_GETOPT_OPTION_END \
459 '\0', NULL, NULL, NULL, 0, 0, 0, NULL, NULL, NULL \
464 * Parse the command line.
466 * @param binaryOptions Name of application with option summary
467 * @param allOptions defined options and handlers
468 * @param argc number of arguments in @a argv
469 * @param argv actual arguments
470 * @return index into argv with first non-option
471 * argument, or #GNUNET_SYSERR on error
474 GNUNET_GETOPT_run (const char *binaryOptions,
475 const struct GNUNET_GETOPT_CommandLineOption *allOptions,
480 #if 0 /* keep Emacsens' auto-indent happy */
487 /* ifndef GNUNET_GETOPT_LIB_H */
490 /** @} */ /* end of group getopt */
492 /* end of gnunet_getopt_lib.h */