libbu (Utility Functions)

The two letters "BU" stand for "BRL-CAD" and "Utility". This library provides several layers of low-level utility routines, providing features that make cross-platform coding easier. More...

Collaboration diagram for libbu (Utility Functions):

Modules
	Definitions
	These are definitions specific to libbu, used throughout the library.
	Applications
	Routines for application setup and supplying information to user programs.
	Subprocess Management
	Routines for launching and managing applications as subprocesses.
	Data Containers
	Containers for holding various kinds of information.
	Dynamic Libraries
	Wrap platform-specific functionality for managing dynamic library run-time loading, symbol access and unloading.
	Memory Management
	Wrappers for memory allocation and release, and mapping.
	Input/Output
	Support for file and string handling, as well as debugging, path manipulation, logging and vector fonts.
	Data Management
	Routines for command processing, network byte order conversion, sorting algorithms, time, endian support, units, etc.
	Data Generation
	Parallel Processing
	Cross platform API for parallel processing, handling issues like threads and semaphores.
	Environment Management
	Cross platform API for interacting with the operating system environment.
	System Header Management
	Convenience headers that manage the correct inclusion of various types of system functionality.
	Version
	Version reporting for LIBBU.
	EXPERIMENTAL
	In-progress API, not ready for general use.

Files
file	bu.h
	Main header file for the BRL-CAD Utility Library, LIBBU.

Detailed Description

The two letters "BU" stand for "BRL-CAD" and "Utility". This library provides several layers of low-level utility routines, providing features that make cross-platform coding easier.

Parallel processing support: threads, semaphores, parallel-malloc. Consolidated logging support: bu_log(), bu_exit(), and bu_bomb().

The intention is that these routines are general extensions to the data types offered by the C language itself, and to the basic C runtime support provided by the system LIBC. All routines in LIBBU are designed to be "parallel-safe" (sometimes called "mp-safe" or "thread-safe" if parallelism is via threading) to greatly ease code development for multiprocessor systems.

The LIBBU API is defined in bu.h or appropriate included files from the ./bu subdirectory; none of the routines in this library will depend on data types defined in other BRL-CAD header files, such as vmath.h. Look for those routines in LIBBN.

All truly fatal errors detected by the library use bu_bomb() to exit with a status of 12. The LIBBU variants of system calls (e.g., bu_malloc()) do not return to the caller (unless there's a bomb hook defined) unless they succeed, thus sparing the programmer from constantly having to check for NULL return codes.

The two headers bio.h and bnetwork.h are not LIBBU API but rather are intended as convenience headers used to package up the somewhat finicky logic needed to correctly include operating system file I/O and networking headers.