Logging

BRL-CAD support library, error logging routines. More...

Collaboration diagram for Logging:

Files
file	log.h
file	log.h

Data Structures
struct	bu_hook
struct	bu_hook_list
struct	bu_lex_t_int
struct	bu_lex_t_dbl
struct	bu_lex_t_key
struct	bu_lex_t_id
union	bu_lex_token
struct	bu_lex_key

Macros
#define	BU_HOOK_LIST_INIT_ZERO   { 0, 0, NULL}
#define	BU_HOOK_LIST_IS_INITIALIZED(_p)   ((_p)->capacity != 0)
#define	BU_LEX_ANY   0 /* pseudo type */
#define	BU_LEX_INT   1
#define	BU_LEX_DOUBLE   2
#define	BU_LEX_SYMBOL   3
#define	BU_LEX_KEYWORD   4
#define	BU_LEX_IDENT   5
#define	BU_LEX_NUMBER   6 /* Pseudo type */
#define	BU_LEX_NEED_MORE   0

Typedefs
typedef int(*	bu_hook_t) (void *, void *)
typedef struct bu_hook	bu_hook_list_t

Functions
void	bu_hook_list_init (struct bu_hook_list *hlp)
void	bu_hook_add (struct bu_hook_list *hlp, bu_hook_t func, void *clientdata)
void	bu_hook_delete (struct bu_hook_list *hlp, bu_hook_t func, void *clientdata)
void	bu_hook_call (struct bu_hook_list *hlp, void *buf)
void	bu_hook_save_all (struct bu_hook_list *source, struct bu_hook_list *destination)
void	bu_hook_delete_all (struct bu_hook_list *hlp)
void	bu_hook_restore_all (struct bu_hook_list *destination, struct bu_hook_list *source)
char *	bu_fgets (char *s, int size, FILE *stream)
	fgets replacement function that also handles CR as an EOL marker More...
void	bu_setlinebuf (FILE *fp)
	A portable way of doing setlinebuf(). More...
void	bu_log_indent_delta (int delta)
	parallel safe version of fprintf for logging More...
void	bu_log_indent_vls (struct bu_vls *v)
void	bu_log_add_hook (bu_hook_t func, void *clientdata)
void	bu_log_delete_hook (bu_hook_t func, void *clientdata)
void	bu_log_hook_save_all (struct bu_hook_list *save_hlp)
void	bu_log_hook_delete_all (void)
void	bu_log_hook_restore_all (struct bu_hook_list *restore_hlp)
void	bu_putchar (int c)
int	bu_log (const char *,...) _BU_ATTR_PRINTF12
int	bu_flog (FILE *, const char *,...) _BU_ATTR_PRINTF23
int	bu_vsscanf (const char *src, const char *fmt, va_list ap)
	libbu implementations of vsscanf/sscanf() with extra format specifiers. More...
int	bu_sscanf (const char *src, const char *fmt,...) _BU_ATTR_SCANF23
int	bu_scan_fastf_t (int *c, const char *src, const char *delim, size_t n,...)
int	bu_lex (union bu_lex_token *token, struct bu_vls *rtstr, struct bu_lex_key *keywords, struct bu_lex_key *symbols)
long int	bu_mread (int fd, void *bufp, long int n)
	multiple-read to fill a buffer More...

Detailed Description

BRL-CAD support library, error logging routines.

These are hook routines for keeping track of callback functions.

Note that the user may provide his own logging routine, by replacing these functions. That is why this is in file of its own. For example, LGT and RTSRV take advantage of this.

Here is an example of how to set up a custom logging callback. While bu_log presently writes to STDERR by default, this behavior should not be relied upon and may be changed to STDOUT in the future without notice.

--- BEGIN EXAMPLE ---
 
int log_output_to_file(void *data, void *str)
{
  FILE *fp = (FILE *)data;
  fprintf(fp, "LOG: %s", str);
  return 0;
}
 
int main(int ac, char *av[])
{
  FILE *fp = fopen("whatever.log", "w+");
  bu_log_add_hook(log_output_to_file, (void *)fp);
  bu_log("Logging to file.\n");
  bu_log_delete_hook(log_output_to_file, (void *)fp);
  bu_log("Logging to stderr.\n");
  fclose(fp);
  return 0;
}
 
--- END EXAMPLE ---

Macro Definition Documentation

BU_HOOK_LIST_INIT_ZERO

#define BU_HOOK_LIST_INIT_ZERO   { 0, 0, NULL}

macro suitable for declaration statement initialization of a bu_hook_list struct. does not allocate memory. not suitable for initialization of a list head node.

Definition at line 61 of file hook.h.

BU_HOOK_LIST_IS_INITIALIZED

#define BU_HOOK_LIST_IS_INITIALIZED

(

_p

)

((_p)->capacity != 0)

returns truthfully whether a non-head node bu_hook_list has been initialized via BU_HOOK_LIST_INIT() or BU_HOOK_LIST_INIT_ZERO.

Definition at line 68 of file hook.h.

BU_LEX_ANY

#define BU_LEX_ANY   0 /* pseudo type */

Definition at line 231 of file log.h.

BU_LEX_INT

#define BU_LEX_INT   1

Definition at line 236 of file log.h.

BU_LEX_DOUBLE

#define BU_LEX_DOUBLE   2

Definition at line 241 of file log.h.

BU_LEX_SYMBOL

#define BU_LEX_SYMBOL   3

Definition at line 246 of file log.h.

BU_LEX_KEYWORD

#define BU_LEX_KEYWORD   4

Definition at line 247 of file log.h.

BU_LEX_IDENT

#define BU_LEX_IDENT   5

Definition at line 252 of file log.h.

BU_LEX_NUMBER

#define BU_LEX_NUMBER   6 /* Pseudo type */

Definition at line 253 of file log.h.

BU_LEX_NEED_MORE

#define BU_LEX_NEED_MORE   0

Definition at line 265 of file log.h.

Typedef Documentation

bu_hook_t

typedef int(* bu_hook_t) (void *, void *)

log indentation hook

Definition at line 41 of file hook.h.

bu_hook_list_t

typedef struct bu_hook bu_hook_list_t

Definition at line 53 of file hook.h.

Function Documentation

bu_hook_list_init()

void bu_hook_list_init

(

struct bu_hook_list *

hlp

)

initialize a hook list to empty

the caller is responsible for ensuring memory is not leaked.

bu_hook_add()

void bu_hook_add	(	struct bu_hook_list *	hlp,
		bu_hook_t	func,
		void *	clientdata
	)

add a hook to the list.

in addition to the callback, the call may optionally provide a data pointer that will get passed as the first argument to the 'func' hook function. the hook function may be NULL, which will result in a no-op (skipped) when bu_hook_call() is called.

bu_hook_delete()

void bu_hook_delete	(	struct bu_hook_list *	hlp,
		bu_hook_t	func,
		void *	clientdata
	)

delete a hook from the list.

this removes a specified callback function registered with a particular data pointer via bu_hook_add() from the hook list.

bu_hook_call()

void bu_hook_call	(	struct bu_hook_list *	hlp,
		void *	buf
	)

call all registered hooks.

this invokes all callbacks added via bu_hook_add() passing any data pointer as the first argument and the provided 'buf' argument as the second argument, either of which may be NULL if desired.

bu_hook_save_all()

void bu_hook_save_all	(	struct bu_hook_list *	source,
		struct bu_hook_list *	destination
	)

copy all hooks from one list to another

bu_hook_delete_all()

void bu_hook_delete_all

(

struct bu_hook_list *

hlp

)

delete all hooks in a list

bu_hook_restore_all()

void bu_hook_restore_all	(	struct bu_hook_list *	destination,
		struct bu_hook_list *	source
	)

replace all hooks in a list with the hooks from another list

all hooks from ther 'destination' hook list will be deleted and all hooks in the 'source' list will be copied into the 'destination' list.

bu_fgets()

char * bu_fgets	(	char *	s,
		int	size,
		FILE *	stream
	)

fgets replacement function that also handles CR as an EOL marker

Reads in at most one less than size characters from stream and stores them into the buffer pointed to by s. Reading stops after an EOF, CR, LF, or a CR/LF combination. If a LF or CR is read, it is stored into the buffer. If a CR/LF is read, just a CR is stored into the buffer. A '\0' is stored after the last character in the buffer. Returns s on success, and NULL on error or when end of file occurs while no characters have been read.

bu_setlinebuf()

void bu_setlinebuf

(

FILE *

fp

)

A portable way of doing setlinebuf().

bu_log_indent_delta()

void bu_log_indent_delta

(

int

delta

)

parallel safe version of fprintf for logging

Change global indentation level by indicated number of characters. Call with a large negative number to cancel all indentation.

bu_log_indent_vls()

void bu_log_indent_vls

(

struct bu_vls *

v

)

For multi-line vls generators, honor logindent level like bu_log() does, and prefix the proper number of spaces. Should be called at the front of each new line.

bu_log_add_hook()

void bu_log_add_hook	(	bu_hook_t	func,
		void *	clientdata
	)

Adds a hook to the list of bu_log hooks. The top (newest) one of these will be called with its associated client data and a string to be processed. Typically, these hook functions will display the output (possibly in an X window) or record it.

NOTE: The hook functions are all non-PARALLEL.

bu_log_delete_hook()

void bu_log_delete_hook	(	bu_hook_t	func,
		void *	clientdata
	)

Removes the hook matching the function and clientdata parameters from the hook list. Note that it is not necessarily the active (top) hook.

bu_log_hook_save_all()

void bu_log_hook_save_all

(

struct bu_hook_list *

save_hlp

)

bu_log_hook_delete_all()

void bu_log_hook_delete_all

(

void

)

bu_log_hook_restore_all()

void bu_log_hook_restore_all

(

struct bu_hook_list *

restore_hlp

)

bu_putchar()

void bu_putchar

(

int

c

)

Log a single character with no flushing.

bu_log()

int bu_log	(	const char *	,
			...
	)

The routine is primarily called to log library events.

The function is essentially a semaphore-protected version of fprintf(stderr) with optional logging hooks and automatic indentation options.

bu_flog()

int bu_flog	(	FILE *	,
		const char *	,
			...
	)

Just like bu_log() except that you can send output to a specified file pointer.

bu_vsscanf()

int bu_vsscanf	(	const char *	src,
		const char *	fmt,
		va_list	ap
	)

libbu implementations of vsscanf/sscanf() with extra format specifiers.

Custom vsscanf which wraps the system sscanf, and is wrapped by bu_sscanf.

bu_vsscanf differs notably from the underlying system sscanf in that:

• A maximum field width is required for unsuppressed s and %[...] conversions. If a s or %[...] conversion is encountered which does not include a maximum field width, the routine bombs in order to avoid an accidental buffer overrun.

• V and %#V have been added as valid conversions. Both expect a pointer to a struct bu_vls as their argument.

  V is comparable to %[^]. It instructs bu_vsscanf to read arbitrary characters from the source and store them in the vls buffer. The default maximum field width is infinity.

  %#V is comparable to s. It instructs bu_vsscanf to skip leading whitespace, and then read characters from the source and store them in the vls buffer until the next whitespace character is encountered. The default maximum field width is infinity.

• 0 is always a valid field width for unsuppressed c, s, and %[...] conversions and causes '\0' to be written to the supplied char* argument.
• a/e/f/g and A/E/F/G are always synonyms for float conversion.
• The C99 conversions hh[diouxX], z[diouxX], and t[diouxX] are always supported.

This routine has an associated test program named test_sscanf, which compares its behavior to the system sscanf.

bu_sscanf()

int bu_sscanf	(	const char *	src,
		const char *	fmt,
			...
	)

Initializes the va_list, then calls bu_vsscanf.

This routine has an associated test program named test_sscanf, which compares its behavior to the system sscanf.

bu_scan_fastf_t()

int bu_scan_fastf_t	(	int *	c,
		const char *	src,
		const char *	delim,
		size_t	n,
			...
	)

Routines for scanning certain kinds of data. Scans a sequence of fastf_t numbers from a string or stdin

Scanning fastf_t numbers with bu_sscanf() is difficult, because doing so requires scanning to some intermediate type like double and then assigning to the fastf_t variable to convert the value to whatever type fastf_t really is. This function makes it possible to scan a series of fastf_t numbers separated by some character(s) easily, by doing the required conversion internally to the functions. As series of delimiter characters will be skipped, empty scan fields are not supported (e.g., "0.0,,0.0,1.0" will scan as 3 fields, not 4 with the 2nd skipped).

Parameters

[out]	c	Returns number of characters scanned by the function
[in]	src	A source string to scan from, or NULL to read from stdin
[in]	delim	Any delimiter character(s) to skip between scan values
[in]	n	Number of fastf_t values to scan from the src input string
[out]	...	Pointers to fastf_t for storing scanned values (optional)

bu_lex()

int bu_lex	(	union bu_lex_token *	token,
		struct bu_vls *	rtstr,
		struct bu_lex_key *	keywords,
		struct bu_lex_key *	symbols
	)

bu_mread()

long int bu_mread	(	int	fd,
		void *	bufp,
		long int	n
	)

multiple-read to fill a buffer

Provide a general means to a read some count of items from a file descriptor reading multiple times until the quantity desired is obtained. This is useful for pipes and network connections that don't necessarily deliver data with the same grouping as it is written with.

If a read error occurs, a negative value will be returns and errno should be set (by read()). "Multiple try" read. Read multiple times until quantity is obtained or an error occurs. This is useful for pipes.