evio  5.2
 All Data Structures Files Functions Variables Typedefs Macros Groups
read routines

These routines handle opening the ev lib for reading from a file, buffer, or socket. More...

Functions

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

Detailed Description

These routines handle opening the ev lib for reading from a file, buffer, or socket.

Function Documentation

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.

Evio string data is endian independent. The array pointed to in pStrArray is allocated here and needs to be freed by the caller. All strings contained in the array also need to be freed by the caller.

Parameters
bufferbuffer containing evio format string data (NOT including header)
bufLenlength of string data in bytes
pStrArrayaddress of string array which gets filled parsed strings
strCountpointer to int which get filled with the number of strings in string array
Returns
S_SUCCESS if successful
S_EVFILE_BADARG if buffer, pStrArray, or strCount arg is NULL, or if bufLen < 4.
S_EVFILE_TRUNC if not enough room in buffer
S_FAILURE if buffer not in proper evio format

References S_EVFILE_BADARG, S_FAILURE, and S_SUCCESS.

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
handleevio handle
bufferpointer to buffer
buflenlength 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, S_SUCCESS, and evfilestruct::version.

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
handleevio handle
bufferpointer to pointer to buffer gets filled with pointer to allocated buffer (caller must free)
buflenpointer 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
handleevio handle
bufferpointer to pointer to buffer gets filled with pointer to location in internal buffer which is guaranteed to be valid only until the next evRead, evReadAlloc, or evReadNoCopy call.
buflenpointer 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 reading a file from a remote machine, it is not wise to use the "ra" flag in evOpen. This memory maps the file which is not ideal over the network.

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
handleevio handle
pEventpointer which gets filled with pointer to event in buffer or memory mapped file
buflenpointer to int gets filled with length of buffer in 32 bit words including the full (8 byte) bank header
eventNumberthe 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.