evio  6.0
 All Data Structures Files Functions Variables Typedefs Macros Groups
evio.h File Reference
#include <stdint.h>
#include <stdio.h>
#include <pthread.h>
#include <stddef.h>

Data Structures

struct  evfilestruct
 This structure contains information about file opened for either reading or writing. More...
 
struct  evioBlockHeaderV4_t
 Structure for Sergei Boiarinov's use. More...
 

Macros

#define EV_VERSION   6
 Evio format version, not the evio package version #. More...
 
#define EV_HDSIZ   8
 Size of block header in 32 bit words. More...
 
#define EV_HDSIZ_V6   14
 
#define EV_HDSIZ_BYTES   32
 
#define EV_HDSIZ_BYTES_V6   56
 
#define S_SUCCESS   0
 
#define S_FAILURE   -1
 
#define evio_err_abort(code, text)
 
#define S_EVFILE   0x00730000
 evfile.msg Event File I/O More...
 
#define S_EVFILE_TRUNC   0x40730001
 Event truncated on read/write. More...
 
#define S_EVFILE_BADBLOCK   0x40730002
 Bad block number encountered. More...
 
#define S_EVFILE_BADHANDLE   0x80730001
 Bad handle (file/stream not open) More...
 
#define S_EVFILE_ALLOCFAIL   0x80730002
 Failed to allocate memory. More...
 
#define S_EVFILE_BADFILE   0x80730003
 File format error. More...
 
#define S_EVFILE_UNKOPTION   0x80730004
 Unknown option specified. More...
 
#define S_EVFILE_UNXPTDEOF   0x80730005
 Unexpected end of file while reading event. More...
 
#define S_EVFILE_BADSIZEREQ   0x80730006
 Invalid buffer size request to evIoct. More...
 
#define S_EVFILE_BADARG   0x80730007
 Invalid function argument. More...
 
#define S_EVFILE_BADMODE   0x80730008
 Wrong mode used in evOpen for this operation. More...
 
#define EVIO_SWAP64(x)
 
#define EVIO_SWAP32(x)
 
#define EVIO_SWAP16(x)
 
#define EVIO_TO_64_BITS(low, high)
 Calculate a 64 bit result from 2 32 bit inputs. More...
 
#define EVIO_BH_LEN_OFFSET   0
 Offset in bytes from beginning of block header to block length. More...
 
#define EVIO_BH_BLKNUM_OFFSET   32
 Offset in bytes from beginning of block header to block number. More...
 
#define EVIO_BH_HDRLEN_OFFSET   64
 Offset in bytes from beginning of block header to header length. More...
 
#define EVIO_BH_EVCOUNT_OFFSET   96
 Offset in bytes from beginning of block header to event count. More...
 
#define EVIO_BH_BITINFO_OFFSET   160
 Offset in bytes from beginning of block header to bitInfo. More...
 
#define EVIO_BH_MAGNUM_OFFSET   224
 Offset in bytes from beginning of block header to magic number. More...
 

Typedefs

typedef struct evfilestruct EVFILE
 This structure contains information about file opened for either reading or writing. More...
 
typedef struct evioBlockHeaderV4_t evioBlockHeaderV4
 Structure for Sergei Boiarinov's use. More...
 

Functions

void set_user_frag_select_func (int32_t(*f)(int32_t tag))
 
int evioIsLocalHostBigEndian ()
 Is the local host big endian? More...
 
uint64_t evioToLongWord (uint32_t word1, uint32_t word2, int needToSwap)
 Take 2, 32 bit words and change that into a 64 bit word, taking endianness and swapping into account. More...
 
void evioswap (uint32_t *buffer, int tolocal, uint32_t *dest)
 Routine to swap the endianness of an evio event (bank). More...
 
void evioSwapFileHeaderV6 (uint32_t *header)
 Swap an evio version 6 file header in place (but not the following index arrary, etc). More...
 
void evioSwapRecordHeaderV6 (uint32_t *header)
 Swap an evio version 6 record header in place (but not the following index arrary, etc). More...
 
uint16_tswap_int16_t (uint16_t *data, unsigned int length, uint16_t *dest)
 This routine swaps a buffer of 16 bit integers. More...
 
uint32_tswap_int32_t (uint32_t *data, unsigned int length, uint32_t *dest)
 This routine swaps a buffer of 32 bit integers. More...
 
uint64_tswap_int64_t (uint64_t *data, unsigned int length, uint64_t *dest)
 This routine swaps a buffer of 64 bit integers. More...
 
int evOpen (char *filename, char *flags, int *handle)
 This function opens a file for either reading or writing evio format data. More...
 
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. More...
 
int evOpenSocket (int sockFd, char *flags, int *handle)
 This function allows for either reading or writing evio format data from a TCP socket. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
int evGetRandomAccessTable (int handle, uint32_t ***const table, uint32_t *len)
 This routine gets an array of event pointers if the handle was opened in random access mode. More...
 
int evWrite (int handle, const uint32_t *buffer)
 This routine writes an evio event to an internal buffer containing evio data. More...
 
int evIoctl (int handle, char *request, void *argp)
 This routine changes various evio parameters used in reading and writing. More...
 
int evFlush (int handle)
 This function flushes any remaining internally buffered data to file/socket. More...
 
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. More...
 
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. More...
 
int evGetFileName (int handle, char *name, size_t maxLength)
 This routine gets the name of the file currently being written to and opened with evOpen, Returned string may NOT be written into. More...
 
int evIsLastBlock (uint32_t sixthWord)
 Routine to take the 6th word of a block header and tell whether it's the last block or not. More...
 
int evGetDictionary (int handle, char **dictionary, uint32_t *len)
 This routine gets the dictionary associated with this handle if there is any. More...
 
int evStringsToBuf (uint32_t *buffer, int bufLen, char **strings, int stringCount, int *dataLen)
 This routine writes an array of strings, in evio format, into the given buffer. More...
 
int evBufToStrings (char *buffer, int bufLen, char ***pStrArray, int *strCount)
 This routine unpacks/parses an evio format buffer containing strings into an array of strings. More...
 
int evIsContainer (int type)
 This routine return true (1) if given type is a container, else returns false (0). More...
 
const char * evGetTypename (int type)
 This routine returns a string representation of an evio type. More...
 
char * evPerror (int error)
 This routine returns a string describing the given error value. More...
 
void evPrintBuffer (uint32_t *p, uint32_t len, int swap)
 Routine to print the contents of a buffer. More...
 
char * evStrReplace (char *orig, const char *replace, const char *with)
 This routine substitutes a given string for a specified substring. More...
 
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. More...
 
char * evStrFindSpecifiers (const char *orig, int *specifierCount)
 This routine checks a string for C-style printing integer format specifiers. More...
 
char * evStrRemoveSpecifiers (const char *orig)
 This routine checks a string for C-style printing integer format specifiers. More...
 
int evGenerateBaseFileName (char *origName, char **baseName, int *count)
 This routine generates a (base) file name from a name containing format specifiers and enviromental variables. More...
 
char * evGenerateFileName (EVFILE *a, int specifierCount, int runNumber, int splitting, int splitNumber, char *runType, uint32_t streamId)
 

Macro Definition 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_HDSIZ_BYTES   32
#define EV_HDSIZ_BYTES_V6   56
#define EV_HDSIZ_V6   14
#define EV_VERSION   6

Evio format version, not the evio package version #.

Referenced by evIsLastBlock().

#define EVIO_BH_BITINFO_OFFSET   160

Offset in bytes from beginning of block header to bitInfo.

#define EVIO_BH_BLKNUM_OFFSET   32

Offset in bytes from beginning of block header to block number.

#define EVIO_BH_EVCOUNT_OFFSET   96

Offset in bytes from beginning of block header to event count.

#define EVIO_BH_HDRLEN_OFFSET   64

Offset in bytes from beginning of block header to header length.

#define EVIO_BH_LEN_OFFSET   0

Offset in bytes from beginning of block header to block length.

#define EVIO_BH_MAGNUM_OFFSET   224

Offset in bytes from beginning of block header to magic number.

#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 S_EVFILE   0x00730000

evfile.msg Event File I/O

Referenced by evPerror().

#define S_EVFILE_ALLOCFAIL   0x80730002

Failed to allocate memory.

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

#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
#define S_EVFILE_BADMODE   0x80730008

Wrong mode used in evOpen for this operation.

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

#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 evGetFileName(), evPerror(), evRead(), and evStringsToBuf().

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

Typedef Documentation

typedef struct evfilestruct EVFILE

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

Structure for Sergei Boiarinov's use.

Function Documentation

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(EVFILE *, int, int, int, int, char *, uint32_t) 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
origNamefile name to modify
baseNamepointer which gets filled with resulting file name
countpointer 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  splitting,
int  splitNumber,
char *  runType,
uint32_t  streamId 
)

This method generates a complete file name from the previously determined baseFileName obtained from calling evGenerateBaseFileName(char *, char **, int *) 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.

If multiple streams of data, each writing a file, end up with the same file name, they can be differentiated by a stream id number. If the id is > 0, the string, ".strm" is appended to the very end of the file followed by the id number (e.g. filename.strm1). This is done after the run type, run number, split numbers, and env vars have been inserted into the file name.

Parameters
aevio handle (contains file name to use as a basis for the generated file name)
specifierCountnumber of C-style int format specifiers in file name arg
runNumberCODA run number
splittingis file being split (split > 0)? 1 - yes, 0 - no
splitNumbernumber of the split file
runTyperun type name
streamIdstreamId number (100 > id > -1)
Returns
NULL if error
generated file name (free if non-NULL)

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

int evIsLastBlock ( uint32_t  sixthWord)

Routine to take the 6th word of a block header and tell whether it's the last block or not.

Parameters
sixthWord6th word of an evio block header
Returns
1 of this is the last block, else 0

References EV_LASTBLOCK_MASK, EV_LASTBLOCK_MASK_V6, and EV_VERSION.

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

Routine to print the contents of a buffer.

Parameters
ppointer to buffer
lennumber of 32-bit words to print out
swapswap if true

References EVIO_SWAP32.

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
origstring to be checked/modified
specifierCountpointer 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
origstring 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
origstring to modify
replacesubstring in orig arg to replace
withstring 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
origstring 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().

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