/** ** $Header: /sdsc/dev/vis/misc/libsdsc/v3.0/libsdsc/src/include/RCS/bin.h,v 1.9 1995/06/30 21:58:48 bduggan Exp $ ** Copyright (c) 1989-1995 San Diego Supercomputer Center (SDSC) ** a division of General Atomics, San Diego, California, USA ** ** Users and possessors of this source code are hereby granted a ** nonexclusive, royalty-free copyright and design patent license to ** use this code in individual software. License is not granted for ** commercial resale, in whole or in part, without prior written ** permission from SDSC. This source is provided "AS IS" without express ** or implied warranty of any kind. ** ** For further information contact: ** E-Mail: info@sds.sdsc.edu ** ** Surface Mail: Information Center ** San Diego Supercomputer Center ** P.O. Box 85608 ** San Diego, CA 92138-5608 ** (619) 534-5000 **/ /** ** FILE ** bin.h - Portable Binary I/O Package ** ** PROJECT ** libSDSC - SDSC standard function library ** ** PUBLIC CONTENTS ** d =defined constant ** f =function ** m =defined macro ** t =typedef/struct/union ** v =variable ** ? =other ** ** __BINH__ d File inclusion flag ** ** types... d upper-case type names ** BINMAXTYPE d maximum type name value ** BINNTYPE d number of types ** ** BINMBF d most-significant byte first ** BINLBF d least-significant byte first ** ** BINIEEE d IEEE floating point format ** BINVAX d VAX floating point format ** BINVAXG d VAX floating point format (with doubles in G format) ** BINCRAYMP d CRAY X/Y-MP floating point format ** ** BINNOFUNC d No nominated function ** BINDEFFUNC d default function ** ** BINOP... d operation codes ** ** BinField t Binary I/O Structure Field Description ** BinMachineInfo t Machine characteristics ** ** BinErrNo v error number ** BinNErr v number of error messages ** BinErrList v error messages ** BINE... d error codes ** ** PRIVATE CONTENTS ** none ** ** HISTORY ** $Log: bin.h,v $ ** Revision 1.9 1995/06/30 21:58:48 bduggan ** added ansi prototype for function pointer ** ** Revision 1.8 1995/06/29 00:12:59 bduggan ** changed copyright ** ** Revision 1.7 94/10/03 16:39:07 nadeau ** Built defined constant definitions in to code instead of using external ** include files generated by the Makefile. No longer seems necessary ** to generate on-the-fly since the value set is relatively static. ** Updated to ANSI C and C++ compatibility. ** Updated comments. ** Updated copyright message. ** ** Revision 1.6 92/09/02 15:13:28 vle ** Updated copyright notice. ** ** Revision 1.5 91/01/09 16:53:37 nadeau ** Cleaned up function declarations. ** ** Revision 1.4 90/06/25 10:39:12 ferrerj ** Added IBM floating point format. ** ** Revision 1.3 90/05/21 16:13:10 nadeau ** Changed BinFRead() et al from macros to function declarations. ** ** Revision 1.2 90/04/23 15:27:49 nadeau ** Changed BinErrno to BinErrNo and BinNerr to BinNErr. ** ** Revision 1.1 89/12/14 13:57:28 nadeau ** Initial revision ** */ #ifndef __BINH__ #define __BINH__ #include /* Needed to get FILE declaration */ /* * CONSTANTS * types... - upper-case type names * * DESCRIPTION * These #define's identify host program variable types and let the binary * I/O package read and write routines know how to store or retrieve bytes * from host buffer arrays and when to sign-extend. */ #define POINTER 0 #define CHAR 1 #define UCHAR 2 #define SHORT 3 #define LONG 4 #define INT 5 #define INT8 6 #define INT16 7 #define INT32 8 #define USHORT 9 #define ULONG 10 #define UINT 11 #define UINT8 12 #define UINT16 13 #define UINT32 14 #define BOOLEAN 15 #define FLOAT 16 #define DOUBLE 17 #define INT64 18 #define UINT64 19 #define BINMAXTYPE 19 #define BINNTYPE (BINMAXTYPE+1) /* * CONSTANTS * BINMBF - most-significant byte first * BINLBF - least-significant byte first * * DESCRIPTION * These #define's identify one of two types of byte ordering. * * Passed to BinByteOrder( ) or received from BinQByteOrder( ), these * indicate the byte order of THE FILE! * * When received from BinQMachine( ), these indicate the byte order of * THE HOST! */ #define BINMBF 0 #define BINLBF 1 /* 2-... reserved */ /* * CONSTANTS * BINIEEE - IEEE floating point format * BINVAX - VAX floating point format * BINVAXG - VAX floating point format (with doubles in G format) * BINCRAYMP - CRAY X/Y-MP floating point format * * DESCRIPTION * These #defines identify one of the floating point formats known by * the binary I/O package. * * Passed to BinFloatFormat( ) or received from BinQFloatFormat( ), these * indicate the floating point format OF THE FILE! */ #define BINIEEE 0 #define BINVAX 1 #define BINVAXG 2 #define BINCRAYMP 3 #define BINIBM 4 /* 4-... reserved */ /* * CONSTANTS * BINNOFUNC - No nominated function * BINDEFFUNC - default function * * DESCRIPTION * These #defines identify one of two special conditions for the error * handler function nomination done by BinErrorHandler( ). BINNOFUNC * indicates that no handler function is nominated. BINDEFFUNC indicates * the default error handler function should be used. */ #ifdef __STDC__ #define BINNOFUNC ((int (*)(int , int , int , void *, int , int))((long)0)) #define BINDEFFUNC ((int (*)(int , int , int , void *, int , int))((long)-1)) #else #define BINNOFUNC ((int (*)())((long)0)) #define BINDEFFUNC ((int (*)())((long)-1)) /* all other values reserved */ #endif /* * CONSTANTS * BINOPREAD - read operation in progress * BINOPWRITE - write operaiton in progress * BINOPREADSTRUCT - structure read operation in progress * BINOPWRITESTRUCT- structure write operation in progress * BINOPCONVERTFLOAT- floating point conversion operation in progress * * DESCRIPTION * Thse #defines identify the operation in progress at the time an * error occurred that caused the error handler function to be called. * Most errors are reported via return values from the Binary I/O * package functions. Integer truncation and floating point overflow * errors, however, are reported on a per-conversion basis by calling * the nominated handler function (see BinErrorHandler()). If no * handler function is nominated, an error message is printed to stderr. */ #define BINOPREAD 0 #define BINOPWRITE 1 #define BINOPREADSTRUCT 2 #define BINOPWRITESTRUCT 3 #define BINOPCONVERTFLOAT 4 /* 5-... reserved */ /* * TYPEDEF & STRUCTURE * BinField - Binary I/O Structure Field Description * * DESCRIPTION * The BinField struct describes a group of like-typed fields in a * structure to be read or written using the Binary I/O Struct calls. */ typedef struct BinField { int bin_type; /* Declared type of struct field*/ int bin_nbytes; /* # of bytes occupied in file */ int bin_count; /* # of repeatitions of this item*/ } BinField; /* * TYPEDEF & STRUCTURE * BinMachineInfo - Machine characteristics * * DESCRIPTION * The BinMachineInfo struct describes the machine and its C compiler's * characteristics. The structure is returned by a call to BinQMachine( ). * * bin_byteOrder is the byte order of the host. Use BinQByteOrder( ) * to query the byte order currently being assumed for files. * bin_byteOrderName is the character string name for the byte order. * * bin_floatFormat is the floating point format of the host. Use * BinQFloatFormat( ) to query the floating point format currently being * assumed for files. bin_floatFormatName is the character string name * for the floating point format. * * Each of bin_typeSize, bin_typeSigned, bin_typeRes, and bin_typePad * are arrays of BINNTYPE entries, one per type. * * bin_typeSize is the number of bytes required to store a single variable * of the type. An INT on a VAX has a size of 4 bytes, while on a * CRAY-XMP it has a size of 8 bytes. * * bin_typeSigned is a TRUE or FALSE value indicating if the type is * signed. * * bin_typeRes is the resolution, or number of significant bytes, of * the type. On most machines the size and resolution of a type are * the same. On a CRAY-XMP, however, a SHORT has a size of 8 bytes, * but a resolution of only 3 bytes. * * bin_typePad is the structure field padding needed for the type. * In other words, the table indicates what addressing boundaries * types are forced to be on when in structures. An INT on a VAX * running ULTRIX/UNIX is aligned (padded) to a 4 byte boundary. * A SHORT on the same VAX is aligned to a 2 byte boundary. All types * on a VAX running VMS are not aligned at all (on any 1 byte boundary). * All types, except CHAR's, on a CRAY-XMP are aligned to 8 byte * boundaries. * * bin_typeName is the lower-case C type names for the types. * * bin_reserved is space reserved for future expansion. */ typedef struct BinMachineInfo { /* Names */ char *bin_vendorName; /* Vendor name */ char *bin_machineName; /* Machine name (not host name) */ char *bin_cpuName; /* CPU name */ char *bin_osName; /* OS name */ /* CPU Characteristics */ int bin_byteOrder; /* CPU byte order */ char *bin_byteOrderName;/* CPU byte order name */ int bin_floatFormat; /* Floating point format */ char *bin_floatFormatName;/* Floating point format name */ /* Type Characteristics */ int *bin_typeSize; /* Sizes of types */ int *bin_typeSigned; /* Signed type or not? */ int *bin_typeRes; /* Resolution of types */ int *bin_typePad; /* Structure field padding of types */ char **bin_typeName; /* Names for the types */ unsigned long *bin_typePadMask; /* Pad mask */ int bin_reserved[9]; /* Reserved for future expansion */ } BinMachineInfo; /* * GLOBAL VARIABLE * BinErrNo - error number * BinNErr - number of error messages * BinErrList - error messages * * DESCRIPTION * On an error, the binary I/O package routines return -1 and set * BinErrno to an error code. The programmer may call BinPError * to print the associated error message to stderr, or may do the * message lookup in BinErrList themselves. */ extern int BinErrNo; /* Current error number */ extern int BinNErr; /* Number of error messages */ extern char *BinErrList[]; /* List of error messages */ /* * CONSTANTS * BINE... - error codes * * DESCRIPTION * BinErrno may be set to these error codes as a result of an error in * calling one of the binary I/O package routines. */ #define BINESYS 0 /* System error: see errno */ #define BINETYPE 1 /* Bad buffer type */ #define BINENBYTES 2 /* Bad # of occupied bytes in file*/ #define BINECOUNT 3 /* Bad # of items to read/write */ #define BINEBYTEORDER 4 /* Bad byte order selection */ #define BINEMALLOC 5 /* Malloc error */ #define BINEFLOATFORMAT 6 /* Bad float format selection */ #define BINEFLOATUNSUPPORTED 7 /* Unsupported size of float */ #define BINEFLOATOVERFLOW 8 /* Floating point overflow */ #define BINEINTEGERTRUNC 9 /* Integer truncation */ #define BINEFLOATUNDERFLOW 10 /* Floating point underflow */ /* * FUNCTIONS * BinQMachine - Query machine information * BinPError - Print error message * BinQError - Query error message * BinErrorHandler - nominate an error condition handler function * BinByteOrder - Select the byte order of the file * BinQByteOrder - Query the byte order of the file * BinRead - Read binary file * BinFRead - Read binary file * BinWrite - Write binary file * BinFWrite - Write binary file * BinReadStruct - Read binary file into a C struct * BinFReadStruct - Read binary file into a C struct * BinWriteStruct - Write binary file into a C struct * BinFWriteStruct - Write binary file into a C struct * * DESCRIPTION * The following functions comprise the binary I/O package. */ #ifdef __cplusplus extern "C" { #endif #ifdef __STDC__ extern BinMachineInfo * BinQMachine( void ); extern void BinPError( char * ); extern char * BinQError( void ); extern void BinErrorHandler( int (*)(int, int, int, void*, int, int ) ); extern int BinByteOrder( int ); extern int BinQByteOrder( void ); extern int BinFloatFormat( int ); extern int BinQFloatFormat( void ); extern int BinRead( int, void *, int, int, int ); extern int BinFRead( FILE *, void *, int, int, int ); extern int BinSRead( unsigned char *, void *, int, int, int ); extern int BinWrite( int, void *, int, int, int ); extern int BinFWrite( FILE *, void *, int, int, int ); extern int BinSWrite( unsigned char *, void *, int, int, int ); extern int BinReadStruct( int, void *, BinField * ); extern int BinFReadStruct( FILE *, void *, BinField * ); extern int BinSReadStruct( unsigned char *, void *, BinField * ); extern int BinWriteStruct( int, void *, BinField * ); extern int BinFWriteStruct( FILE *, void *, BinField * ); extern int BinSWriteStruct( unsigned char *, void *, BinField * ); #else extern BinMachineInfo * BinQMachine( ); extern void BinPError( ); extern char * BinQError( ); extern void BinErrorHandler( ); extern int BinByteOrder( ); extern int BinQByteOrder( ); extern int BinFloatFormat( ); extern int BinQFloatFormat( ); extern int BinRead( ); extern int BinFRead( ); extern int BinSRead( ); extern int BinWrite( ); extern int BinFWrite( ); extern int BinSWrite( ); extern int BinReadStruct( ); extern int BinFReadStruct( ); extern int BinSReadStruct( ); extern int BinWriteStruct( ); extern int BinFWriteStruct( ); extern int BinSWriteStruct( ); #endif #ifdef __cplusplus } #endif #endif /* __BINH__ */