cmdline.h (4319B)
1 /* cmdline.h: a reentrant version of getopt(). Written 2006 by Brian
2 * Raiter. This code is in the public domain.
3 */
4
5 #ifndef _cmdline_h_
6 #define _cmdline_h_
7
8 /* The information specifying a single cmdline option.
9 */
10 typedef struct option {
11 char const *name; /* the option's long name, or "" if none */
12 char chname; /* a single-char name, or zero if none */
13 int optval; /* a unique value representing this option */
14 int arg; /* 0 = no arg, 1 = arg req'd, 2 = optional */
15 } option;
16
17 /* Parse the given cmdline arguments. list is an array of option
18 * structs, each entry specifying a valid option. The last struct in
19 * the array must have name set to NULL. argc and argv give the
20 * cmdline to parse. callback is the function to call for each option
21 * and non-option found on the cmdline. data is a pointer that is
22 * passed to each invocation of callback. The return value of callback
23 * should be zero to continue processing the cmdline, or any other
24 * value to abort. The return value of readoptions() is the value
25 * returned from the last callback, or zero if no arguments were
26 * found, or -1 if an error occurred.
27 *
28 * When readoptions() encounters a regular cmdline argument (i.e. a
29 * non-option argument), callback() is invoked with opt equal to zero
30 * and val pointing to the argument. When an option is found,
31 * callback() is invoked with opt equal to the optval field in the
32 * option struct corresponding to that option, and val points to the
33 * option's paramter, or is NULL if the option does not take a
34 * parameter. If readoptions() finds an option that does not appear in
35 * the list of valid options, callback() is invoked with opt equal to
36 * '?'. If readoptions() encounters an option that is missing its
37 * required parameter, callback() is invoked with opt equal to ':'. If
38 * readoptions() finds a parameter on a long option that does not
39 * admit a parameter, callback() is invoked with opt equal to '='. In
40 * each of these cases, val will point to the erroneous option
41 * argument.
42 */
43 extern int readoptions(option const* list, int argc, char **argv,
44 int (*callback)(int opt, char const *val, void *data),
45 void *data);
46
47 /* Parse the given file. list is an array of option structs, in the
48 * same form as taken by readoptions(). fp is a pointer to an open
49 * text file. callback is the function to call for each line found in
50 * the configuration file. data is a pointer that is passed to each
51 * invocation of callback. The return value of readcfgfile() is the
52 * value returned from the last callback, or zero if no arguments were
53 * found, or -1 if an error occurred while reading the file.
54 *
55 * The function will ignore lines that contain only whitespace, or
56 * lines that begin with a hash sign. All other lines should be of the
57 * form "OPTION=VALUE", where OPTION is one of the long options in
58 * list. Whitespace around the equal sign is permitted. An option that
59 * takes no arguments can either have a VALUE of 0 or 1, or omit the
60 * "=VALUE" entirely. (A VALUE of 0 will behave the same as if the
61 * line was not present.)
62 */
63 extern int readcfgfile(option const* list, FILE *fp,
64 int (*callback)(int opt, char const *val, void *data),
65 void *data);
66
67
68 /* Create an argc-argv pair from a string containing a command line.
69 * cmdline is the string to be parsed. argcp points to the variable to
70 * receive the argc value, and argvp points to the variable to receive
71 * the argv value. argvp can be NULL if the caller just wants to get
72 * argc. Zero is returned on failure. This function allocates memory
73 * on behalf of the caller. The memory is allocated as a single block,
74 * so it is sufficient to simply free() the pointer returned through
75 * argvp. Note that argv[0] will always be initialized to NULL; the
76 * first argument will be stored in argv[1]. The string is parsed by
77 * separating arguments on whitespace boundaries. Space within
78 * substrings enclosed in single-quotes is ignored. A substring
79 * enclosed in double-quotes is treated the same, except that the
80 * backslash is recognized as an escape character within such a
81 * substring. Enclosing quotes and escaping backslashes are not copied
82 * into the argv values.
83 */
84 extern int makecmdline(char const *cmdline, int *argcp, char ***argvp);
85
86 #endif