evio.c File Reference

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <unistd.h>
#include <fcntl.h>
#include <pthread.h>
#include <sys/mman.h>
#include <sys/types.h>
#include <sys/stat.h>
#include "evio.h"

Defines
#define	EV_READFILE 0
#define	EV_READPIPE 1
#define	EV_READSOCK 2
#define	EV_READBUF 3
#define	EV_WRITEFILE 4
#define	EV_WRITEPIPE 5
#define	EV_WRITESOCK 6
#define	EV_WRITEBUF 7
#define	EV_MAGIC 0xc0da0100
	Number used to determine data endian.
#define	EV_BLOCKSIZE_V3 8192
	Version 3's fixed block size in 32 bit words.
#define	EV_BLOCKSIZE_V4 64000
	Version 4's target block size in 32 bit words (256kB).
#define	EV_BLOCKSIZE_MIN 256
	Minimum block size allowed if size reset.
#define	EV_BLOCKSIZE_MAX 25600000
	Maximum block size allowed if size reset.
#define	EV_VERSION_MASK 0xFF
	In version 4, lowest 8 bits are version, rest is bit info.
#define	EV_DICTIONARY_MASK 0x100
	In version 4, dictionary presence is 9th bit in version/info word.
#define	EV_LASTBLOCK_MASK 0x200
	In version 4, "last block" is 10th bit in version/info word.
#define	EV_EVENTS_MAX 100000
	In version 4, maximum max number of events per block.
#define	EV_EVENTS_MAX_DEF 10000
	In version 4, default max number of events per block.
#define	EV_SPLIT_SIZE 2000000000L
	In version 4, if splitting file, default split size in bytes (2GB).
#define	EV_HD_BLKSIZ 0
	Position of blk hdr word for size of block in 32-bit words.
#define	EV_HD_BLKNUM 1
	Position of blk hdr word for block number, starting at 0.
#define	EV_HD_HDSIZ 2
	Position of blk hdr word for size of header in 32-bit words (=8).
#define	EV_HD_COUNT 3
	Position of blk hdr word for number of events in block (version 4+).
#define	EV_HD_START 3
	Position of blk hdr word for first start of event in this block (ver 1-3).
#define	EV_HD_USED 4
	Position of blk hdr word for number of words used in block (<= BLKSIZ) (ver 1-3).
#define	EV_HD_RESVD1 4
	Position of blk hdr word for reserved (ver 4+).
#define	EV_HD_VER 5
	Position of blk hdr word for version of file format (+ bit info in ver 4+).
#define	EV_HD_RESVD2 6
	Position of blk hdr word for reserved.
#define	EV_HD_MAGIC 7
	Position of blk hdr word for magic number for endianness tracking.
#define	setDictionaryBit(a) ((a)[EV_HD_VER] \|= EV_DICTIONARY_MASK)
	Turn on 9th bit to indicate dictionary included in block.
#define	clearDictionaryBit(a) ((a)[EV_HD_VER] &= ~EV_DICTIONARY_MASK)
	Turn off 9th bit to indicate dictionary included in block.
#define	hasDictionary(a) (((a)[EV_HD_VER] & EV_DICTIONARY_MASK) > 0 ? 1 : 0)
	Is there a dictionary in this block?
#define	hasDictionaryInt(i) ((i & EV_DICTIONARY_MASK) > 0 ? 1 : 0)
	Is there a dictionary in this block?
#define	setLastBlockBit(a) ((a)[EV_HD_VER] \|= EV_LASTBLOCK_MASK)
	Turn on 10th bit to indicate last block of file/transmission.
#define	clearLastBlockBit(a) ((a)[EV_HD_VER] &= ~EV_LASTBLOCK_MASK)
	Turn off 10th bit to indicate last block of file/transmission.
#define	clearLastBlockBitInt(i) (i &= ~EV_LASTBLOCK_MASK)
	Turn off 10th bit to indicate last block of file/transmission.
#define	isLastBlock(a) (((a)[EV_HD_VER] & EV_LASTBLOCK_MASK) > 0 ? 1 : 0)
	Is this the last block of file/transmission?
#define	isLastBlockInt(i) ((i & EV_LASTBLOCK_MASK) > 0 ? 1 : 0)
	Is this the last block of file/transmission?
#define	initBlockHeader(a)
	Initialize a block header.
#define	initLastBlockHeader(a, b)
	Initialize a last block header.
Functions
void	evPrintBuffer (uint32_t *p, uint32_t len, int swap)
	Routine to print the contents of a buffer.
char *	evStrReplace (char orig, const char replace, const char *with)
	This routine substitutes a given string for a specified substring.
char *	evStrReplaceEnvVar (const char *orig)
	This routine finds constructs of the form and replaces it with the value of the ENV environmental variable if it exists or with nothing if it doesn't.
char *	evStrFindSpecifiers (const char orig, int specifierCount)
	This routine checks a string for C-style printing integer format specifiers.
char *	evStrRemoveSpecifiers (const char *orig)
	This routine checks a string for C-style printing integer format specifiers.
int	evGenerateBaseFileName (char origName, char baseName, int count)
	This routine generates a (base) file name from a name containing format specifiers and enviromental variables.
char *	evGenerateFileName (EVFILE a, int specifierCount, int runNumber, int split, int splitNumber, char runType)
	This method generates a complete file name from the previously determined baseFileName obtained from calling evGenerateBaseFileName and stored in the evOpen handle.
int	evopen_ (char filename, char flags, int *handle, int fnlen, int flen)
	Fortran interface to evOpen.
int	evOpen (char filename, char flags, int *handle)
	This function opens a file for either reading or writing evio format data.
int	evOpenBuffer (char buffer, uint32_t bufLen, char flags, int *handle)
	This function allows for either reading or writing evio format data from a buffer.
int	evOpenSocket (int sockFd, char flags, int handle)
	This function allows for either reading or writing evio format data from a TCP socket.
int	evOpenFake (char filename, char flags, int handle, char *evf)
int	evReadAlloc (int handle, uint32_t *buffer, uint32_t buflen)
	This routine reads an evio bank from an evio format file/socket/buffer opened with routines evOpen, evOpenBuffer, or evOpenSocket, allocates a buffer and fills it with the bank.
int evread int	evread_ (int handle, uint32_t buffer, uint32_t *buflen)
	Fortran interface to evRead.
int	evRead (int handle, uint32_t *buffer, uint32_t buflen)
	This routine reads from an evio format file/socket/buffer opened with routines evOpen, evOpenBuffer, or evOpenSocket and returns the next event in the buffer arg.
int	evReadNoCopy (int handle, const uint32_t *buffer, uint32_t buflen)
	This routine reads from an evio format file/buffer/socket opened with routines evOpen, evOpenBuffer, or evOpenSocket and returns a pointer to the next event residing in an internal buffer.
int	evReadRandom (int handle, const uint32_t *pEvent, uint32_t buflen, uint32_t eventNumber)
	This routine does a random access read from an evio format file/buffer opened with routines evOpen or evOpenBuffer.
int evwrite int	evwrite_ (int handle, const uint32_t buffer)
	Fortran interface to evWrite.
int	evWrite (int handle, const uint32_t *buffer)
	This routine writes an evio event to an internal buffer containing evio data.
int evclose int	evclose_ (int *handle)
	Fortran interface to evClose.
int	evClose (int handle)
	This routine flushes any existing evio format data in an internal buffer (written to with evWrite) to the final destination file/socket/buffer opened with routines evOpen, evOpenBuffer, or evOpenSocket.
int	evGetBufferLength (int handle, uint32_t *length)
	This routine returns the number of bytes written into a buffer so far when given a handle provided by calling evOpenBuffer.
int evioctl int	evioctl_ (int handle, char request, void *argp, int reqlen)
	Fortran interface to evIoctl.
int	evIoctl (int handle, char request, void argp)
	This routine changes various evio parameters used in reading and writing.
int	evGetRandomAccessTable (int handle, const uint32_t **table, uint32_t len)
	This routine gets an array of event pointers if the handle was opened in random access mode.
int	evGetDictionary (int handle, char *dictionary, uint32_t len)
	This routine gets the dictionary associated with this handle if there is any.
int	evWriteDictionary (int handle, char *xmlDictionary)
	This routine writes an optional dictionary as the first event of an evio file/socket/buffer.
const char *	evGetTypename (int type)
	This routine returns a string representation of an evio type.
int	evIsContainer (int type)
	This routine return true (1) if given type is a container, else returns false (0).
char *	evPerror (int error)
	This routine returns a string describing the given error value.

Detailed Description

 Let's take a look at an evio block header also
 known as a physical record header.

 In versions 1, 2 & 3, evio files impose an anachronistic
 block structure. The complication that arises is that logical records
 (events) will sometimes cross physical record boundaries.

 ####################################
 Evio block header, versions 1,2 & 3:
 ####################################

 MSB(31)                          LSB(0)
 <---  32 bits ------------------------>
 _______________________________________
 |             Block Size              |
 |_____________________________________|
 |            Block Number             |
 |_____________________________________|
 |           Header Size = 8           |
 |_____________________________________|
 |               Start                 |
 |_____________________________________|
 |                Used                 |
 |_____________________________________|
 |              Version                |
 |_____________________________________|
 |              Reserved               |
 |_____________________________________|
 |              Magic #                |
 |_____________________________________|

      Block Size    = number of 32 bit ints in block (including this one).
                      This is fixed for versions 1-3, generally at 8192 (32768 bytes)
      Block Number  = id number (starting at 1)
      Header Size   = number of 32 bit nts in this header (always 8)
      Start         = offset to first event header in block relative to start of block
      Used          = # of used/valid words (header + data) in block,
                      (normally = block size, but in last block may be smaller)
      Version       = evio format version
      Reserved      = reserved
      Magic #       = magic number (0xc0da0100) used to check endianness

 In version 4, only an integral number of complete
 events will be contained in a single block.

 ################################
 Evio block header, version 4+:
 ################################

 MSB(31)                          LSB(0)
 <---  32 bits ------------------------>
 _______________________________________
 |             Block Size              |
 |_____________________________________|
 |            Block Number             |
 |_____________________________________|
 |          Header Length = 8          |
 |_____________________________________|
 |             Event Count             |
 |_____________________________________|
 |              Reserved               |
 |_____________________________________|
 |          Bit info         | Version |
 |_____________________________________|
 |              Reserved               |
 |_____________________________________|
 |            Magic Number             |
 |_____________________________________|

      Block Size         = number of ints in block (including this one).
      Block Number       = id number (starting at 1)
      Header Length      = number of ints in this header (EV_HDSIZ which is currently 8)
      Event Count        = number of events in this block (always an integral #).
                           NOTE: this value should not be used to parse the following
                           events since the first block may have a dictionary whose
                           presence is not included in this count.
      Bit info & Version = Lowest 8 bits are the version number (4).
                           Upper 24 bits contain bit info.
                           If a dictionary is included as the first event, bit #9 is set (=1)
      Magic #            = magic number (0xc0da0100) used to check endianness

   Bit info (24 bits) has the following bits defined:

   Bit  9     = true if dictionary is included (relevant for first block only)
   Bit  10    = true if this block is the last block in file or network transmission
   Bits 11-14 = type of events following (ROC Raw = 0, Physics = 1, PartialPhysics = 2,
                DisentangledPhysics = 3, User = 4, Control = 5, Prestart = 6, Go = 7,
                Pause = 8, End = 9, Other = 15)

 ################################
 COMPOSITE DATA:
 ################################
   This is a new type of data (value = 0xf) which originated with Hall B.
   It is a composite type and allows for possible expansion in the future
   if there is a demand. Basically it allows the user to specify a custom
   format by means of a string - stored in a tagsegment. The data in that
   format follows in a bank. The routine to swap this data must be provided
   by the definer of the composite type - in this case Hall B. The swapping
   function is plugged into this evio library's swapping routine.
   Here's what it looks like.

 MSB(31)                          LSB(0)
 <---  32 bits ------------------------>
 _______________________________________
 |  tag    | type |    length          | --> tagsegment header
 |_________|______|____________________|
 |        Data Format String           |
 |                                     |
 |_____________________________________|
 |              length                 | \
 |_____________________________________|  \  bank header
 |       tag      |  type   |   num    |  /
 |________________|_________|__________| /
 |               Data                  |
 |                                     |
 |_____________________________________|

   The beginning tagsegment is a normal evio tagsegment containing a string
   (type = 0x3). Currently its type and tag are not used - at least not for
   data formatting.
   The bank is a normal evio bank header with data following.
   The format string is used to read/write this data so that takes care of any
   padding that may exist. As with the tagsegment, the tags and type are ignored.

Define Documentation

#define clearDictionaryBit ( a ) ((a)[EV_HD_VER] &= ~EV_DICTIONARY_MASK)

Turn off 9th bit to indicate dictionary included in block.

#define clearLastBlockBit ( a ) ((a)[EV_HD_VER] &= ~EV_LASTBLOCK_MASK)

Turn off 10th bit to indicate last block of file/transmission.

#define clearLastBlockBitInt ( i ) (i &= ~EV_LASTBLOCK_MASK)

Turn off 10th bit to indicate last block of file/transmission.

#define EV_BLOCKSIZE_MAX 25600000

Maximum block size allowed if size reset.

Need to play nice with jevio. Can be a max of (2^31 - 1 - 2headers) = 2147483583 , but set it to 100MB.

Referenced by evIoctl().

#define EV_BLOCKSIZE_MIN 256

Minimum block size allowed if size reset.

Referenced by evIoctl().

#define EV_BLOCKSIZE_V3 8192

Version 3's fixed block size in 32 bit words.

#define EV_BLOCKSIZE_V4 64000

Version 4's target block size in 32 bit words (256kB).

#define EV_DICTIONARY_MASK 0x100

In version 4, dictionary presence is 9th bit in version/info word.

#define EV_EVENTS_MAX 100000

In version 4, maximum max number of events per block.

Referenced by evIoctl().

#define EV_EVENTS_MAX_DEF 10000

In version 4, default max number of events per block.

#define EV_HD_BLKNUM 1

Position of blk hdr word for block number, starting at 0.

#define EV_HD_BLKSIZ 0

Position of blk hdr word for size of block in 32-bit words.

#define EV_HD_COUNT 3

Position of blk hdr word for number of events in block (version 4+).

#define EV_HD_HDSIZ 2

Position of blk hdr word for size of header in 32-bit words (=8).

#define EV_HD_MAGIC 7

Position of blk hdr word for magic number for endianness tracking.

#define EV_HD_RESVD1 4

Position of blk hdr word for reserved (ver 4+).

#define EV_HD_RESVD2 6

Position of blk hdr word for reserved.

#define EV_HD_START 3

Position of blk hdr word for first start of event in this block (ver 1-3).

#define EV_HD_USED 4

Position of blk hdr word for number of words used in block (<= BLKSIZ) (ver 1-3).

#define EV_HD_VER 5

Position of blk hdr word for version of file format (+ bit info in ver 4+).

Referenced by evIoctl().

#define EV_LASTBLOCK_MASK 0x200

In version 4, "last block" is 10th bit in version/info word.

#define EV_MAGIC 0xc0da0100

Number used to determine data endian.

#define EV_READBUF 3

Referenced by evRead(), evReadNoCopy(), and evReadRandom().

#define EV_READFILE 0

Referenced by evClose(), evRead(), evReadNoCopy(), and evReadRandom().

#define EV_READPIPE 1

Referenced by evClose(), evRead(), and evReadNoCopy().

#define EV_READSOCK 2

Referenced by evRead(), and evReadNoCopy().

#define EV_SPLIT_SIZE 2000000000L

In version 4, if splitting file, default split size in bytes (2GB).

#define EV_VERSION_MASK 0xFF

In version 4, lowest 8 bits are version, rest is bit info.

#define EV_WRITEBUF 7

Referenced by evClose(), evIoctl(), and evWriteDictionary().

#define EV_WRITEFILE 4

Referenced by evClose(), evGenerateFileName(), evIoctl(), evOpenFake(), and evWriteDictionary().

#define EV_WRITEPIPE 5

Referenced by evClose(), evIoctl(), and evWriteDictionary().

#define EV_WRITESOCK 6

Referenced by evClose(), evIoctl(), and evWriteDictionary().

#define hasDictionary ( a ) (((a)[EV_HD_VER] & EV_DICTIONARY_MASK) > 0 ? 1 : 0)

Is there a dictionary in this block?

#define hasDictionaryInt ( i ) ((i & EV_DICTIONARY_MASK) > 0 ? 1 : 0)

Is there a dictionary in this block?

#define initBlockHeader ( a )

Value:

{ \
    (a)[EV_HD_BLKSIZ] = 0; \
    (a)[EV_HD_BLKNUM] = 1; \
    (a)[EV_HD_HDSIZ]  = EV_HDSIZ; \
    (a)[EV_HD_COUNT]  = 0; \
    (a)[EV_HD_RESVD1] = 0; \
    (a)[EV_HD_VER]    = EV_VERSION; \
    (a)[EV_HD_RESVD2] = 0; \
    (a)[EV_HD_MAGIC]  = EV_MAGIC; \
} \

Initialize a block header.

#define initLastBlockHeader	(	a,
		b		)

Value:

{ \
    (a)[EV_HD_BLKSIZ] = 8; \
    (a)[EV_HD_BLKNUM] = b; \
    (a)[EV_HD_HDSIZ]  = EV_HDSIZ; \
    (a)[EV_HD_COUNT]  = 0; \
    (a)[EV_HD_RESVD1] = 0; \
    (a)[EV_HD_VER]    = EV_VERSION | EV_LASTBLOCK_MASK; \
    (a)[EV_HD_RESVD2] = 0; \
    (a)[EV_HD_MAGIC]  = EV_MAGIC; \
} \

Initialize a last block header.

Referenced by evIoctl().

#define isLastBlock ( a ) (((a)[EV_HD_VER] & EV_LASTBLOCK_MASK) > 0 ? 1 : 0)

Is this the last block of file/transmission?

#define isLastBlockInt ( i ) ((i & EV_LASTBLOCK_MASK) > 0 ? 1 : 0)

Is this the last block of file/transmission?

#define setDictionaryBit ( a ) ((a)[EV_HD_VER] |= EV_DICTIONARY_MASK)

Turn on 9th bit to indicate dictionary included in block.

#define setLastBlockBit ( a ) ((a)[EV_HD_VER] |= EV_LASTBLOCK_MASK)

Turn on 10th bit to indicate last block of file/transmission.

Function Documentation

int evClose ( int handle )

This routine flushes any existing evio format data in an internal buffer (written to with evWrite) to the final destination file/socket/buffer opened with routines evOpen, evOpenBuffer, or evOpenSocket.

It also frees up the handle so it cannot be used any more without calling evOpen again. Any data written is in evio version 4 format and any opened file is closed. If reading, nothing is done.

Parameters:

handle

evio handle

Returns:: S_SUCCESS if successful; S_FAILURE if mapped memory does not unmap or pclose() failed; S_EVFILE_TRUNC if not enough room writing to a user-given buffer in evOpen; S_EVFILE_BADHANDLE if bad handle arg; fclose error if fclose error

References evfilestruct::baseFileName, evfilestruct::buf, evfilestruct::dictBuf, evfilestruct::dictionary, EV_READFILE, EV_READPIPE, EV_WRITEBUF, EV_WRITEFILE, EV_WRITEPIPE, EV_WRITESOCK, evfilestruct::file, evfilestruct::fileName, evfilestruct::mmapFile, evfilestruct::mmapFileSize, evfilestruct::pTable, evfilestruct::randomAccess, evfilestruct::runType, evfilestruct::rw, S_EVFILE_BADHANDLE, S_FAILURE, S_SUCCESS, and evfilestruct::sockFd.

Referenced by evclose_().

int evclose int evclose_ ( int * handle )

Fortran interface to evClose.

References evClose().

int evGenerateBaseFileName	(	char *	origName,
		char **	baseName,
		int *	count
	)

This routine generates a (base) file name from a name containing format specifiers and enviromental variables.

The given name may contain up to 2, C-style integer format specifiers (such as 03d, or x). If more than 2 are found, an error is returned.

If no "0" precedes any integer between the "%" and the "d" or "x" of the format specifier, it will be added automatically in order to avoid spaces in the final, generated file name. In the evGenerateFileName(String, int, int, int, int) routine, the first occurrence will be substituted with the given runNumber value. If the file is being split, the second will be substituted with the split number.

The file name may contain characters of the form which will be substituted with the value of the associated environmental variable or a blank string if none is found.

Parameters:

	origName	file name to modify
	baseName	pointer which gets filled with resulting file name
	count	pointer to int filled with number of format specifiers found

Returns:: S_SUCCESS if successful; S_FAILURE if bad format specifiers or more that 2 specifiers found; S_EVFILE_BADARG if args are null or origName is invalid; S_EVFILE_ALLOCFAIL if out-of-memory

References evStrFindSpecifiers(), evStrReplaceEnvVar(), S_EVFILE_ALLOCFAIL, S_EVFILE_BADARG, S_FAILURE, and S_SUCCESS.

char* evGenerateFileName	(	EVFILE *	a,
		int	specifierCount,
		int	runNumber,
		int	split,
		int	splitNumber,
		char *	runType
	)

This method generates a complete file name from the previously determined baseFileName obtained from calling evGenerateBaseFileName and stored in the evOpen handle.

All occurrences of the string "%s" in the baseFileName will be substituted with the value of the runType arg or nothing if the runType is null.

If evio data is to be split up into multiple files (split > 0), numbers are used to distinguish between the split files with splitNumber. If baseFileName contains C-style int format specifiers (specifierCount > 0), then the first occurrence will be substituted with the given runNumber value. If the file is being split, the second will be substituted with the splitNumber. If 2 specifiers exist and the file is not being split, no substitutions are made. If no specifier for the splitNumber exists, it is tacked onto the end of the file name. It returns the final file name or NULL if error. Free the result if non-NULL.

Parameters:

	handle	evio handle (contains file name to use as a basis for the generated file name)
	specifierCount	number of C-style int format specifiers in file name arg
	runNumber	CODA run number
	split	number of bytes at which to split off evio file (<= 0 if not)
	splitNumber	number of the split file
	runType	run type name

Returns:: NULL if error; generated file name (free if non-NULL)

References evfilestruct::baseFileName, EV_WRITEFILE, evStrRemoveSpecifiers(), evStrReplace(), and evfilestruct::rw.

int evGetBufferLength	(	int	handle,
		uint32_t *	length
	)

This routine returns the number of bytes written into a buffer so far when given a handle provided by calling evOpenBuffer.

After the handle is closed, this no longer returns anything valid.

Parameters:

	handle	evio handle
	length	pointer to int which gets filled with number of bytes written to buffer so far

Returns:: S_SUCCESS if successful; S_EVFILE_BADHANDLE if bad handle arg

References evfilestruct::rwBytesOut, S_EVFILE_BADHANDLE, and S_SUCCESS.

int evGetDictionary	(	int	handle,
		char **	dictionary,
		uint32_t *	len
	)

This routine gets the dictionary associated with this handle if there is any.

Memory must be freed by caller if a dictionary was successfully returned.

Parameters:

	handle	evio handle
	dictionary	pointer to string which gets filled with dictionary string (xml) if it exists, else gets filled with NULL. Memory for dictionary allocated here, must be freed by caller.
	len	pointer to int which gets filled with dictionary string length if there is one, else filled with 0. If this arg = NULL, no len is returned.

Returns:: S_SUCCESS if successful; S_EVFILE_BADARG if dictionary arg is NULL; S_EVFILE_ALLOCFAIL if cannot allocate memory; S_EVFILE_BADHANDLE if bad handle arg

References evfilestruct::dictionary, S_EVFILE_ALLOCFAIL, S_EVFILE_BADARG, S_EVFILE_BADHANDLE, and S_SUCCESS.

int evGetRandomAccessTable	(	int	handle,
		const uint32_t ***	table,
		uint32_t *	len
	)

This routine gets an array of event pointers if the handle was opened in random access mode.

User must not change the pointers in the array or the data being pointed to (hence the consts in the second parameter).

Parameters:

	handle	evio handle
	table	pointer to array of uint32_t pointers which gets filled with an array of event pointers. If this arg = NULL, error is returned.
	len	pointer to int which gets filled with the number of pointers in the array. If this arg = NULL, error is returned.

Returns:: S_SUCCESS if successful; S_EVFILE_BADMODE if handle not opened in random access mode; S_EVFILE_BADARG if table or len arg(s) is NULL; S_EVFILE_BADHANDLE if bad handle arg

References evfilestruct::eventCount, evfilestruct::pTable, evfilestruct::randomAccess, S_EVFILE_BADARG, S_EVFILE_BADHANDLE, S_EVFILE_BADMODE, and S_SUCCESS.

const char* evGetTypename ( int type )

This routine returns a string representation of an evio type.

Parameters:

type

numerical value of an evio type

Returns:: string representation of the given type

int evIoctl	(	int	handle,
		char *	request,
		void *	argp
	)

This routine changes various evio parameters used in reading and writing.

It changes the target block size (in 32-bit words) for writes if request = "B". If setting block size fails, writes can still continue with original block size. Minimum size = 1K + 8(header) words. Max size = 5120000 words.

It changes size of buffer (in 32-bit words) for writing to file/socket/pipe if request = "W". Must be >= block size + ending header (8). Max size = 5120008 words.

It changes the maximum number of events/block if request = "N". It only goes up to EV_EVENTS_MAX or 100,000. Used only in version 4.

It changes the number of bytes at which to split a file being written to if request = "S". If unset with this function, it defaults to EV_SPLIT_SIZE (2GB). NOTE: argp must point to 64 bit integer (not 32 bit)! Used only in version 4.

It sets the run number used when auto naming while splitting files being written to if request = "R". Used only in version 4.

It sets the run type used when auto naming while splitting files being written to if request = "T". Used only in version 4.

It returns the version number if request = "V".

It returns the total number of events in a file/buffer opened for reading or writing if request = "E". Includes any event added with evWrite call. Used only in version 4.

It returns a pointer to the EV_HDSIZ block header ints if request = "H". This pointer must be freed by the caller to avoid a memory leak.

NOTE: all request strings are case insensitive. All version 4 commands to version 3 files are ignored.

Parameters:

handle

evio handle

request

case independent string value of:

"B" for setting target block size for writing in words
"W" for setting writing (to file) internal buffer size in words
"N" for setting max # of events/block
"R" for setting run number (used in file splitting)
"T" for setting run type (used in file splitting)
"S" for setting file split size in bytes
"V" for getting evio version #
"H" for getting 8 ints of block header info
"E" for getting # of events in file/buffer

argp

pointer to uin32_t containing new block size in 32-bit words if request = B, or
pointer to uin32_t containing new buffer size in 32-bit words if request = W, or
pointer to uin32_t containing new max # of events/block if request = N, or
pointer to uin32_t containing run number if request = R, or
pointer to character containing run type if request = T, or
pointer to int32_t returning version # if request = V, or
pointer to uint64_t containing max size in bytes of split file if request = S, or
address of pointer to uint32_t returning pointer to 8 uint32_t's of block header if request = H. This pointer must be freed by caller since it points to allocated memory
pointer to uin32_t returning total # of original events in existing file/buffer when reading or appending if request = E, or

Returns:: S_SUCCESS if successful; S_FAILURE if using sockets when request = E; S_EVFILE_BADARG if request is NULL or argp is NULL; S_EVFILE_BADFILE if file too small or problem reading file when request = E; S_EVFILE_BADHANDLE if bad handle arg; S_EVFILE_ALLOCFAIL if cannot allocate memory; S_EVFILE_UNXPTDEOF if buffer too small when request = E; S_EVFILE_UNKOPTION if unknown option specified in request arg; S_EVFILE_BADSIZEREQ when setting block/buffer size - if currently reading, have already written events with different block size, or is smaller than min allowed size (header size + 1K), or is larger than the max allowed size (5120000 words); when setting max # events/blk - if val < 1; errno if error in fseek, ftell when request = E

References evfilestruct::append, evfilestruct::blkEvCount, evfilestruct::blkEvMax, evfilestruct::blknum, evfilestruct::blkSizeTarget, evfilestruct::buf, evfilestruct::bufRealSize, evfilestruct::bufSize, evfilestruct::currentHeader, EV_BLOCKSIZE_MAX, EV_BLOCKSIZE_MIN, EV_EVENTS_MAX, EV_HD_VER, EV_WRITEBUF, EV_WRITEFILE, EV_WRITEPIPE, EV_WRITESOCK, initLastBlockHeader, evfilestruct::left, evfilestruct::next, evfilestruct::runNumber, evfilestruct::runType, evfilestruct::rw, S_EVFILE_ALLOCFAIL, S_EVFILE_BADARG, S_EVFILE_BADHANDLE, S_EVFILE_BADSIZEREQ, S_EVFILE_UNKOPTION, S_SUCCESS, evfilestruct::split, and UINT64_MAX.

Referenced by evioctl_().

int evioctl int evioctl_	(	int *	handle,
		char *	request,
		void *	argp,
		int	reqlen
	)

Fortran interface to evIoctl.

References evIoctl().

int evIsContainer ( int type )

This routine return true (1) if given type is a container, else returns false (0).

Parameters:

type

numerical value of an evio type

Returns:: 1 if given type is a container, else 0.

int evOpen	(	char *	filename,
		char *	flags,
		int *	handle
	)

This function opens a file for either reading or writing evio format data.

Works with all versions of evio for reading, but only writes version 4 format. A handle is returned for use with calling other evio routines.

Parameters:

	filename	name of file. Constructs of the form will be substituted with the given environmental variable or removed if nonexistent. Constructs of the form s will be substituted with the run type if specified in evIoctl or removed if nonexistent. Up to 2, C-style int format specifiers are allowed. The first is replaced with the run number (set in evIoctl). If splitting, the second is replaced by the split number, otherwise it's removed. If splitting and no second int specifier exists, a "." and split number are automatically appended to the end of the file name.
	flags	pointer to case-independent string of "w" for writing, "r" for reading, "a" for appending, "ra" for random access reading of a file, or "s" for splitting a file while writing
	handle	pointer to int which gets filled with handle

Returns:: S_SUCCESS if successful; S_FAILURE when splitting, if bad format specifiers or more that 2 specifiers found; S_EVFILE_BADARG if filename, flags or handle arg is NULL; unrecognizable flags;; S_EVFILE_ALLOCFAIL if memory allocation failed; S_EVFILE_BADFILE if error reading file, unsupported version, or contradictory data in file; errno if file could not be opened (handle = 0)

References S_EVFILE_BADARG.

Referenced by evopen_().

int evopen_	(	char *	filename,
		char *	flags,
		int *	handle,
		int	fnlen,
		int	flen
	)

Fortran interface to evOpen.

References evOpen().

int evOpenBuffer	(	char *	buffer,
		uint32_t	bufLen,
		char *	flags,
		int *	handle
	)

This function allows for either reading or writing evio format data from a buffer.

Works with all versions of evio for reading, but only writes version 4 format. A handle is returned for use with calling other evio routines.

Parameters:

	buffer	pointer to buffer
	bufLen	length of buffer in 32 bit ints
	flags	pointer to case-independent string of "w", "r", "a", or "ra" for writing/reading/appending/random-access-reading to/from a buffer.
	handle	pointer to int which gets filled with handle

Returns:: S_SUCCESS if successful; S_EVFILE_BADARG if buffer, flags or handle arg is NULL; unrecognizable flags; buffer size too small; S_EVFILE_ALLOCFAIL if memory allocation failed; S_EVFILE_BADFILE if error reading buffer, unsupported version, or contradictory data

References S_EVFILE_BADARG.

int evOpenFake	(	char *	filename,
		char *	flags,
		int *	handle,
		char **	evf
	)

References evfilestruct::baseFileName, EV_WRITEFILE, evfilestruct::rw, and S_SUCCESS.

int evOpenSocket	(	int	sockFd,
		char *	flags,
		int *	handle
	)

This function allows for either reading or writing evio format data from a TCP socket.

Works with all versions of evio for reading, but only writes version 4 format. A handle is returned for use with calling other evio routines.

Parameters:

	sockFd	TCP socket file descriptor
	flags	pointer to case-independent string of "w" & "r" for writing/reading to/from a socket
	handle	pointer to int which gets filled with handle

Returns:: S_SUCCESS if successful; S_EVFILE_BADARG if flags or handle arg is NULL; bad file descriptor arg; unrecognizable flags; S_EVFILE_ALLOCFAIL if memory allocation failed; S_EVFILE_BADFILE if error reading socket, unsupported version, or contradictory data; errno if socket read error

References S_EVFILE_BADARG.

char* evPerror ( int error )

This routine returns a string describing the given error value.

The returned string is a static char array. This means it is not thread-safe and will be overwritten on subsequent calls.

Parameters:

error

error condition

Returns:: error string

References S_EVFILE, S_EVFILE_ALLOCFAIL, S_EVFILE_BADARG, S_EVFILE_BADBLOCK, S_EVFILE_BADFILE, S_EVFILE_BADHANDLE, S_EVFILE_BADMODE, S_EVFILE_BADSIZEREQ, S_EVFILE_TRUNC, S_EVFILE_UNKOPTION, S_EVFILE_UNXPTDEOF, S_FAILURE, and S_SUCCESS.

void evPrintBuffer	(	uint32_t *	p,
		uint32_t	len,
		int	swap
	)

Routine to print the contents of a buffer.

Parameters:

	p	pointer to buffer
	len	number of 32-bit words to print out
	swap	swap if true

References EVIO_SWAP32.

int evRead	(	int	handle,
		uint32_t *	buffer,
		uint32_t	buflen
	)

This routine reads from an evio format file/socket/buffer opened with routines evOpen, evOpenBuffer, or evOpenSocket and returns the next event in the buffer arg.

Works with all versions of evio. A status is returned.

Parameters:

	handle	evio handle
	buffer	pointer to buffer
	buflen	length of buffer in 32 bit words

Returns:: S_SUCCESS if successful; S_EVFILE_BADMODE if opened for writing or random-access reading; S_EVFILE_TRUNC if buffer provided by caller is too small for event read; S_EVFILE_BADARG if buffer is NULL or buflen < 3; S_EVFILE_BADHANDLE if bad handle arg; S_EVFILE_ALLOCFAIL if memory cannot be allocated; S_EVFILE_UNXPTDEOF if unexpected EOF or end-of-valid-data while reading data (perhaps bad block header); EOF if end-of-file or end-of-valid-data reached; errno if file/socket read error; stream error if file stream error

References evfilestruct::byte_swapped, EV_READBUF, EV_READFILE, EV_READPIPE, EV_READSOCK, EVIO_SWAP32, evioswap(), evfilestruct::left, evfilestruct::next, evfilestruct::randomAccess, evfilestruct::rw, S_EVFILE_ALLOCFAIL, S_EVFILE_BADARG, S_EVFILE_BADHANDLE, S_EVFILE_BADMODE, S_EVFILE_TRUNC, and S_SUCCESS.

Referenced by evread_().

int evread int evread_	(	int *	handle,
		uint32_t *	buffer,
		uint32_t *	buflen
	)

Fortran interface to evRead.

References evRead().

int evReadAlloc	(	int	handle,
		uint32_t **	buffer,
		uint32_t *	buflen
	)

This routine reads an evio bank from an evio format file/socket/buffer opened with routines evOpen, evOpenBuffer, or evOpenSocket, allocates a buffer and fills it with the bank.

Works with all versions of evio. A status is returned.

Parameters:

	handle	evio handle
	buffer	pointer to pointer to buffer gets filled with pointer to allocated buffer (caller must free)
	buflen	pointer to int gets filled with length of buffer in 32 bit words including the full (8 byte) bank header

Returns:: S_SUCCESS if successful; S_EVFILE_BADMODE if opened for writing or random-access reading; S_EVFILE_BADARG if buffer or buflen is NULL; S_EVFILE_BADHANDLE if bad handle arg; S_EVFILE_ALLOCFAIL if memory cannot be allocated; S_EVFILE_UNXPTDEOF if unexpected EOF or end-of-valid-data while reading data (perhaps bad block header); EOF if end-of-file or end-of-valid-data reached; errno if file/socket read error; stream error if file stream error

References S_EVFILE_BADHANDLE.

int evReadNoCopy	(	int	handle,
		const uint32_t **	buffer,
		uint32_t *	buflen
	)

This routine reads from an evio format file/buffer/socket opened with routines evOpen, evOpenBuffer, or evOpenSocket and returns a pointer to the next event residing in an internal buffer.

If the data needs to be swapped, it is swapped in place. Any other calls to read routines may cause the data to be overwritten. No writing to the returned pointer is allowed. Works only with evio version 4 and up. A status is returned.

Parameters:

	handle	evio handle
	buffer	pointer to pointer to buffer gets filled with pointer to location in internal buffer which is guaranteed to be valid only until the next evRead, evReadNoAlloc, or evReadNoCopy call.
	buflen	pointer to int gets filled with length of buffer in 32 bit words including the full (8 byte) bank header

Returns:: S_SUCCESS if successful; S_EVFILE_BADMODE if opened for writing or random-access reading; S_EVFILE_BADARG if buffer or buflen is NULL; S_EVFILE_BADFILE if version < 4, unsupported or bad format; S_EVFILE_BADHANDLE if bad handle arg; S_EVFILE_ALLOCFAIL if memory cannot be allocated; S_EVFILE_UNXPTDEOF if unexpected EOF or end-of-valid-data while reading data (perhaps bad block header); EOF if end-of-file or end-of-valid-data reached; errno if file/socket read error; stream error if file stream error

References evfilestruct::byte_swapped, EV_READBUF, EV_READFILE, EV_READPIPE, EV_READSOCK, EVIO_SWAP32, evioswap(), evfilestruct::left, evfilestruct::next, evfilestruct::randomAccess, evfilestruct::rw, S_EVFILE_BADARG, S_EVFILE_BADFILE, S_EVFILE_BADHANDLE, S_EVFILE_BADMODE, S_SUCCESS, and evfilestruct::version.

int evReadRandom	(	int	handle,
		const uint32_t **	pEvent,
		uint32_t *	buflen,
		uint32_t	eventNumber
	)

This routine does a random access read from an evio format file/buffer opened with routines evOpen or evOpenBuffer.

It returns a pointer to the desired event residing in either a memory mapped file or buffer when opened in random access mode.

If the data needs to be swapped, it is swapped in place. No writing to the returned pointer is allowed. Works only with evio version 4 and up. A status is returned.

Parameters:

	handle	evio handle
	buffer	pointer which gets filled with pointer to event in buffer or memory mapped file
	buflen	pointer to int gets filled with length of buffer in 32 bit words including the full (8 byte) bank header
	eventNumber	the number of the event to be read (returned) starting at 1.

Returns:: S_SUCCESS if successful; S_FAILURE if no events found in file or failure to make random access map; S_EVFILE_BADMODE if not opened for random access reading; S_EVFILE_BADARG if pEvent arg is NULL; S_EVFILE_BADFILE if version < 4, unsupported or bad format; S_EVFILE_BADHANDLE if bad handle arg

References evfilestruct::byte_swapped, EV_READBUF, EV_READFILE, evfilestruct::eventCount, EVIO_SWAP32, evioswap(), evfilestruct::pTable, evfilestruct::randomAccess, evfilestruct::rw, S_EVFILE_BADARG, S_EVFILE_BADFILE, S_EVFILE_BADHANDLE, S_EVFILE_BADMODE, S_FAILURE, S_SUCCESS, and evfilestruct::version.

char* evStrFindSpecifiers	(	const char *	orig,
		int *	specifierCount
	)

This routine checks a string for C-style printing integer format specifiers.

More specifically, it checks for nd and nx where n can be multiple digits. It makes sure that there is at least one digit between % and x/d and that the first digit is a "0" so that generated filenames contain no white space. It returns the modified string or NULL if error. Free the result if non-NULL. It also returns the number of valid specifiers found in the orig argument.

Parameters:

	orig	string to be checked/modified
	specifierCount	pointer to int which gets filled with the number of valid format specifiers in the orig arg

Returns:: resulting string which is NULL if there is a problem and needs to be freed if not NULL.

References evStrReplace().

Referenced by evGenerateBaseFileName().

char* evStrRemoveSpecifiers ( const char * orig )

This routine checks a string for C-style printing integer format specifiers.

More specifically, it checks for nd and nx where n can be multiple digits. It removes all such specifiers and returns the modified string or NULL if error. Free the result if non-NULL.

Parameters:

orig

string to be checked/modified

Returns:: resulting string which is NULL if there is a problem and needs to be freed if not NULL.

Referenced by evGenerateFileName().

char* evStrReplace	(	char *	orig,
		const char *	replace,
		const char *	with
	)

This routine substitutes a given string for a specified substring.

Free the result if non-NULL.

Parameters:

	orig	string to modify
	replace	substring in orig arg to replace
	with	string to substitute for replace arg

Returns:: resulting string which is NULL if there is a problem and needs to be freed if not NULL.

Referenced by evGenerateFileName(), evStrFindSpecifiers(), and evStrReplaceEnvVar().

char* evStrReplaceEnvVar ( const char * orig )

This routine finds constructs of the form and replaces it with the value of the ENV environmental variable if it exists or with nothing if it doesn't.

Simple enough to do without regular expressions. Free the result if non-NULL.

Parameters:

orig

string to modify

Returns:: resulting string which is NULL if there is a problem and needs to be freed if not NULL.

References evStrReplace().

Referenced by evGenerateBaseFileName().

int evWrite	(	int	handle,
		const uint32_t *	buffer
	)

This routine writes an evio event to an internal buffer containing evio data.

If that internal buffer is full, it is flushed to the final destination file/socket/buffer/pipe opened with routines evOpen, evOpenBuffer, or evOpenSocket. It writes data in evio version 4 format and returns a status.

Parameters:

	handle	evio handle
	buffer	pointer to buffer containing event to write

Returns:: S_SUCCESS if successful; S_EVFILE_BADMODE if opened for reading or appending to opposite endian file/buffer.; S_EVFILE_TRUNC if not enough room writing to a user-supplied buffer; S_EVFILE_BADARG if buffer is NULL; S_EVFILE_BADHANDLE if bad handle arg; S_EVFILE_ALLOCFAIL if cannot allocate memory; errno if file/socket write error; stream error if file stream error

Referenced by evwrite_().

int evwrite int evwrite_	(	int *	handle,
		const uint32_t *	buffer
	)

Fortran interface to evWrite.

References evWrite().

int evWriteDictionary	(	int	handle,
		char *	xmlDictionary
	)

This routine writes an optional dictionary as the first event of an evio file/socket/buffer.

The dictionary is not included in any event count.

Parameters:

	handle	evio handle
	xmlDictionary	string containing xml format dictionary or NULL to remove previously specified dictionary

Returns:: S_SUCCESS if successful; S_FAILURE if already written events/dictionary; S_EVFILE_BADMODE if reading or appending; S_EVFILE_BADARG if dictionary in wrong format; S_EVFILE_ALLOCFAIL if cannot allocate memory; S_EVFILE_BADHANDLE if bad handle arg; errno if file/socket write error; stream error if file stream error

References evfilestruct::append, evfilestruct::blknum, evfilestruct::dictBuf, evfilestruct::dictionary, evfilestruct::dictLength, EV_WRITEBUF, EV_WRITEFILE, EV_WRITEPIPE, EV_WRITESOCK, evfilestruct::eventCount, evfilestruct::rw, S_EVFILE_ALLOCFAIL, S_EVFILE_BADARG, S_EVFILE_BADHANDLE, S_EVFILE_BADMODE, S_FAILURE, and evfilestruct::wroteDictionary.

evio.c File Reference

Defines

Functions

Detailed Description

Define Documentation

Function Documentation