libslack(prog) - program framework module
#include <slack/prog.h>
typedef struct option option; typedef struct Option Option; typedef struct Options Options;
typedef void (*opt_action_int_t)(int); typedef void (*opt_action_optional_int_t)(int *); typedef void (*opt_action_string_t)(const char *); typedef void (*opt_action_optional_string_t)(const char *); typedef void (*opt_action_none_t)(void);
enum OptionArgument { OPT_NONE, OPT_INTEGER, OPT_STRING };
enum OptionAction { OPT_NOTHING, OPT_VARIABLE, OPT_FUNCTION };
typedef enum OptionArgument OptionArgument; typedef enum OptionAction OptionAction;
struct Option { const char *name; char short_name; const char *argname; const char *desc; int has_arg; OptionArgument arg_type; OptionAction action; void *object; };
struct Options { Options *parent; Option *options; };
void prog_init(void); const char *prog_set_name(const char *name); Options *prog_set_options(Options *options); const char *prog_set_syntax(const char *syntax); const char *prog_set_desc(const char *desc); const char *prog_set_version(const char *version); const char *prog_set_date(const char *date); const char *prog_set_author(const char *author); const char *prog_set_contact(const char *contact); const char *prog_set_vendor(const char *vendor); const char *prog_set_url(const char *url); const char *prog_set_legal(const char *legal); Msg *prog_set_out(Msg *out); Msg *prog_set_err(Msg *err); Msg *prog_set_dbg(Msg *dbg); Msg *prog_set_alert(Msg *alert); ssize_t prog_set_debug_level(size_t debug_level); ssize_t prog_set_verbosity_level(size_t verbosity_level); int prog_set_locker(Locker *locker); const char *prog_name(void); const Options *prog_options(void); const char *prog_syntax(void); const char *prog_desc(void); const char *prog_version(void); const char *prog_date(void); const char *prog_author(void); const char *prog_contact(void); const char *prog_vendor(void); const char *prog_url(void); const char *prog_legal(void); Msg *prog_out(void); Msg *prog_err(void); Msg *prog_dbg(void); Msg *prog_alert(void); size_t prog_debug_level(void); size_t prog_verbosity_level(void); int prog_out_fd(int fd); int prog_out_stdout(void); int prog_out_file(const char *path); int prog_out_syslog(const char *ident, int option, int facility, int priority); int prog_out_none(void); int prog_err_fd(int fd); int prog_err_stderr(void); int prog_err_file(const char *path); int prog_err_syslog(const char *ident, int option, int facility, int priority); int prog_err_none(void); int prog_dbg_fd(int fd); int prog_dbg_stdout(void); int prog_dbg_stderr(void); int prog_dbg_file(const char *path); int prog_dbg_syslog(const char *id, int option, int facility, int priority); int prog_dbg_none(void); int prog_alert_fd(int fd); int prog_alert_stdout(void); int prog_alert_stderr(void); int prog_alert_file(const char *path); int prog_alert_syslog(const char *id, int option, int facility, int priority); int prog_alert_none(void); int prog_opt_process(int ac, char **av); void prog_usage_msg(const char *fmt, ...); void prog_help_msg(void); void prog_version_msg(void); const char *prog_basename(const char *path); extern Options prog_options_table[1]; int opt_process(int argc, char **argv, Options *options, char *msgbuf, size_t bufsize); char *opt_usage(char *buf, size_t size, Options *options);
This module provides administrative services for arbitrary programs. The services include program identification; flexible, complete command line option processing; help, usage and version messages; flexible debug, verbose, error and normal messaging (simple call syntax with arbitrary message destinations including multiplexing).
This module exposes an alternate interface to GNU getopt_long(3). It defines a way to specify command line option syntax, semantics and
descriptions in multiple, discrete chunks. The getopt functions require that the client specify the syntax and partial semantics
for all options in the same place (if it is to be done statically). This
can be annoying when library modules require their own command line
options. This module allows various parts of a program to (statically)
specify their own command line options independently and link them together
via parent
pointers.
Option syntax is specified in much the same way as for GNU
getopt_long(3). Option semantics are specified by an action (OPT_NOTHING
, OPT_VARIABLE
or OPT_FUNCTION
), an argument type (OPT_NONE
, OPT_INTEGER
or OPT_STRING
) and an object (int *
,
char **
, func()
, func(int)
or func(char *)
).
The opt_process() and opt_usage() functions are used by the prog functions and needn't be used directly. Instead, use prog_opt_process(3) to execute options and prog_usage_msg(3) and prog_help_msg() to construct usage and help message directly from the supplied option data. They are exposed in case you don't want to use any other part of this module.
void prog_init(void)
Initialises the message, error, debug and alert destinations to stdout
,
stderr
, stderr
and stderr
, respectively. These are all null
by default so this function must be called before any messages are emitted.
const char *prog_set_name(const char *name)
Sets the program's name to name
. This is used when composing usage, help, version and error messages. On
success, returns name
. On error, returns
null
with errno
set appropriately.
Options *prog_set_options(Options *options)
Sets the program's options to options
. This is used when processing the command line options with prog_opt_process(). On success, returns
options
. On error, returns null
with errno
set appropriately.
const char *prog_set_syntax(const char *syntax)
Sets the program's syntax description to syntax
. This is used when composing usage and help messages. It must contain a
one line description of the command line arguments, excluding any options.
On success, returns
syntax
. On error, returns null
with errno
set appropriately.
const char *prog_set_desc(const char *desc)
Sets the program's description to desc
. This is used when composing help messages. On success, returns desc
. On error, returns null
with
errno
set appropriately.
const char *prog_set_version(const char *version)
Sets the program's version to version
. This is used when composing help and version messages. On success,
returns version
. On error, returns
null
with errno
set appropriately.
const char *prog_set_date(const char *date)
Sets the program's release date to date
. This is used when composing help messages. On success, returns date
. On error, returns null
with
errno
set appropriately.
const char *prog_set_author(const char *author)
Sets the program's author to author
. This is used when composing help messages. It must contain the (free
format) name of the author. Returns
author
. On error, returns null
with errno
set appropriately.
const char *prog_set_contact(const char *contact)
Sets the program's contact address to contact
. This is used when composing help messages. It must contain the email
address to which bug reports should be sent. On success, returns contact
. On error, returns
null
with errno
set appropriately.
const char *prog_set_vendor(const char *vendor)
Sets the program's vendor to vendor
. This is used when composing help messages. It must contain the (free
format) name of the vendor. Returns
vendor
. On error, returns null
with errno
set appropriately.
const char *prog_set_url(const char *url)
Sets the program's URL to url
. This is used when composing help messages. It must contain the URL where
the program can be downloaded. On success, returns url
. On error, returns null
with errno
set appropriately.
const char *prog_set_legal(const char *legal)
Sets the program's legal notice to legal
. This is used when composing help messages. It is assumed that the legal
notice may contain multiple lines and so must contain its own newline
characters. On success, returns
legal
. On error, returns null
with errno
set appropriately.
Msg *prog_set_out(Msg *out)
Sets the program's message destination to out
. This is used by msg()
and vmsg() which are, in turn, used to emit usage, version and help messages. The
program message destination is set to standard output by
prog_init() but it can be anything. However, it is probably best to leave it as
standard output until after command line option processing is complete. See msg() for details. On success, returns out
. On error, returns null
with errno
set appropriately.
Msg *prog_set_err(Msg *err)
Sets the program's error message destination to err
. This is used by
error(3), errorsys(3), fatal(3), fatalsys(3), dump(3) and
dumpsys(3). The program error message destination is set to standard error by prog_init(3) but it can be anything. See msg(3) for details. On success, returns err
. On error, returns null
with errno
set appropriately.
Msg *prog_set_dbg(Msg *dbg)
Sets the program's debug message destination to dbg
. This is set to standard error by prog_init(3) but it can be set to anything. See
msg(3) for details. On success, returns dbg
. On error, returns null
with errno
set appropriately.
Msg *prog_set_alert(Msg *alert)
Sets the program's alert message destination to alert
. This is set to standard error by prog_init() but it can be set to anything. See
msg(3) for details. On success, returns alert
. On error, returns
null
with errno
set appropriately.
ssize_t prog_set_debug_level(size_t debug_level)
Sets the program's debug level to debug_level
. This is used when determining whether or not to emit a debug message. The
debug level comprises two parts, the section and the level. The level occupies the low byte of debug_level
. The section occupies the next three bytes. This enables debugging to be partitioned
into sections, allowing users to turn on debugging at any level (from 0 up
to 255) for particular sections of a program (at most 24). Debug messages
with a section value whose bits overlap those of the program's current
debug section and with a level that is less than or equal to the program's
current debug level are emitted. As a convenience, if the program debug
section is zero, debug messages with a sufficuently small level are emitted
regardless of the message section. On success, returns the previous debug
level. On error, returns -1
with errno
set appropriately.
Example:
#define LEXER_SECTION (1 << 8) #define PARSER_SECTION (2 << 8) #define INTERP_SECTION (4 << 8)
prog_set_debug_level(LEXER_SECTION | PARSER_SECTION | 1); debug((LEXER_SECTION | 1, "lexer debug")) // yes debug((LEXER_SECTION | 4, "lexer debug")) // no (level too high) debug((PARSER_SECTION | 1, "parser debug")) // yes debug((INTERP_SECTION | 1, "interp debug")) // no (wrong section) debug((1, "global debug")) // no (no section to match)
prog_set_debug_level(1); debug((LEXER_SECTION | 1, "lexer debug")) // yes debug((LEXER_SECTION | 4, "lexer debug")) // no (level too high) debug((PARSER_SECTION | 1, "parser debug")) // yes debug((INTERP_SECTION | 1, "interp debug")) // yes debug((1, "global debug")) // yes debug((4, "global debug")) // no (level too high)
ssize_t prog_set_verbosity_level(size_t verbosity_level)
Sets the program's verbosity level to verbosity_level
. This is used to determine whether or not to emit verbose messages.
Verbose messages with a level that is less than or equal to the program's
current verbosity level are emitted. On success, returns the previous
verbosity level. On error, returns -1
with errno
set appropriately.
int prog_set_locker(Locker *locker)
Sets the locker (multiple thread synchronisation strategy) for this module.
This is only needed in multi-threaded programs. See locker(3)
for details. On success, returns 0
. On error, returns -1
with errno
set appropriately.
const char *prog_name(void)
Returns the program's name. On error, returns null
with errno
set appropriately.
const Options *prog_options(void)
Returns the program's options. On error, returns null
with errno
set appropriately.
const char *prog_syntax(void)
Returns the program's syntax description. On error, returns null
with
errno
set appropriately.
const char *prog_desc(void)
Returns the program's description. On error, returns null
with errno
set appropriately.
const char *prog_version(void)
Returns the program's version string. On error, returns null
with
errno
set appropriately.
const char *prog_date(void)
Returns the program's release date. On error, returns null
with errno
set appropriately.
const char *prog_author(void)
Returns the program's author. On error, returns null
with errno
set appropriately.
const char *prog_contact(void)
Returns the program's contact address. On error, returns null
with
errno
set appropriately.
const char *prog_vendor(void)
Returns the program's vendor. On error, returns null
with errno
set appropriately.
const char *prog_url(void)
Returns the program's URL. On error, returns null
with errno
set appropriately.
const char *prog_legal(void)
Returns the program's legal notice. On error, returns null
with errno
set appropriately.
Msg *prog_out(void)
Returns the program's message destination. On error, returns null
with
errno
set appropriately.
Msg *prog_err(void)
Returns the program's error message destination. On error, returns null
with errno
set appropriately.
Msg *prog_dbg(void)
Returns the program's debug message destination. On error, returns null
with errno
set appropriately.
Msg *prog_alert(void)
Returns the program's alert message destination. On error, returns null
with errno
set appropriately.
size_t prog_debug_level(void)
Returns the program's debug level. On error, returns 0
with errno
set appropriately.
size_t prog_verbosity_level(void)
Returns the program's verbosity level. On error, returns 0
with
errno
set appropriately.
int prog_out_fd(int fd)
Sets the program's message destination to be the file descriptor specified
by fd
. On success, returns 0
. On error, returns -1
with errno
set appropriately.
int prog_out_stdout(void)
Sets the program's message destination to be standard output. On success,
returns 0
. On error, returns -1
with errno
set appropriately.
int prog_out_file(const char *path)
Sets the program's message destination to be the file specified by path
. On success, returns 0
. On error, returns -1
with errno
set appropriately.
int prog_out_syslog(const char *ident, int option, int facility, int priority)
Sets the program's message destination to be syslog initialised with
ident
, option
, facility
and priority
. On success, returns 0
. On error, returns -1
with errno
set appropriately.
int prog_out_none(void)
Sets the program's message destination to null
. This disables all normal messages. On success, returns 0. On error, sets errno
appropriately.
int prog_err_fd(int fd)
Sets the program's error message destination to be the file descriptor
specified by fd
. On success, returns 0
. On error, returns -1
with
errno
set appropriately.
int prog_err_stderr(void)
Sets the program's error message destination to be standard error. On
success, returns 0
. On error, returns -1
with errno
set appropriately.
int prog_err_file(const char *path)
Sets the program's error message destination to be the file specified by
path
. On success, returns 0
. On error, returns -1
with errno
set appropriately.
int prog_err_syslog(const char *ident, int option, int facility, int priority)
Sets the program's error message destination to be syslog initialised with ident
, option
, facility
and priority
. On success, returns
0
. On error, returns -1
with errno
set appropriately.
int prog_err_none(void)
Sets the program's error message destination to null
. This disables all error messages. On success, returns 0
. On error, returns -1
with set
errno
appropriately.
int prog_dbg_fd(int fd)
Sets the program's debug message destination to be the file descriptor
specified by fd
. On success, returns 0
. On error, returns -1
with
errno
set appropriately.
int prog_dbg_stdout(void)
Sets the program's debug message destination to be standard output. On
success, returns 0
. On error, returns -1
with errno
set appropriately.
int prog_dbg_stderr(void)
Sets the program's debug message destination to be standard error. On
success, returns 0
. On error, returns -1
with errno
set appropriately.
int prog_dbg_file(const char *path)
Sets the program's debug message destination to be the file specified by
path
. On success, returns 0
. On error, returns -1
with errno
set appropriately.
int prog_dbg_syslog(const char *id, int option, int facility, int priority)
Sets the program's debug message destination to be syslog initialised with ident
, option
, facility
and priority
. On success, returns
0
. On error, returns -1
with errno
set appropriately.
int prog_dbg_none(void)
Sets the program's debug message destination to null
. This disables all debug messages. On success, returns 0
. On error, returns -1
with
errno
set appropriately.
int prog_alert_fd(int fd)
Sets the program's alert message destination to be the file descriptor
specified by fd
. On success, returns 0
. On error, returns -1
with
errno
set appropriately.
int prog_alert_stdout(void)
Sets the program's alert message destination to be standard output. On
success, returns 0
. On error, returns -1
with errno
set appropriately.
int prog_alert_stderr(void)
Sets the program's alert message destination to be standard error. On
success, returns 0
. On error, returns -1
with errno
set appropriately.
int prog_alert_file(const char *path)
Sets the program's alert message destination to be the file specified by
path
. On success, returns 0
. On error, returns -1
with errno
set appropriately.
int prog_alert_syslog(const char *id, int option, int facility, int priority)
Sets the program's alert message destination to be syslog initialised with ident
, option
, facility
and priority
. On success, returns
0
. On error, returns -1
with errno
set appropriately.
int prog_alert_none(void)
Sets the program's alert message destination to null
. This disables all alert messages. On success, returns 0
. On error, returns -1
with
errno
set appropriately.
int prog_opt_process(int ac, char **av)
Parses and processes the command line options in av
. If there is an error, a usage message is emitted and the program
terminates. This function is just an interface to GNU getopt_long(3) that provides easier, more flexible, and more complete option handling. As
well as supplying the syntax for options, this function requires their
semantics and descriptions. The descriptions allow usage and help messages
to be automatically composed by
prog_usage_msg(3) and prog_help_msg(3). The semantics (which may be either a variable assignment or a function
invocation) allow complete command line option processing to be performed
with a single call to this function. On success, returns optind
. On error (i.e. invalid option or option argument), calls prog_usage_msg() which terminates the program with a return code of EXIT_FAILURE
. See the EXAMPLE section for details on specifying option data. See opt_process() for details on the processing of each option. On error, returns -1
with errno
set appropriately.
void prog_usage_msg(const char *fmt, ...)
Emits a program usage error message then terminates the program with a
return code of EXIT_FAILURE
. The usage message consists of the program's name, syntax, options and
descriptions (if they have been supplied) and the given message. fmt
is a printf(3)-like format string. Any remaining arguments are processed as in printf(3).
Warning: Do not under any circumstances ever pass a non-literal string as the fmt argument unless you know exactly how many conversions will take place. Being careless with this is a very good way to build potential security holes into your programs. The same is true for all functions that take a printf()-like format string as an argument.
prog_usage_msg(buf); // EVIL prog_usage_msg("%s", buf); // GOOD
void prog_help_msg(void)
Emits a program help message then terminates the program with a return code
of EXIT_SUCCESS
. This message consists of the program's usage message, description, name,
version, release date, author, vendor, URL, legal notice and contact
address (if they have been supplied).
void prog_version_msg(void)
Emits a program version message then terminates the program with a return
code of EXIT_SUCCESS
. This message consists of the program's name and version (if they have
been supplied).
const char *prog_basename(const char *path)
Returns the filename part of path
. On error, returns null
with
errno
set appropriately.
extern Options prog_options_table[1]
Contains the syntax, semantics and descriptions of some options that are available to all programs that use libslack. These options are:
-h
, --help
Print a help message then exit
-V
, --version
Print a version message then exit
-v
[level], --verbose
[=level]Set the verbosity level (Defaults to 1 if level is not supplied)
-d
[level], --debug
[=level]Set the debug level (Defaults to 1 if level is not supplied)
If your program supports no other options than these, prog_options_table
can be passed directly to prog_set_options(3). Otherwise,
prog_options_table
should be assigned to the parent
field of the
Options
structure that will be passed to prog_set_options(3).
int opt_process(int argc, char **argv, Options *options, char *msgbuf, size_t bufsize)
Parses argv
for options specified in options
. Uses GNU
getopt_long(3). As each option is encountered, its corresponding action is performed. On
success, returns optind
. On error, returns -1
with
errno
set appropriately.
The following table shows the actions that are applied to an option's
object
based on its has_arg
, arg_type
and arg_action
attributes and whether or not an argument is present.
has_arg arg_type arg_action optarg action ~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~ ~~~~~~~~~~~~ ~~~~~~ ~~~~~~ required_argument OPT_INTEGER OPT_VARIABLE yes *object = strtol(argument) required_argument OPT_STRING OPT_VARIABLE yes *object = argument required_argument OPT_INTEGER OPT_FUNCTION yes object(strtol(argument)) required_argument OPT_STRING OPT_FUNCTION yes object(argument)
optional_argument OPT_INTEGER OPT_VARIABLE yes *object = strtol(argument) optional_argument OPT_STRING OPT_VARIABLE yes *object = argument optional_argument OPT_INTEGER OPT_FUNCTION yes object(&strtol(argument)) optional_argument OPT_STRING OPT_FUNCTION yes object(argument)
optional_argument OPT_INTEGER OPT_VARIABLE no ++*object optional_argument OPT_STRING OPT_VARIABLE no nothing optional_argument OPT_INTEGER OPT_FUNCTION no object(NULL) optional_argument OPT_STRING OPT_FUNCTION no object(NULL)
no_argument OPT_NONE OPT_VARIABLE no ++*object no_argument OPT_NONE OPT_FUNCTION no object()
Note that integer option arguments may be expressed in octal, decimal or hexadecimal. There may be leading whitespace but no trailing text of any kind. Overflow and underflow are also treated as errors.
char *opt_usage(char *buf, size_t size, Options *options)
Writes a usage message into buf
that displays the names, syntax and descriptions of all options in options
. options
is traversed depth first so the chunk with the null
parent
appears first. Each chunk of options is preceeded by a blank line. No more
than size
bytes are written, including the terminating nul
character. The string returned will look like:
-a, --aaa -- no-arg/var option -b, --bbb -- no-arg/func option -c, --ccc=arg -- int-arg/var option -d, --ddd=arg -- int-arg/func option -e, --eee=arg -- str-arg/var option -f, --fff=arg -- str-arg/func option -g, --ggg[=arg] -- opt-int-arg/var option -h, --hhh[=arg] -- opt-str-arg/func option with one of those really, really, really, long descriptions that goes on and on and even contains a really long url: http://www.zip.com.au/~joe/fairly/long/url/index.html would you believe? Here it is again! http://www.zip.com.au/~joe/fairly/long/url/index.html#just_kidding
On error, errno
is set either by an underlying function, or as follows:
Arguments are null
or invalid.
An integer option argument string failed to be parsed completely.
An integer option argument string was out of integer range. In this case,
INT_MAX
or INT_MIN
is used.
MT-Disciplined - prog functions
By default, this module is not thread safe because most programs are single threaded and synchronisation doesn't come for free. For multi threaded programs, use prog_set_locker() to synchronise access to this module's data before creating the threads that will access it.
Unsafe - opt functions
opt_process() and opt_usage() must only be used in the main thread. They should not be needed anywhere else. Normally, they would not be called directly at all.
The following program:
#include <slack/std.h> #include <slack/prog.h>
char *name = NULL; int minimum = 0; int reverse = 0;
void setup_syslog(char *facility) { ... } void parse_config(char *path) { ... }
Option example_optab[] = { { "name", 'n', "name", "Provide a name", required_argument, OPT_STRING, OPT_VARIABLE, &name }, { "minimum", 'm', "minval", "Ignore everything below minimum", required_argument, OPT_INTEGER, OPT_VARIABLE, &minimum }, { "syslog", 's', "facility.priority", "Send client's output to syslog (defaults to local0.debug)", optional_argument, OPT_STRING, OPT_FUNCTION, (void *)setup_syslog }, { "reverse", 'r', NULL, "Reverse direction", no_argument, OPT_NONE, OPT_VARIABLE, &reverse }, { "config", 'c', "path", "Specify the configuration file", required_argument, OPT_STRING, OPT_FUNCTION, (void *)parse_config }, { NULL, '\0', NULL, NULL, 0, 0, 0, NULL } };
Options options[1] = {{ prog_options_table, example_optab }};
int main(int ac, char **av) { int a; prog_init(); prog_set_name("example"); prog_set_syntax("[options] arg..."); prog_set_options(options); prog_set_version("1.0"); prog_set_date("20011109"); prog_set_author("raf <raf@raf.org>"); prog_set_contact(prog_author()); prog_set_url("http://libslack.org/"); prog_set_legal("This software is released under the terms of the GPL.\n"); prog_set_desc("This program is an example of the prog module.\n");
for (a = prog_opt_process(ac, av); a < ac; ++a) msg("av[%d] = \"%s\"\n", a, av[a]);
return EXIT_SUCCESS; }
will behave like:
$ example --version # to stdout example-1.0
$ example --help # to stdout usage: example [options] arg... options:
-h, --help - Print a help message then exit -V, --version - Print a version message then exit -v, --verbose[=level] - Set the verbosity level -d, --debug[=level] - Set the debug level
-n, --name=name - Provide a name -m, --minimum=minval - Ignore everything below minimum -s, --syslog[=facility.priority] - Send client's output to syslog (defaults to local0.debug) -r, --reverse - Reverse direction -c, --config=path - Specify the configuration file
This program is an example of the prog module.
Name: example Version: 1.0 Date: 20011109 Author: raf <raf@raf.org> URL: http://libslack.org/
This software is released under the terms of the GPL.
Report bugs to raf <raf@raf.org>
$ example -x # to stderr ./example: invalid option -- x usage: example [options] arg... options:
-h, --help - Print a help message then exit -V, --version - Print a version message then exit -v, --verbose[=level] - Set the verbosity level -d, --debug[=level] - Set the debug level
-n, --name=name - Provide a name -m, --minimum=minval - Ignore everything below minimum -s, --syslog[=facility.priority] - Send client's output to syslog (defaults to local0.debug) -r, --reverse - Reverse direction -c, --config=path - Specify the configuration file
$ example a b c # to stdout av[1] = "a" av[2] = "b" av[3] = "c"
libslack(3), getopt_long(3), err(3), msg(3), opt(3), prop(3), sig(3), locker(3)
20011109 raf <raf@raf.org>