[become] / src / utils.h

/* -*-c-*-
 *
 * $Id: utils.h,v 1.2 1997/08/04 10:24:26 mdw Exp $
 *
 * Miscellaneous useful bits of code.
 *
 * (c) 1997 Mark Wooding
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of `become'
 *
 * `Become' is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * `Become' 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 General Public License
 * along with `become'; if not, write to the Free Software Foundation,
 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

/*----- Revision history --------------------------------------------------*
 *
 * $Log: utils.h,v $
 * Revision 1.2  1997/08/04 10:24:26  mdw
 * Sources placed under CVS control.
 *
 * Revision 1.1  1997/07/21  13:47:42  mdw
 * Initial revision
 *
 */

#ifndef UTILS_H
#define UTILS_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Required header files ---------------------------------------------*/

#include <stddef.h>
#include <stdlib.h>

/*----- Storing and retrieving numbers ------------------------------------*
 *
 * These use big-endian conventions, because they seem more usual in network
 * applications.  I actually think that little-endian is more sensible...
 */

#define load32(p)                                                       \
  ((((unsigned char)(p)[0] & 0xFF) << 24) |                             \
   (((unsigned char)(p)[1] & 0xFF) << 16) |                             \
   (((unsigned char)(p)[2] & 0xFF) <<  8) |                             \
   (((unsigned char)(p)[3] & 0xFF) <<  0))

#define store32(p, v)                                                   \
  ((p)[0] = ((unsigned long)(v) >> 24) & 0xFF,                          \
   (p)[1] = ((unsigned long)(v) >> 16) & 0xFF,                          \
   (p)[2] = ((unsigned long)(v) >>  8) & 0xFF,                          \
   (p)[3] = ((unsigned long)(v) >>  0) & 0xFF)

/* --- Little-endian versions (for MD5) --- */

#define load32_l(p)                                                     \
  ((((unsigned char)(p)[0] & 0xFF) <<  0) |                             \
   (((unsigned char)(p)[1] & 0xFF) <<  8) |                             \
   (((unsigned char)(p)[2] & 0xFF) << 16) |                             \
   (((unsigned char)(p)[3] & 0xFF) << 24))

#define store32_l(p, v)                                                 \
  ((p)[0] = ((unsigned long)(v) >>  0) & 0xFF,                          \
   (p)[1] = ((unsigned long)(v) >>  8) & 0xFF,                          \
   (p)[2] = ((unsigned long)(v) >> 16) & 0xFF,                          \
   (p)[3] = ((unsigned long)(v) >> 24) & 0xFF)

/*----- Other macros ------------------------------------------------------*/

/* --- @burn@ --- *
 *
 * Arguments:   @obj@ = some object
 *
 * Use:         Writes zero bytes over the object.
 */

#define burn(obj) ((void)memset(&obj, 0, sizeof(obj)))

/*----- Program name handling ---------------------------------------------*/

/* --- @quis@ --- *
 *
 * Arguments:   ---
 *
 * Returns:     Pointer to the program name.
 *
 * Use:         Returns the program name.
 */

extern const char *quis(void);

/* --- @ego@ --- *
 *
 * Arguments:   @const char *p@ = pointer to program name
 *
 * Returns:     ---
 *
 * Use:         Tells the utils library what the program's name is.
 */

extern void ego(const char */*p*/);

/*----- Error reporting ---------------------------------------------------*/

/* --- @moan@ --- *
 *
 * Arguments:   @const char *f@ = a @printf@-style format string
 *              @...@ = other arguments
 *
 * Returns:     ---
 *
 * Use:         Reports an error.
 */

extern void moan(const char */*f*/, ...);

/* --- @die@ --- *
 *
 * Arguments:   @const char *f@ = a @printf@-style format string
 *              @...@ = other arguments
 *
 * Returns:     Never.
 *
 * Use:         Reports an error and hari-kiris.  Like @moan@ above, only
 *              more permanent.
 */

extern void die(const char */*f*/, ...);

/*----- Trace messages ----------------------------------------------------*/

#if !defined(NDEBUG) && !defined(TRACING)
#  define TRACING
#endif

#ifdef TRACING

/* --- @trace@ --- *
 *
 * Arguments:   @unsigned int lvl@ = trace level for output
 *              @const char *f@ = a @printf@-style format string
 *              @...@ = other arguments
 *
 * Returns:     ---
 *
 * Use:         Reports a message to the trace output.
 */

extern void trace(unsigned int /*lvl*/, const char */*f*/, ...);

/* --- @traceblk@ --- *
 *
 * Arguments:   @unsigned int lvl@ = trace level for output
 *              @const char *hdr@ = some header string to write
 *              @const void *blk@ = pointer to a block of memory to dump
 *              @size_t sz@ = size of the block of memory
 *
 * Returns:     ---
 *
 * Use:         Dumps the contents of a block to the trace output.
 */

extern void traceblk(unsigned int /*lvl*/, const char */*hdr*/,
                     const void */*blk*/, size_t /*sz*/);

/* --- @traceon@ --- *
 *
 * Arguments:   @FILE *fp@ = a file to trace on
 *              @unsigned int lvl@ = trace level to set
 *
 * Returns:     ---
 *
 * Use:         Enables tracing to a file.
 */

extern void traceon(FILE */*fp*/, unsigned int /*lvl*/);

/* --- @tracesetlvl@ --- *
 *
 * Arguments:   @unsigned int lvl@ = trace level to set
 *
 * Returns:     ---
 *
 * Use:         Sets the tracing level.
 */

extern void tracesetlvl(unsigned int /*lvl*/);

/* --- @tracing@ --- *
 *
 * Arguments:   ---
 *
 * Returns:     Zero if not tracing, tracing level if tracing.
 *
 * Use:         Informs the caller whether tracing is enabled.
 */

extern unsigned int tracing(void);

#endif

/* --- Some hacky macros --- */

#ifdef TRACING
#  define T(x) x
#  define IF_TRACING(lvl, x) if ((lvl) & tracing()) x
#else
#  define T(x)
#  define IF_TRACING(lvl, x)
#endif

/*----- Memory management functions ---------------------------------------*/

/* --- @xmalloc@ --- *
 *
 * Arguments:   @size_t sz@ = size of block to allocate
 *
 * Returns:     Pointer to allocated block.
 *
 * Use:         Allocates memory.  If the memory isn't available, we don't
 *              hang aroung long enough for a normal function return.
 */

extern void *xmalloc(size_t /*sz*/);

/* --- @xstrdup@ --- *
 *
 * Arguments:   @const char *s@ = pointer to a string
 *
 * Returns:     Pointer to a copy of the string.
 *
 * Use:         Copies a string (like @strdup@ would, if it existed).
 */

extern char *xstrdup(const char */*s*/);

/* --- @xrealloc@ --- *
 *
 * Arguments:   @void *p@ = pointer to a block of memory
 *              @size_t sz@ = new size desired for the block
 *
 * Returns:     Pointer to the resized memory block (which is almost
 *              certainly not in the same place any more).
 *
 * Use:         Resizes a memory block.
 */

extern void *xrealloc(void */*p*/, size_t /*sz*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif