Reading interface for OTF2 archives. More...

#include <stdint.h>
#include <otf2/OTF2_ErrorCodes.h>
#include <otf2/OTF2_Archive.h>

Typedefs
typedef struct OTF2_Reader_struct	OTF2_Reader
	Keeps all necessary information for the reader.

Functions
OTF2_Reader *	OTF2_Reader_Open (const char *anchorFilePath)
	Create a new reader handle. More...

OTF2_ErrorCode	OTF2_Reader_Close (OTF2_Reader *reader)
	Close a reader handle. More...

OTF2_ErrorCode	OTF2_Reader_SetHint (OTF2_Reader reader, OTF2_Hint hint, void value)
	Set the hint in the reader to the given value. More...

OTF2_ErrorCode	OTF2_Reader_SetCollectiveCallbacks (OTF2_Reader reader, const OTF2_CollectiveCallbacks collectiveCallbacks, void collectiveData, OTF2_CollectiveContext globalCommContext, OTF2_CollectiveContext *localCommContext)
	Set the collective callbacks for the reader. More...

OTF2_ErrorCode	OTF2_Reader_SetSerialCollectiveCallbacks (OTF2_Reader *reader)
	Convenient function to set the collective callbacks to a serial implementation. More...

OTF2_ErrorCode	OTF2_Reader_SetLockingCallbacks (OTF2_Reader reader, const OTF2_LockingCallbacks lockingCallbacks, void *lockingData)
	Set the locking callbacks for the reader. More...

OTF2_ErrorCode	OTF2_Reader_RegisterEvtCallbacks (OTF2_Reader reader, OTF2_EvtReader evtReader, const OTF2_EvtReaderCallbacks callbacks, void userData)
	Register event reader callbacks. More...

OTF2_ErrorCode	OTF2_Reader_RegisterGlobalEvtCallbacks (OTF2_Reader reader, OTF2_GlobalEvtReader evtReader, const OTF2_GlobalEvtReaderCallbacks callbacks, void userData)
	Register global event reader callbacks. More...

OTF2_ErrorCode	OTF2_Reader_RegisterDefCallbacks (OTF2_Reader reader, OTF2_DefReader defReader, const OTF2_DefReaderCallbacks callbacks, void userData)
	Register local definition reader callbacks. More...

OTF2_ErrorCode	OTF2_Reader_RegisterGlobalDefCallbacks (OTF2_Reader reader, OTF2_GlobalDefReader defReader, const OTF2_GlobalDefReaderCallbacks callbacks, void userData)
	Register global definition reader callbacks. More...

OTF2_ErrorCode	OTF2_Reader_RegisterSnapCallbacks (OTF2_Reader reader, OTF2_SnapReader snapReader, const OTF2_SnapReaderCallbacks callbacks, void userData)
	Register snapshot event reader callbacks. More...

OTF2_ErrorCode	OTF2_Reader_RegisterGlobalSnapCallbacks (OTF2_Reader reader, OTF2_GlobalSnapReader evtReader, const OTF2_GlobalSnapReaderCallbacks callbacks, void userData)
	Register global event reader callbacks. More...

OTF2_ErrorCode	OTF2_Reader_RegisterMarkerCallbacks (OTF2_Reader reader, OTF2_MarkerReader markerReader, const OTF2_MarkerReaderCallbacks callbacks, void userData)
	Register marker reader callbacks. More...

OTF2_ErrorCode	OTF2_Reader_ReadLocalEvents (OTF2_Reader reader, OTF2_EvtReader evtReader, uint64_t eventsToRead, uint64_t *eventsRead)
	Read a given number of events via a local event reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadAllLocalEvents (OTF2_Reader reader, OTF2_EvtReader evtReader, uint64_t *eventsRead)
	Read all events via a local event reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadLocalEventsBackward (OTF2_Reader reader, OTF2_EvtReader evtReader, uint64_t eventsToRead, uint64_t *eventsRead)
	Read a given number of events via a local event reader backwards. More...

OTF2_ErrorCode	OTF2_Reader_ReadGlobalEvent (OTF2_Reader reader, OTF2_GlobalEvtReader evtReader)
	Read an event via a global event reader. More...

OTF2_ErrorCode	OTF2_Reader_HasGlobalEvent (OTF2_Reader reader, OTF2_GlobalEvtReader evtReader, int *flag)
	Has the global event reader at least one more event to deliver. More...

OTF2_ErrorCode	OTF2_Reader_ReadGlobalEvents (OTF2_Reader reader, OTF2_GlobalEvtReader evtReader, uint64_t eventsToRead, uint64_t *eventsRead)
	Read a given number of events via a global event reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadAllGlobalEvents (OTF2_Reader reader, OTF2_GlobalEvtReader evtReader, uint64_t *eventsRead)
	Read all events via a global event reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadLocalDefinitions (OTF2_Reader reader, OTF2_DefReader defReader, uint64_t definitionsToRead, uint64_t *definitionsRead)
	Read a given number of definitions via a local definition reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadAllLocalDefinitions (OTF2_Reader reader, OTF2_DefReader defReader, uint64_t *definitionsRead)
	Read all definitions via a local definition reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadGlobalDefinitions (OTF2_Reader reader, OTF2_GlobalDefReader defReader, uint64_t definitionsToRead, uint64_t *definitionsRead)
	Read a given number of definitions via a global definition reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadAllGlobalDefinitions (OTF2_Reader reader, OTF2_GlobalDefReader defReader, uint64_t *definitionsRead)
	Read all definitions via a global definition reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadLocalSnapshots (OTF2_Reader reader, OTF2_SnapReader snapReader, uint64_t recordsToRead, uint64_t *recordsRead)
	Read a given number of records via a local snapshot reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadAllLocalSnapshots (OTF2_Reader reader, OTF2_SnapReader snapReader, uint64_t *recordsRead)
	Read all records via a local snapshot reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadGlobalSnapshots (OTF2_Reader reader, OTF2_GlobalSnapReader snapReader, uint64_t recordsToRead, uint64_t *recordsRead)
	Read a given number of records via a global snapshot reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadAllGlobalSnapshots (OTF2_Reader reader, OTF2_GlobalSnapReader snapReader, uint64_t *recordsRead)
	Read all records via a global snapshot reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadMarkers (OTF2_Reader reader, OTF2_MarkerReader markerReader, uint64_t markersToRead, uint64_t *markersRead)
	Read a given number of markers via a marker reader. More...

OTF2_ErrorCode	OTF2_Reader_ReadAllMarkers (OTF2_Reader reader, OTF2_MarkerReader markerReader, uint64_t *markersRead)
	Read all markers via a marker reader. More...

OTF2_EvtReader *	OTF2_Reader_GetEvtReader (OTF2_Reader *reader, OTF2_LocationRef location)
	Get a local event reader. More...

OTF2_GlobalEvtReader *	OTF2_Reader_GetGlobalEvtReader (OTF2_Reader *reader)
	Get a global event reader. More...

OTF2_DefReader *	OTF2_Reader_GetDefReader (OTF2_Reader *reader, OTF2_LocationRef location)
	Get a local definition reader. More...

OTF2_GlobalDefReader *	OTF2_Reader_GetGlobalDefReader (OTF2_Reader *reader)
	Get a global definition reader. More...

OTF2_SnapReader *	OTF2_Reader_GetSnapReader (OTF2_Reader *reader, OTF2_LocationRef location)
	Get a local snapshot reader. More...

OTF2_GlobalSnapReader *	OTF2_Reader_GetGlobalSnapReader (OTF2_Reader *reader)
	Get a global snap reader. More...

OTF2_ThumbReader *	OTF2_Reader_GetThumbReader (OTF2_Reader *reader, uint32_t number)
	Get a thumb reader. More...

OTF2_MarkerReader *	OTF2_Reader_GetMarkerReader (OTF2_Reader *reader)
	Get a marker reader. More...

OTF2_MarkerWriter *	OTF2_Reader_GetMarkerWriter (OTF2_Reader *reader)
	Get a marker writer. More...

OTF2_ErrorCode	OTF2_Reader_CloseEvtReader (OTF2_Reader reader, OTF2_EvtReader evtReader)
	Close a local event reader. More...

OTF2_ErrorCode	OTF2_Reader_CloseGlobalEvtReader (OTF2_Reader reader, OTF2_GlobalEvtReader globalEvtReader)
	Closes the global event reader. More...

OTF2_ErrorCode	OTF2_Reader_CloseDefReader (OTF2_Reader reader, OTF2_DefReader defReader)
	Close a local definition reader. More...

OTF2_ErrorCode	OTF2_Reader_CloseGlobalDefReader (OTF2_Reader reader, OTF2_GlobalDefReader globalDefReader)
	Closes the global definition reader. More...

OTF2_ErrorCode	OTF2_Reader_CloseSnapReader (OTF2_Reader reader, OTF2_SnapReader snapReader)
	Close a local snapshot reader. More...

OTF2_ErrorCode	OTF2_Reader_CloseGlobalSnapReader (OTF2_Reader reader, OTF2_GlobalSnapReader globalSnapReader)
	Closes the global snapshot reader. More...

OTF2_ErrorCode	OTF2_Reader_CloseThumbReader (OTF2_Reader reader, OTF2_ThumbReader thumbReader)
	Close an opened thumbnail reader. More...

OTF2_ErrorCode	OTF2_Reader_CloseMarkerReader (OTF2_Reader reader, OTF2_MarkerReader markerReader)
	Closes the marker reader. More...

OTF2_ErrorCode	OTF2_Reader_CloseMarkerWriter (OTF2_Reader reader, OTF2_MarkerWriter markerWriter)
	Closes the marker writer. More...

OTF2_ErrorCode	OTF2_Reader_GetVersion (OTF2_Reader reader, uint8_t major, uint8_t minor, uint8_t bugfix)
	Get OTF2 version. More...

OTF2_ErrorCode	OTF2_Reader_GetChunkSize (OTF2_Reader reader, uint64_t chunkSizeEvents, uint64_t *chunkSizeDefinitions)
	Get event and definition chunk sizes. More...

OTF2_ErrorCode	OTF2_Reader_GetFileSubstrate (OTF2_Reader reader, OTF2_FileSubstrate substrate)
	Get file substrate information. More...

OTF2_ErrorCode	OTF2_Reader_GetCompression (OTF2_Reader reader, OTF2_Compression compression)
	Get compression mode. More...

OTF2_ErrorCode	OTF2_Reader_GetNumberOfLocations (OTF2_Reader reader, uint64_t numberOfLocations)
	Get number of locations. More...

OTF2_ErrorCode	OTF2_Reader_GetNumberOfGlobalDefinitions (OTF2_Reader reader, uint64_t numberOfDefinitions)
	Get number of global definitions. More...

OTF2_ErrorCode	OTF2_Reader_GetMachineName (OTF2_Reader reader, char *machineName)
	Get machine name. More...

OTF2_ErrorCode	OTF2_Reader_GetCreator (OTF2_Reader reader, char *creator)
	Get creator name. More...

OTF2_ErrorCode	OTF2_Reader_GetDescription (OTF2_Reader reader, char *description)
	Get description. More...

OTF2_ErrorCode	OTF2_Reader_GetPropertyNames (OTF2_Reader reader, uint32_t numberOfProperties, char ***names)
	Get the names of all trace file properties. More...

OTF2_ErrorCode	OTF2_Reader_GetProperty (OTF2_Reader reader, const char name, char **value)
	Get the value of the named trace file property. More...

OTF2_ErrorCode	OTF2_Reader_GetBoolProperty (OTF2_Reader reader, const char name, bool *value)
	Get the value of the named trace file property as boolean. More...

OTF2_ErrorCode	OTF2_Reader_GetTraceId (OTF2_Reader reader, uint64_t id)
	Get the identifier of the trace file. More...

OTF2_ErrorCode	OTF2_Reader_GetNumberOfSnapshots (OTF2_Reader reader, uint32_t number)
	Get number of snapshots. More...

OTF2_ErrorCode	OTF2_Reader_GetNumberOfThumbnails (OTF2_Reader reader, uint32_t number)
	Get number of thumbs. More...

OTF2_ErrorCode	OTF2_Reader_OpenEvtFiles (OTF2_Reader *reader)
	Open the events file container. More...

OTF2_ErrorCode	OTF2_Reader_CloseEvtFiles (OTF2_Reader *reader)
	Closes the events file container. More...

OTF2_ErrorCode	OTF2_Reader_OpenDefFiles (OTF2_Reader *reader)
	Open the local definitions file container. More...

OTF2_ErrorCode	OTF2_Reader_CloseDefFiles (OTF2_Reader *reader)
	Closes the local definitions file container. More...

OTF2_ErrorCode	OTF2_Reader_OpenSnapFiles (OTF2_Reader *reader)
	Open the snapshots file container. More...

OTF2_ErrorCode	OTF2_Reader_CloseSnapFiles (OTF2_Reader *reader)
	Closes the snapshots file container. More...

OTF2_ErrorCode	OTF2_Reader_SelectLocation (OTF2_Reader *reader, OTF2_LocationRef location)
	Select a location to be read. More...

OTF2_ErrorCode	OTF2_Reader_IsMaster (OTF2_Reader reader, bool result)
	Determines if this reader is the master object which handles the global archive state (anchor file, global definitions, marker, ...). More...

Detailed Description

Reading interface for OTF2 archives.

Function Documentation

OTF2_Reader* OTF2_Reader_Open ( const char * anchorFilePath )

Create a new reader handle.

Creates a new reader handle, opens an according archive handle, and calls a routine to register all necessary function pointers.

Parameters

anchorFilePath Path to the anchor file e.g. 'trace.otf2'. This can be a relative as well as an absolute path.

Returns: Returns a handle to the reader if successful, NULL otherwise.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_Close ( OTF2_Reader * reader )

Close a reader handle.

Closes a reader handle and releases all associated handles. Does nothing if NULL is provided.

Parameters

reader Reader handle.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_SetHint	(	OTF2_Reader *	reader,
		OTF2_Hint	hint,
		void *	value
	)

Set the hint in the reader to the given value.

Hints can only be set once and only before OTF2 itself uses the hint the first time.

Parameters

reader	Reader handle.
hint	Name of the hint.
value	Reference to the hint value.

Since: Version 1.5

Returns

OTF2_SUCCESS if successful^^

OTF2_ERROR_INVALID_ARGUMENT in case of NULL pointers for archive or value, or an unknown hint value^^

OTF2_ERROR_HINT_INVALID in case the hint is not valid for this handle^^

OTF2_ERROR_HINT_LOCKED in case the hint was already set or was queried at least once by the handle^^

OTF2_ERROR_HINT_INVALID_VALUE in case the provided value is invalid for this hint^^

^^

OTF2_ErrorCode OTF2_Reader_SetCollectiveCallbacks	(	OTF2_Reader *	reader,
		const OTF2_CollectiveCallbacks *	collectiveCallbacks,
		void *	collectiveData,
		OTF2_CollectiveContext *	globalCommContext,
		OTF2_CollectiveContext *	localCommContext
	)

Set the collective callbacks for the reader.

The reader has as the default the serial collectives set.

This function is a collective operation.

Parameters

reader	Reader handle.
collectiveCallbacks	Struct holding the collective callback functions.
collectiveData	Data passed to the collective callbacks in the `userData` argument.
globalCommContext	Global communication context.
localCommContext	Local communication context. Unused in reading mode. A local communication context may be created via the callbacks which fits the one used when the given trace was written.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_SetSerialCollectiveCallbacks ( OTF2_Reader * reader )

Convenient function to set the collective callbacks to a serial implementation.

Parameters

reader Reader handle.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_SetLockingCallbacks	(	OTF2_Reader *	reader,
		const OTF2_LockingCallbacks *	lockingCallbacks,
		void *	lockingData
	)

Set the locking callbacks for the reader.

Can be called any time, but only once. Before this call no thread-safety is guaranteed.

Parameters

reader	Reader handle.
lockingCallbacks	Struct holding the locking callback functions.
lockingData	Data passed to the locking callbacks in the `userData` argument.

Returns

OTF2_SUCCESS if successful^^

OTF2_ERROR_INVALID_ARGUMENT in case of NULL pointers for archive or lockingCallbacks, or mandatory callbacks in lockingCallbacks are missing^^

OTF2_ERROR_INVALID_CALL in case there were locking callbacks already set^^

^^

OTF2_ErrorCode OTF2_Reader_RegisterEvtCallbacks	(	OTF2_Reader *	reader,
		OTF2_EvtReader *	evtReader,
		const OTF2_EvtReaderCallbacks *	callbacks,
		void *	userData
	)

Register event reader callbacks.

Parameters

reader	OTF2_Reader handle.
evtReader	Local event reader handle.
callbacks	Callbacks for the event readers.
userData	Addition user data.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_RegisterGlobalEvtCallbacks	(	OTF2_Reader *	reader,
		OTF2_GlobalEvtReader *	evtReader,
		const OTF2_GlobalEvtReaderCallbacks *	callbacks,
		void *	userData
	)

Register global event reader callbacks.

Parameters

reader	OTF2_Reader handle.
evtReader	Global event reader handle.
callbacks	Callbacks for the global event reader.
userData	Addition user data.

Returns: Returns OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_RegisterDefCallbacks	(	OTF2_Reader *	reader,
		OTF2_DefReader *	defReader,
		const OTF2_DefReaderCallbacks *	callbacks,
		void *	userData
	)

Register local definition reader callbacks.

Parameters

reader	OTF2_Reader handle.
defReader	Local definition reader handle.
callbacks	Callbacks for the local definition readers.
userData	Addition user data.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_RegisterGlobalDefCallbacks	(	OTF2_Reader *	reader,
		OTF2_GlobalDefReader *	defReader,
		const OTF2_GlobalDefReaderCallbacks *	callbacks,
		void *	userData
	)

Register global definition reader callbacks.

Parameters

reader	OTF2_Reader handle.
defReader	Global definition reader handle.
callbacks	Callbacks for the global definition readers.
userData	Addition user data.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_RegisterSnapCallbacks	(	OTF2_Reader *	reader,
		OTF2_SnapReader *	snapReader,
		const OTF2_SnapReaderCallbacks *	callbacks,
		void *	userData
	)

Register snapshot event reader callbacks.

Parameters

reader	OTF2_Reader handle.
snapReader	Local snap reader handle.
callbacks	Callbacks for the event readers.
userData	Addition user data.

Since: Version 1.2

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_RegisterGlobalSnapCallbacks	(	OTF2_Reader *	reader,
		OTF2_GlobalSnapReader *	evtReader,
		const OTF2_GlobalSnapReaderCallbacks *	callbacks,
		void *	userData
	)

Register global event reader callbacks.

Parameters

reader	OTF2_Reader handle.
evtReader	Global event reader handle.
callbacks	Callbacks for the global event reader.
userData	Addition user data.

Since: Version 1.2

Returns: Returns OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_RegisterMarkerCallbacks	(	OTF2_Reader *	reader,
		OTF2_MarkerReader *	markerReader,
		const OTF2_MarkerReaderCallbacks *	callbacks,
		void *	userData
	)

Register marker reader callbacks.

Parameters

reader	OTF2_Reader handle.
markerReader	Marker reader handle.
callbacks	Callbacks for the marker reader.
userData	Addition user data.

Since: Version 1.2

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_ReadLocalEvents	(	OTF2_Reader *	reader,
		OTF2_EvtReader *	evtReader,
		uint64_t	eventsToRead,
		uint64_t *	eventsRead
	)

Read a given number of events via a local event reader.

Parameters

reader	Reader handle.
evtReader	Local event reader handle.
eventsToRead	Number events to be read.
eventsRead	Return pointer to the number of events actually read.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_ReadAllLocalEvents	(	OTF2_Reader *	reader,
		OTF2_EvtReader *	evtReader,
		uint64_t *	eventsRead
	)

Read all events via a local event reader.

Parameters

	reader	Reader handle.
	evtReader	Local event reader handle.
[out]	eventsRead	Return pointer to the number of events actually read.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_ReadLocalEventsBackward	(	OTF2_Reader *	reader,
		OTF2_EvtReader *	evtReader,
		uint64_t	eventsToRead,
		uint64_t *	eventsRead
	)

Read a given number of events via a local event reader backwards.

Parameters

	reader	Reader handle.
	evtReader	Local event reader handle.
	eventsToRead	Number events to be read.
[out]	eventsRead	Return pointer to the number of events actually read.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_ReadGlobalEvent	(	OTF2_Reader *	reader,
		OTF2_GlobalEvtReader *	evtReader
	)

Read an event via a global event reader.

Parameters

reader	Reader handle.
evtReader	Global event reader handle.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_HasGlobalEvent	(	OTF2_Reader *	reader,
		OTF2_GlobalEvtReader *	evtReader,
		int *	flag
	)

Has the global event reader at least one more event to deliver.

Parameters

	reader	Global event reader handle.
	evtReader	Global event reader handle.
[out]	flag	In case of success, the flag will be set to 1 when there is at least more more event to read. To 0 if not. Otherwise the value is undefined.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_ReadGlobalEvents	(	OTF2_Reader *	reader,
		OTF2_GlobalEvtReader *	evtReader,
		uint64_t	eventsToRead,
		uint64_t *	eventsRead
	)

Read a given number of events via a global event reader.

Parameters

	reader	Reader handle.
	evtReader	Global event reader handle.
	eventsToRead	Number events to be read.
[out]	eventsRead	Return pointer to the number of events actually read.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_ReadAllGlobalEvents	(	OTF2_Reader *	reader,
		OTF2_GlobalEvtReader *	evtReader,
		uint64_t *	eventsRead
	)

Read all events via a global event reader.

Parameters

	reader	Reader handle.
	evtReader	Global event reader handle.
[out]	eventsRead	Return pointer to the number of events actually read.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_ReadLocalDefinitions	(	OTF2_Reader *	reader,
		OTF2_DefReader *	defReader,
		uint64_t	definitionsToRead,
		uint64_t *	definitionsRead
	)

Read a given number of definitions via a local definition reader.

Parameters

	reader	Reader handle.
	defReader	Local definition reader handle.
	definitionsToRead	Number definitions to be read.
[out]	definitionsRead	Return pointer to the number of definitions actually read.

Returns

OTF2_SUCCESS if successful^^

OTF2_ERROR_INTERRUPTED_BY_CALLBACK if an user supplied callback returned OTF2_CALLBACK_INTERRUPT^^

OTF2_ERROR_DUPLICATE_MAPPING_TABLE if a duplicate mapping table definition was read^^

otherwisethe error code^^

^^

OTF2_ErrorCode OTF2_Reader_ReadAllLocalDefinitions	(	OTF2_Reader *	reader,
		OTF2_DefReader *	defReader,
		uint64_t *	definitionsRead
	)

Read all definitions via a local definition reader.

Parameters

	reader	Reader handle.
	defReader	Local definition reader handle.
[out]	definitionsRead	Return pointer to the number of definitions actually read.

Returns

OTF2_SUCCESS if successful^^

OTF2_ERROR_INTERRUPTED_BY_CALLBACK if an user supplied callback returned OTF2_CALLBACK_INTERRUPT^^

OTF2_ERROR_DUPLICATE_MAPPING_TABLE if a duplicate mapping table definition was read^^

otherwisethe error code^^

^^

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_ReadGlobalDefinitions	(	OTF2_Reader *	reader,
		OTF2_GlobalDefReader *	defReader,
		uint64_t	definitionsToRead,
		uint64_t *	definitionsRead
	)

Read a given number of definitions via a global definition reader.

Parameters

	reader	Reader handle.
	defReader	Global definition reader handle.
	definitionsToRead	Number definitions to be read.
[out]	definitionsRead	Return pointer to the number of definitions actually read.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_ReadAllGlobalDefinitions	(	OTF2_Reader *	reader,
		OTF2_GlobalDefReader *	defReader,
		uint64_t *	definitionsRead
	)

Read all definitions via a global definition reader.

Parameters

	reader	Reader handle.
	defReader	Global definition reader handle.
[out]	definitionsRead	Return pointer to the number of definitions actually read.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_ReadLocalSnapshots	(	OTF2_Reader *	reader,
		OTF2_SnapReader *	snapReader,
		uint64_t	recordsToRead,
		uint64_t *	recordsRead
	)

Read a given number of records via a local snapshot reader.

Parameters

reader	Reader handle.
snapReader	Local snapshot reader handle.
recordsToRead	Number records to be read.
recordsRead	Return pointer to the number of records actually read.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Since: Version 1.2

OTF2_ErrorCode OTF2_Reader_ReadAllLocalSnapshots	(	OTF2_Reader *	reader,
		OTF2_SnapReader *	snapReader,
		uint64_t *	recordsRead
	)

Read all records via a local snapshot reader.

Parameters

	reader	Reader handle.
	snapReader	Local snapshot reader handle.
[out]	recordsRead	Return pointer to the number of records

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Since: Version 1.2

OTF2_ErrorCode OTF2_Reader_ReadGlobalSnapshots	(	OTF2_Reader *	reader,
		OTF2_GlobalSnapReader *	snapReader,
		uint64_t	recordsToRead,
		uint64_t *	recordsRead
	)

Read a given number of records via a global snapshot reader.

Parameters

	reader	Reader handle.
	snapReader	Global snapshot reader handle.
	recordsToRead	Number records to be read.
[out]	recordsRead	Return pointer to the number of records actually read.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Since: Version 1.2

OTF2_ErrorCode OTF2_Reader_ReadAllGlobalSnapshots	(	OTF2_Reader *	reader,
		OTF2_GlobalSnapReader *	snapReader,
		uint64_t *	recordsRead
	)

Read all records via a global snapshot reader.

Parameters

	reader	Reader handle.
	snapReader	Global snapshot reader handle.
[out]	recordsRead	Return pointer to the number of records

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Since: Version 1.2

OTF2_ErrorCode OTF2_Reader_ReadMarkers	(	OTF2_Reader *	reader,
		OTF2_MarkerReader *	markerReader,
		uint64_t	markersToRead,
		uint64_t *	markersRead
	)

Read a given number of markers via a marker reader.

Parameters

	reader	Reader handle.
	markerReader	Marker reader handle.
	markersToRead	Number markers to be read.
[out]	markersRead	Return pointer to the number of markers actually read.

Since: Version 1.2

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_ReadAllMarkers	(	OTF2_Reader *	reader,
		OTF2_MarkerReader *	markerReader,
		uint64_t *	markersRead
	)

Read all markers via a marker reader.

Parameters

	reader	Reader handle.
	markerReader	Marker reader handle.
[out]	markersRead	Return pointer to the number of markers actually read.

Since: Version 1.2

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_EvtReader* OTF2_Reader_GetEvtReader	(	OTF2_Reader *	reader,
		OTF2_LocationRef	location
	)

Get a local event reader.

Parameters

reader	Valid reader handle.
location	Location ID for the requested local reader.

Returns: Returns a handle to the local event reader if successful, NULL otherwise.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_GlobalEvtReader* OTF2_Reader_GetGlobalEvtReader ( OTF2_Reader * reader )

Get a global event reader.

Parameters

reader Valid reader handle.

Returns: Returns a handle to the global event reader if successful, NULL otherwise.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_DefReader* OTF2_Reader_GetDefReader	(	OTF2_Reader *	reader,
		OTF2_LocationRef	location
	)

Get a local definition reader.

Parameters

reader	Valid reader handle.
location	Location ID for the requested local reader.

Returns: Returns a handle to the local definition reader if successful, NULL otherwise.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_GlobalDefReader* OTF2_Reader_GetGlobalDefReader ( OTF2_Reader * reader )

Get a global definition reader.

Parameters

reader Valid reader handle.

Returns: Returns a handle to the global definition reader if successful, NULL otherwise.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_SnapReader* OTF2_Reader_GetSnapReader	(	OTF2_Reader *	reader,
		OTF2_LocationRef	location
	)

Get a local snapshot reader.

Parameters

reader	Valid reader handle.
location	Location ID for the requested local reader.

Returns: Returns a handle to the local event reader if successful, NULL otherwise.

Since: Version 1.2

OTF2_GlobalSnapReader* OTF2_Reader_GetGlobalSnapReader ( OTF2_Reader * reader )

Get a global snap reader.

Parameters

reader Valid reader handle.

Returns: Returns a handle to the global snap reader if successful, NULL otherwise.

Since: Version 1.2

OTF2_ThumbReader* OTF2_Reader_GetThumbReader	(	OTF2_Reader *	reader,
		uint32_t	number
	)

Get a thumb reader.

Parameters

reader	Reader handle.
number	Thumbnail number.

Since: Version 1.2

Returns: Returns a global definition writer handle if successful, NULL if an error occurs.

OTF2_MarkerReader* OTF2_Reader_GetMarkerReader ( OTF2_Reader * reader )

Get a marker reader.

Parameters

reader Valid reader handle.

Since: Version 1.2

Returns: Returns a handle to the marker reader if successful, NULL otherwise.

OTF2_MarkerWriter* OTF2_Reader_GetMarkerWriter ( OTF2_Reader * reader )

Get a marker writer.

Parameters

reader Valid reader handle.

Since: Version 1.2

Returns: Returns a handle to the marker writer if successful, NULL otherwise.

OTF2_ErrorCode OTF2_Reader_CloseEvtReader	(	OTF2_Reader *	reader,
		OTF2_EvtReader *	evtReader
	)

Close a local event reader.

Parameters

reader	Valid reader handle.
evtReader	Event reader to be closed.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_CloseGlobalEvtReader	(	OTF2_Reader *	reader,
		OTF2_GlobalEvtReader *	globalEvtReader
	)

Closes the global event reader.

This closes also all local event readers.

Parameters

reader	Valid reader handle.
globalEvtReader	The global event reader.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_CloseDefReader	(	OTF2_Reader *	reader,
		OTF2_DefReader *	defReader
	)

Close a local definition reader.

Parameters

reader	Valid reader handle.
defReader	Definition reader to be closed.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_CloseGlobalDefReader	(	OTF2_Reader *	reader,
		OTF2_GlobalDefReader *	globalDefReader
	)

Closes the global definition reader.

Parameters

reader	Valid reader handle.
globalDefReader	The global definition reader.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_CloseSnapReader	(	OTF2_Reader *	reader,
		OTF2_SnapReader *	snapReader
	)

Close a local snapshot reader.

Parameters

reader	Valid reader handle.
snapReader	snapshot reader to be closed.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Since: Version 1.2

OTF2_ErrorCode OTF2_Reader_CloseGlobalSnapReader	(	OTF2_Reader *	reader,
		OTF2_GlobalSnapReader *	globalSnapReader
	)

Closes the global snapshot reader.

Parameters

reader	Valid reader handle.
globalSnapReader	The global snapshot reader.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Since: Version 1.2

OTF2_ErrorCode OTF2_Reader_CloseThumbReader	(	OTF2_Reader *	reader,
		OTF2_ThumbReader *	thumbReader
	)

Close an opened thumbnail reader.

Parameters

reader	Reader handle.
thumbReader	Thumbnail reader handle to be closed.

Since: Version 1.2

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_CloseMarkerReader	(	OTF2_Reader *	reader,
		OTF2_MarkerReader *	markerReader
	)

Closes the marker reader.

Parameters

reader	Valid reader handle.
markerReader	The marker reader.

Since: Version 1.2

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_CloseMarkerWriter	(	OTF2_Reader *	reader,
		OTF2_MarkerWriter *	markerWriter
	)

Closes the marker writer.

Parameters

reader	Valid reader handle.
markerWriter	The marker writer.

Since: Version 1.2

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_GetVersion	(	OTF2_Reader *	reader,
		uint8_t *	major,
		uint8_t *	minor,
		uint8_t *	bugfix
	)

Get OTF2 version.

Parameters

	reader	Valid reader handle.
[out]	major	Major version.
[out]	minor	Minor version.
[out]	bugfix	Bugfix revision.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_GetChunkSize	(	OTF2_Reader *	reader,
		uint64_t *	chunkSizeEvents,
		uint64_t *	chunkSizeDefinitions
	)

Get event and definition chunk sizes.

Parameters

	reader	Reader handle.
[out]	chunkSizeEvents	Returned size of event chunks
[out]	chunkSizeDefinitions	Returned size of definition chunks.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_GetFileSubstrate	(	OTF2_Reader *	reader,
		OTF2_FileSubstrate *	substrate
	)

Get file substrate information.

Parameters

	reader	Reader handle.
[out]	substrate	Returned file substrate.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_GetCompression	(	OTF2_Reader *	reader,
		OTF2_Compression *	compression
	)

Get compression mode.

Parameters

	reader	Reader handle.
[out]	compression	Returned compression mode.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_GetNumberOfLocations	(	OTF2_Reader *	reader,
		uint64_t *	numberOfLocations
	)

Get number of locations.

Parameters

	reader	Reader handle.
[out]	numberOfLocations	Returned number of locations.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_GetNumberOfGlobalDefinitions	(	OTF2_Reader *	reader,
		uint64_t *	numberOfDefinitions
	)

Get number of global definitions.

Parameters

	reader	Reader handle.
[out]	numberOfDefinitions	Returned number of global definitions.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_GetMachineName	(	OTF2_Reader *	reader,
		char **	machineName
	)

Get machine name.

Parameters

	reader	Reader handle.
[out]	machineName	Returned machine name. Allocated with malloc.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_GetCreator	(	OTF2_Reader *	reader,
		char **	creator
	)

Get creator name.

Parameters

	reader	Reader handle.
[out]	creator	Returned creator. Allocated with malloc.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_GetDescription	(	OTF2_Reader *	reader,
		char **	description
	)

Get description.

Parameters

	reader	Reader handle.
[out]	description	Returned description. Allocated with malloc.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_GetPropertyNames	(	OTF2_Reader *	reader,
		uint32_t *	numberOfProperties,
		char ***	names
	)

Get the names of all trace file properties.

Parameters

	reader	Reader handle.
[out]	numberOfProperties	Returned number of trace file properties.
[out]	names	Returned list of property names. Allocated with malloc. To release memory, just pass `names` to free*.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_GetProperty	(	OTF2_Reader *	reader,
		const char *	name,
		char **	value
	)

Get the value of the named trace file property.

Parameters

	reader	Reader handle.
	name	Name of the property.
[out]	value	Returned value of the property. Allocated with malloc.

Returns

OTF2_SUCCESS if successful^^

OTF2_ERROR_PROPERTY_NOT_FOUND if the named property was not found^^

^^

OTF2_ErrorCode OTF2_Reader_GetBoolProperty	(	OTF2_Reader *	reader,
		const char *	name,
		bool *	value
	)

Get the value of the named trace file property as boolean.

Parameters

	reader	Reader handle.
	name	Name of the property.
[out]	value	Returned boolean value of the property.

Returns

OTF2_SUCCESS if successful^^

OTF2_ERROR_PROPERTY_NOT_FOUND if the named property was not found^^

OTF2_ERROR_PROPERTY_VALUE_INVALID if the value could not be interpreted as a boolean value^^

^^

OTF2_ErrorCode OTF2_Reader_GetTraceId	(	OTF2_Reader *	reader,
		uint64_t *	id
	)

Get the identifier of the trace file.

Parameters

	reader	Reader handle.
[out]	id	Trace identifier.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_GetNumberOfSnapshots	(	OTF2_Reader *	reader,
		uint32_t *	number
	)

Get number of snapshots.

Parameters

	reader	Reader handle.
[out]	number	Returned number of snapshots.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Since: Version 1.2

OTF2_ErrorCode OTF2_Reader_GetNumberOfThumbnails	(	OTF2_Reader *	reader,
		uint32_t *	number
	)

Get number of thumbs.

Parameters

	reader	Reader handle.
[out]	number	Returned number of thumbs.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Since: Version 1.2

OTF2_ErrorCode OTF2_Reader_OpenEvtFiles ( OTF2_Reader * reader )

Open the events file container.

This function is a collective operation.

Parameters

reader Reader handle.

Since: Version 1.3

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_CloseEvtFiles ( OTF2_Reader * reader )

Closes the events file container.

All previously used event readers must be closed before this call.

This function is a collective operation.

Parameters

reader Reader handle.

Since: Version 1.3

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_OpenDefFiles ( OTF2_Reader * reader )

Open the local definitions file container.

This function is a collective operation.

Parameters

reader Reader handle.

Since: Version 1.3

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_CloseDefFiles ( OTF2_Reader * reader )

Closes the local definitions file container.

This function is a collective operation.

All previously used local definition readers must be closed before this call.

Parameters

reader Reader handle.

Since: Version 1.3

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_OpenSnapFiles ( OTF2_Reader * reader )

Open the snapshots file container.

This function is a collective operation.

Parameters

reader Reader handle.

Since: Version 1.3

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_CloseSnapFiles ( OTF2_Reader * reader )

Closes the snapshots file container.

This function is a collective operation.

All previously used snapshot readers must be closed before this call.

Parameters

reader Reader handle.

Since: Version 1.3

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

OTF2_ErrorCode OTF2_Reader_SelectLocation	(	OTF2_Reader *	reader,
		OTF2_LocationRef	location
	)

Select a location to be read.

Parameters

reader	Reader handle.
location	Location ID.

Since: Version 1.3

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Examples:: otf2_mpi_reader_example.c, otf2_mpi_reader_example.cc, and otf2_reader_example.c.

OTF2_ErrorCode OTF2_Reader_IsMaster	(	OTF2_Reader *	reader,
		bool *	result
	)

Determines if this reader is the master object which handles the global archive state (anchor file, global definitions, marker, ...).

Parameters

	reader	Reader handle.
[out]	result	Storage for the result.

Returns: OTF2_SUCCESS if successful, an error code if an error occurs.

Typedefs

Functions

Detailed Description

Function Documentation