LIBBU(3)

NAME
libbu - The BRL-CAD Utility Library

SYNOPSIS
#include "common.h"
#include "<stdio.h>"
#include "machine.h"
#include "bu.h"

WARNING - WARNING - WARNING - WARNING - WARNING
This file seems to be out of date with the sources.
Consult the headers for up-to-date information.
Use the below interface documentation at your own discretion.
WARNING - WARNING - WARNING - WARNING - WARNING

DESCRIPTION
libbu contains all of the basic "computer-science" integer utility subroutines for The BRL-CAD Package; the two letters "BU" stand for "BRL-CAD" and "Utility". Numerical (floating-point math) routines are found in the separate library libbn. All subroutines in libbu are designed to be "parallel-safe" (sometimes called "mp-safe"), to greatly ease code development for multi-processor systems.

The header file bu.h contains several "packages" which are implemented entirely by macros and have no corresponding source code. This includes the portable interface for declaring function prototypes BU_EXTERN and BU_ARGS, the portable interface for declaring FORTRAN-callable C routines BU_FORTRAN, the object constructor macros BU_GETSTRUCT and BU_GETUNION, the magic-number checking macros BU_CKMAG, the entire doubly-linked list package (formerly found in h/rtlist.h) BU_LIST_xxx().

In addition to the capabilities implemented as macros, there are additional "packages" which have both macro and subroutine interfaces:

The arbitrary-length bit-vector routines bu_bitv_xxx().

The standardized parallel-safe error logging and abort routines bu_log() and bu_bomb().

A portable re-entrant implementation of the getopt(3) library routine bu_getopt(3).

A set of data histogramming routines bu_hist_xxx().

A set of portable vendor-independent routines for parallel processing that include bu_avail_cpus() to determine how many CPUs are available on the current system, bu_parallel() to initiate a specified number of parallel threads of execution, and bu_semaphore_init(), bu_semaphore_acquire(), and bu_semaphore_release() for portable handling of semaphores to protect critical sections of code.

The bu_malloc() family of parallel-safe routines provide an interface to the system memory allocator which include standardized error checking, optional memory-use logging, and optional run-time pointer and memory corruption testing.

The bu_open_mapped_file() routines provide a standardized interface for acquiring the entire contents of an existing file mapped into the current address space, using the virtual-memory capabilities of the operating-system (such as mmap(2)) where available, or if all else fails, allocating sufficient dynamic memory and reading the entire file.

The bu_structparse data structure and associated routines provide a convenient way of describing a C data structure, and reading and writing it in both human-readable ASCII and efficient binary forms.

The bu_ptbl "pointer table" data structure provides a convenient mechanism for managing a collection of pointers to objects, where the size of the array is not known in advance and may change with time. It is very convenient to be able to write code that can say "remember this object", and then later on iterate through the collection of remembered objects. When combined with the concept of placing "magic numbers" in the first long of each data structure, the pointers to the objects become automatically typed.

The bu_vls structure provides support for variable length strings, freeing the programmer from concerns about having char arrays large enough to hold strings. A complete set of string routines are provided, including bu_vls_gets(), bu_vls_strdup(), bu_vls_strcat(), bu_vls_from_argv(), bu_vls_fwrite(), and many others.

The red-black package of balanced binary tree operations that provides all the basic dynamic set operations (e.g., insertion, deletion, search, minimum, maximum, predecessor, and successor) and order-statistic operations (i.e., select and rank) with optimal -- that is, O(log n) -- performance while sorting on multiple keys.

Finally, a set of routines exist for taking text descriptions of distance units and converting them to millimeters and back, including bu_units_conversion().

WARNING
libbu is designed to run in parallel on multiprocessor machines. On some such machines system calls must be semaphore protected. For this reason, libbu provides:

bu_log()
bu_malloc() bu_free() bu_calloc() bu_realloc()
bu_strdup()

The function bu_log() is essentially a semaphore-protected version of printf() except that it uses the standard error (stderr) instead of the standard output (stdout).

Dynamic memory handling in applications using libbu should use the functions provided by libbu instead of the usual system runtime library routines. The libbu versions do not return to the caller unless they succeed, thus sparing the programmer from constantly having to check for NULL return code. If a libbu routine fails with an unrecoverable error, it will call bu_bomb with their last argument (str) as the parameter. The string parameter usually indicates the purpose of the memory being allocated.

The function bu_strdup() calls bu_malloc() instead of malloc() to acquire memory. Thus it should be used in place of strdup() in programs linking with libbu.

EXIT CODE
All truly fatal errors detected by the library use bu_bomb to exit with a status of 12.

RECOMMENDATION
You should study the macros and data structures in bu.h.

To convert programs written for BRL-CAD Release 4.4 and earlier, where these routines were all part of librt, a compatibility header file is provided:

#include "compat4.h"

In addition, you can painlessly upgrade your source code to using the new libraries by using the provided editor script:

ed yourprog.c < ../include/sed4

This will change all the subroutine, macro, and data structure names from their old rt_ prefix names to their new bu_ prefix names.

SEE ALSO
brlcad(1B), librt(1B), libbn(1B), redblack(3B).

DIAGNOSTICS
``bu_malloc: malloc failure'', if libbu is unable to allocate memory with malloc.

AUTHORS
Michael John Muuss
Lee A. Butler
Glenn Durfee
Paul J. Tanenbaum

SOURCE
 The U. S. Army Research Laboratory
 Aberdeen Proving Ground, Maryland 21005-5068 USA

COPYRIGHT
Copyright (c) 2004-2007 United States Government as represented by U.S. Army Research Laboratory. This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this file; see the file named COPYING for more information.

BUG REPORTS
Reports of bugs or problems should be submitted via electronic mail to <devs@brlcad.org>, or via the provided "cadbug.sh" script.