DragonFly On-Line Manual Pages

verbose(l)                      BEGEMOT Library                     verbose(l)

NAME
       verb - print verbose messages

SYNOPSIS

       # 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);

DESCRIPTION
       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.

ENVIRONMENT
       BEGEMOT_ERR
              Overrides the prefix format mode.

SEE ALSO
       panic(l),

AUTHOR
       Harti Brandt

BEGEMOT                           17 Mar 1998                       verbose(l)