evio.h File Reference

#include <stdio.h>
#include <pthread.h>
#include <stddef.h>
#include <stdint.h>

Data Structures
struct	evfilestruct
	This structure contains information about file opened for either reading or writing. More...
Defines
#define	EV_VERSION 4
#define	EV_HDSIZ 8
	Size of block header in 32 bit words.
#define	S_SUCCESS 0
#define	S_FAILURE -1
#define	evio_err_abort(code, text)
#define	S_EVFILE 0x00730000
	evfile.msg Event File I/O
#define	S_EVFILE_TRUNC 0x40730001
	Event truncated on read/write.
#define	S_EVFILE_BADBLOCK 0x40730002
	Bad block number encountered.
#define	S_EVFILE_BADHANDLE 0x80730001
	Bad handle (file/stream not open).
#define	S_EVFILE_ALLOCFAIL 0x80730002
	Failed to allocate event I/O structure.
#define	S_EVFILE_BADFILE 0x80730003
	File format error.
#define	S_EVFILE_UNKOPTION 0x80730004
	Unknown option specified.
#define	S_EVFILE_UNXPTDEOF 0x80730005
	Unexpected end of file while reading event.
#define	S_EVFILE_BADSIZEREQ 0x80730006
	Invalid buffer size request to evIoct.
#define	S_EVFILE_BADARG 0x80730007
	Invalid function argument.
#define	S_EVFILE_BADMODE 0x80730008
	Wrong mode used in evOpen for this operation.
#define	EVIO_SWAP64(x)
#define	EVIO_SWAP32(x)
#define	EVIO_SWAP16(x)
Typedefs
typedef struct evfilestruct	EVFILE
	This structure contains information about file opened for either reading or writing.
Functions
void	set_user_frag_select_func (int32_t(*f)(int32_t tag))
void	evioswap (uint32_t buffer, int tolocal, uint32_t dest)
	Routine to swap the endianness of an evio event (bank).
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	evRead (int handle, uint32_t *buffer, uint32_t size)
	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	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	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	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	evWrite (int handle, const uint32_t *buffer)
	This routine writes an evio event to an internal buffer containing evio data.
int	evIoctl (int handle, char request, void argp)
	This routine changes various evio parameters used in reading and writing.
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	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.
int	evIsContainer (int type)
	This routine return true (1) if given type is a container, else returns false (0).
const char *	evGetTypename (int type)
	This routine returns a string representation of an evio type.
char *	evPerror (int error)
	This routine returns a string describing the given error value.
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.

Define Documentation

#define EV_HDSIZ 8

Size of block header in 32 bit words.

Must never be smaller than 8, but can be set larger.

#define EV_VERSION 4

#define evio_err_abort	(	code,
		text		)

Value:

do { \
    fprintf (stderr, "%s at \"%s\":%d: %s\n", \
        text, __FILE__, __LINE__, strerror (code)); \
    exit (-1); \
} while (0)

#define EVIO_SWAP16 ( x )

Value:

( (((x) >> 8) & 0x00FF) | \
                         (((x) << 8) & 0xFF00) )

Referenced by eviofmtswap().

#define EVIO_SWAP32 ( x )

Value:

( (((x) >> 24) & 0x000000FF) | \
                         (((x) >> 8)  & 0x0000FF00) | \
                         (((x) << 8)  & 0x00FF0000) | \
                         (((x) << 24) & 0xFF000000) )

Referenced by eviofmtswap(), evPrintBuffer(), evRead(), evReadNoCopy(), evReadRandom(), swap_int32_t(), and swap_int32_t_value().

#define EVIO_SWAP64 ( x )

Value:

( (((x) >> 56) & 0x00000000000000FFL) | \
                         (((x) >> 40) & 0x000000000000FF00L) | \
                         (((x) >> 24) & 0x0000000000FF0000L) | \
                         (((x) >> 8)  & 0x00000000FF000000L) | \
                         (((x) << 8)  & 0x000000FF00000000L) | \
                         (((x) << 24) & 0x0000FF0000000000L) | \
                         (((x) << 40) & 0x00FF000000000000L) | \
                         (((x) << 56) & 0xFF00000000000000L) )

Referenced by eviofmtswap().

#define S_EVFILE 0x00730000

evfile.msg Event File I/O

Referenced by evPerror().

#define S_EVFILE_ALLOCFAIL 0x80730002

Failed to allocate event I/O structure.

Referenced by evGenerateBaseFileName(), evGetDictionary(), evIoctl(), evPerror(), evRead(), and evWriteDictionary().

#define S_EVFILE_BADARG 0x80730007

Invalid function argument.

Referenced by evGenerateBaseFileName(), evGetDictionary(), evGetRandomAccessTable(), evIoctl(), evOpen(), evOpenBuffer(), evOpenSocket(), evPerror(), evRead(), evReadNoCopy(), evReadRandom(), and evWriteDictionary().

#define S_EVFILE_BADBLOCK 0x40730002

Bad block number encountered.

Referenced by evPerror().

#define S_EVFILE_BADFILE 0x80730003

File format error.

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

#define S_EVFILE_BADHANDLE 0x80730001

Bad handle (file/stream not open).

Referenced by evClose(), evGetBufferLength(), evGetDictionary(), evGetRandomAccessTable(), evIoctl(), evPerror(), evRead(), evReadAlloc(), evReadNoCopy(), evReadRandom(), and evWriteDictionary().

#define S_EVFILE_BADMODE 0x80730008

Wrong mode used in evOpen for this operation.

Referenced by evGetRandomAccessTable(), evPerror(), evRead(), evReadNoCopy(), evReadRandom(), and evWriteDictionary().

#define S_EVFILE_BADSIZEREQ 0x80730006

Invalid buffer size request to evIoct.

Referenced by evIoctl(), and evPerror().

#define S_EVFILE_TRUNC 0x40730001

Event truncated on read/write.

Referenced by evPerror(), and evRead().

#define S_EVFILE_UNKOPTION 0x80730004

Unknown option specified.

Referenced by evIoctl(), and evPerror().

#define S_EVFILE_UNXPTDEOF 0x80730005

Unexpected end of file while reading event.

Referenced by evPerror().

#define S_FAILURE -1

Referenced by evClose(), evGenerateBaseFileName(), evPerror(), evReadRandom(), and evWriteDictionary().

#define S_SUCCESS 0

Referenced by evClose(), evGenerateBaseFileName(), evGetBufferLength(), evGetDictionary(), evGetRandomAccessTable(), evIoctl(), evOpenFake(), evPerror(), evRead(), evReadNoCopy(), and evReadRandom().

Typedef Documentation

typedef struct evfilestruct EVFILE

This structure contains information about file opened for either reading or writing.

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 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_().

void evioswap	(	uint32_t *	buf,
		int	tolocal,
		uint32_t *	dest
	)

Routine to swap the endianness of an evio event (bank).

Parameters:

	buf	buffer of evio event data to be swapped
	tolocal	if 0 buf contains data of same endian as local host, else buf has data of opposite endian
	dest	buffer to place swapped data into. If this is NULL, then dest = buf.

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

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 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 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 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 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.

void set_user_frag_select_func ( int32_t(*)(int32_t tag) f )

evio.h File Reference

Data Structures

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation