annotate stitch/stitch.h @ 0:5242703e91d3 tip

Initial checkin for AIM92 aimR8.2 (last updated May 1997).

/*
    Copyright (c) Applied Psychology Unit, Medical Research Council. 1988, 1989
    ===========================================================================

    Permission to use, copy, modify, and distribute this software without fee 
    is hereby granted for research purposes, provided that this copyright 
    notice appears in all copies and in all supporting documentation, and that 
    the software is not redistributed for any fee (except for a nominal shipping 
    charge). Anyone wanting to incorporate all or part of this software in a
    commercial product must obtain a license from the Medical Research Council.

    The MRC makes no representations about the suitability of this 
    software for any purpose.  It is provided "as is" without express or implied 
    warranty.
 
    THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
    ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL THE
    A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 
    DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN 
    AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 
    OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
*/

/*
    stitch.h
    ========

    interface for stitch system.

    This contains many regrettable #defines which are the act of a parnoid
    bad typist who wishes to lerave nothing to chance. They are not as hostile
    as they might first seem being mostly to do with methodical means of
    allocation making more use of typeing to avoid any chance of a badly
    allocated data buffer. This file is supported by two other abstractions:
    buffer.[ch] which ensures a buffer is the size required without realoocation.
    wrap.[ch] which encapsulates allocations to detect buffer overflows.

    In general there are two levels of indirection between the macros defined
    below and the final calls for memory allocation from the C library function.
    The first level is a C pre-processor macro to get all the catsings right
    for lint and do things with types that procedures just can't do.
    The second level is just passes the allocation call on so it can
    be intercepted as an aid to portability.

*/


#ifndef _STITCH_H_
#define _STITCH_H_

/* redefinitions of general memory allocation to check number and cast argumnets */

#define Malloc(         _size,         _where )  stitch_malloc( (unsigned) ( _size ),                        _where )
#define Ralloc(         _size,         _where )  stitch_ralloc( (unsigned) ( _size ),                        _where )
#define Calloc(         _size, _items, _where )  stitch_malloc( (unsigned) ( _size ), (unsigned) ( _items ), _where )
#define Realloc( _old,  _size        , _where )  stitch_realloc( (Pointer) ( _old  ), (unsigned) ( _size  )         )

/* deallocation - delete destroys pointer to keep it out of trouble */

#define Free(        _old ) stitch_free( (Pointer) ( _old ) )
#define Delete( _variable ) ( Free( _variable ), _variable = 0 )

/* more names for the allocation */

#define Allocate(       _size,         _where )        stitch_malloc( (unsigned) ( _size ),                   _where )
#define AllocateZeroed( _size,         _where ) stitch_zeroed_malloc( (unsigned) ( _size ),                   _where )
#define AllocateCopied( _size, _model, _where ) stitch_copied_malloc( (unsigned) ( _size ), (Pointer) _model, _where )

#define Reallocate( _old, _size ) stitchRealloc( (Pointer) ( _old ), (unsigned) ( _size ) )

/* macros for allocation making more use of type of variable receiving pointer */

#define TypeSize( _pointer ) ( sizeof * (_pointer) 0 )

/* return pointer to New structure, random, zeroed or copied */

#define New(                   _type                            ) (_type  ) Allocate(       TypeSize( _type ),         stitchStructStr )
#define NewZeroed(             _type                            ) (_type  ) AllocateZeroed( TypeSize( _type ),         stitchStructStr )
#define NewCopied(             _type,            _model         ) (_type  ) AllocateCopied( TypeSize( _type ), _model, stitchStructStr )

/* return pointer to array of structures */

#define NewArray(              _type,        _n,         _where ) (_type *) Allocate(       sizeof (_type) * (unsigned) ( _n ),         _where )
#define NewZeroedArray(        _type,        _n,         _where ) (_type *) AllocateZeroed( sizeof (_type) * (unsigned) ( _n ),         _where )
#define NewCopiedArray(        _type,        _n, _model, _where ) (_type *) AllocateCopied( sizeof (_type) * (unsigned) ( _n ), _model, _where )

/* as above but declare variable to receive pointer as well like new in C++ */

#define DeclareNew(            _type, _name                     )  _type  _name = New(            _type                     )
#define DeclareNewZeroed(      _type, _name                     )  _type  _name = NewZeroed(      _type                     )
#define DeclareNewCopied(      _type, _name,     _model         )  _type  _name = NewCopied(      _type,     _model         )

#define DeclareNewArray(       _type, _name, _n,         _where )  _type *_name = NewArray(       _type, _n,         _where )
#define DeclareNewZeroedArray( _type, _name, _n,         _where )  _type *_name = NewZeroedArray( _type, _n,         _where )
#define DeclareNewCopiedArray( _type, _name, _n, _model, _where )  _type *_name = NewCopiedArray( _type, _n, _model, _where )

/* structure utilities */

#define CopyArray( _from, _to, _number ) ( stitch_bcopy( _from, _to, sizeof ( * ( _to ) ) * ( _number ) ), _to )
#define ZeroArray(        _to, _number ) ( stitch_bzero(        _to, sizeof ( * ( _to ) ) * ( _number ) ), _to )

#define Copy(      _from, _to          ) ( stitch_bcopy( _from, _to, sizeof ( * ( _to ) )               ), _to )
#define Zero(             _to          ) ( stitch_bzero(        _to, sizeof ( * ( _to ) )               ), _to )

#if 0

/* defines for new names for now ( removed for clarity ) */

#define       stitchMalloc( _size,         _where )        stitch_malloc( (unsigned) _size,         _where )
#define stitchZeroedMalloc( _size,         _where ) stitch_zeroed_malloc( (unsigned) _size,         _where )
#define stitchCopiedMalloc( _size, _model, _where ) stitch_copied_malloc( (unsigned) _size, _model, _where )

#define stitchRealloc( _pt, _size,         _where ) stitch_ralloc( (Pointer) _pt, (unsigned) _size, _where )

#define stitchFree( _old ) stitch_free( _old )
#endif


/* realy important typedefs.... */

#if PEDANTIC
typedef struct _void *Pointer ; /* pointer to object of unknown size effectively void * */
#else
typedef char    *Pointer ;
#endif
typedef char    *Address ;


/* a portable inteface to the system */

extern void           stitch_error()  ;

extern Pointer        stitch_malloc() ;
extern Pointer stitch_copied_malloc() ;
extern Pointer stitch_zeroed_malloc() ;
extern Pointer        stitch_ralloc() ;
extern Pointer        stitch_calloc() ;

extern void           stitch_free()   ;
extern void           stitch_exit()   ;

/* beware these definitions, they are for speed and fail if stitch.h not included */

extern void  (*stitch_bcopy)() ;
extern void  (*stitch_bzero)() ;

extern char stitchStructStr[] ;

#endif