#ifndef _VERBOSE_H_a2cde8fe_
#define _VERBOSE_H_a2cde8fe_

/* This file is in the public domain. */

#include <stdio.h>

#include "verbose-bits.h"

/*
 * Interface to the verbosity output stuff.
 *
 * verbose holds the VERBOSE_* bits corresponding to the enabled
 *  verbosity types.  (Where they go is kept in variables private to
 *  verbose.c.)  VERB(t) tests whether type t (which should not include
 *  the VERBOSE_ prefix) is enabled; verb(t,...) is a printf-like call
 *  which generates output of verbosity type t (which, again, should
 *  not include the VERBOSE_ prefix).  pverb() is available for use
 *  when verb() is not suitable, such as when output belongs to more
 *  than one verbosity class, or when the type is not known at compile
 *  time.
 *
 * verbosity_default turns on the default verbosity values; it's used
 *  by the -v command-line flag.
 *
 * verbosity_set enables verbosity according to its argument; this is
 *  passed -V's argument directly - it is where =DEST is implemented
 *  and even is where the ? convention is implemented for -V.
 *
 * verbose_startup must be called, once, after all -v and -V options
 *  have been processed.  It handles opening files and suchlike.
 *
 * verb_fopen is a bit like verb and pverb in that it generates verbose
 *  output; the difference is that it returns a FILE *, so that
 *  verbosity output can be generated with other functions which output
 *  to FILE *s.  (The argument is a verbosity bitmask saying which
 *  kind(s) of verbosity is/are to be generated.)  See the note below
 *  about output interleaving.
 *
 * verb_data_block generates verbose output for binary data blobs; the
 *  output is remininscent of hexdump -C output.  It expects to
 *  generate complete lines.  The first arg is the verbosity type(s);
 *  the other two args describe the data block.
 *
 * verb_data_blocks is just like verb_data_block except that the data
 *  printed, instead of coming from a contiguous area of memory, is
 *  drawn from multiple such areas (a la writev vs write).  The arglist
 *  is
 *	(verbosity, nblocks, blk0ptr, blk0len, blk1ptr, blk1len, ...)
 *  where blkXptr is a const void * and blkXlen is an int, and there
 *  are nblocks ptr/len pairs in all.  (Note that the blkXptr values
 *  will usually require casts.)  If a blkNlen is -1, that blkNptr is
 *  ignored, zero bytes of data are generated, but a * marker appears
 *  in the output before the next byte (or at the end of the output, if
 *  no more bytes follow).  Multiple such markers may appear, but if
 *  multiple such markers occur with no bytes between them, they will
 *  be collapsed into a single marker in the output.  Markers must be
 *  counted in nblocks.
 *
 * verb_vis generates verbose output for a data block which is mostly
 *  text but may include some nonprinting characters; it generates
 *  output using Cish escaping conventions, such as \r for 0x0d octets
 *  or \203 for 0x83 octets, with ISO-8859 printables being represented
 *  as themselves.
 *
 * Note that intermixing output from functions that take verbosity
 *  bitmasks, such as verb/pverb and verb_vis, with functions producing
 *  output to a FILE * returned by verb_fopen, may interleave output in
 *  surprising ways.  verb_fopen output is buffered and gets written to
 *  its destination(s) at some time not earlier than the stdio call
 *  which writes to the FILE * and not later than the time the FILE *
 *  is fclose()d, and output to a given FILE * is correctly ordered
 *  with respect to other output to the same FILE *, but there are no
 *  other ordering guarantees between output to a FILE * and output
 *  generated other ways, not even if fflush() is used on the FILE *.
 *  (This lack of guarantees is also in effect for output to two
 *  different FILE *s, unless the constraints given for FILE * output
 *  compel an ordering.)
 *
 * Call ordering constraints: before verbose_startup is called, only
 *  verbosity_default and verbosity_set may be called; after, neither
 *  of those may be called, but the rest may be.  Also, verbose_startup
 *  may be called at most once.  Violating any of these constraints
 *  produces undefined behaviour.
 */

extern unsigned int verbose;
#define VERB(n) (verbose & VERBOSE_##n)
#define verb(n,fmt,rest...) pverb(VERBOSE_##n,fmt , ##rest)
extern void pverb(unsigned int, const char *, ...)
	__attribute__((__format__(__printf__,2,3)));
extern void verbosity_default(void);
extern void verbosity_set(const char *);
extern void verbose_startup(void);
extern FILE *verb_fopen(unsigned int);
extern void verb_data_block(unsigned int, const void *, int);
extern void verb_data_blocks(unsigned int, int, ...);
extern void verb_vis(unsigned int, const void *, int);

#endif