/**

 **	$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 <stdio.h>		/* 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__ */

