verb - print verbose messages
# include <begemot.h>
void verb(u_int opt, u_int level, const char *fmt, ...);
void verbc(u_int opt, u_int level, const char *fmt, ...);
void verbn(u_int opt, u_int level, const char *fmt, ...);
void vverb(u_int opt, u_int level, const char *fmt, va_list ap);
void vverbc(u_int opt, u_int level, const char *fmt, va_list ap);
void vverbn(u_int opt, u_int level, const char *fmt, va_list ap);
u_int verb_level(u_int opt);
void verb_option(char * optarg);
void verb_update(FILE * fp);
void verb_opts(verb_option_t * opts);
The
verb family of functions may be used to print debug and other
information from programs in a uniform way. They can be used in simple
programs, as well as in large programs.
The functions employ the concept of so-called verbose facilities and levels. A
facility (or option) usually represents one sub-system or sub-function of a
given program, whereas the verbose level controls the amount of information to
be printed for each facility. In simple programs one facility (the default
one) may be sufficient, whereas in complex programs it is often desirable to
enable/disable debugging printout in different parts of the program
independent of each other.
Facilities are defined by providing a definition of an array of
verb_option_t's. This array consists of structures, the first field of
which is an ASCII string for the facility name. So the definition
verb_option_t verbopts[] = {
{ "lexer" },
{ "parser" },
{ "gen" },
{ NULL }
};
could be used to define the facilities for a compiler. The array must be
terminated with a NULL entry. If your program consists of more than one source
file, you may also want to provide symbolic definitions of the facilities in a
header file (for only one source file, you don't need an extra header):
enum {
V_LEXER,
V_PARSER,
V_GEN
};
The option array is made known to the library by calling
verb_opts. If
verb_opts is not called, the default definition from the library,
containing the facility "verbose" is used, which is sufficient for
simple programs. A symbolic definition of
V_DFTL is provided in this
case for the facility.
The verbose level is usually set through command line arguments. You should
aquire the habit of using the same option for verbosity in all your programs.
A convention could be to use the 'v' or 'd'. The argument of this option
should be passed to
verb_option. The argument may take one of two
forms: a facility name or facility=value, where value is an integer. In the
first case, the level of the verbose facility is incremented by one, in the
second case it is set to the given value.
The facility "all" is always defined (and you can't override this
definition) to mean: change all facilities. So the string
all=2 will
set all verbose levels to 2.
For simple programs with only one verbose facility, you can use your option
without an argument and call
verb_option("all") instead.
Verbose levels can also be changed from a file by calling
verb_update
with an open file pointer. This is useful for long-running complex programs,
where you may want to change the verbose level dynamically. In this case you
could catch a signal, open a file with a fixed name in the signal handler and
pass the file to verb_update.
To actually print something the functions
verb,
verbn or
verbc or their va_list equivalents are used. These functions differ in
the appearance of the output:
verb prints the standard prefix (see
panic(l)), the message and appends a newline.
verbn does not
append the newline and
verbc only prints the message without prefix and
newline. The output is sent to the standard error file descriptor.
To obtain the current verbose level for a given facility you may call
verb_level.
- BEGEMOT_ERR
- Overrides the prefix format mode.
panic(l),
Harti Brandt
Visit the GSP FreeBSD Man Page Interface.