3.1-rc3 (revision d9ca08bb)
Macros | Typedefs | Functions
OTF2_Archive.h File Reference

Writing interface for OTF2 archives. More...

#include <stdint.h>
#include "otf2_compiler.h"
#include <otf2/OTF2_ErrorCodes.h>
#include <otf2/OTF2_Callbacks.h>
#include <otf2/OTF2_DefWriter.h>
#include <otf2/OTF2_DefReader.h>
#include <otf2/OTF2_EvtWriter.h>
#include <otf2/OTF2_EvtReader.h>
#include <otf2/OTF2_SnapWriter.h>
#include <otf2/OTF2_SnapReader.h>
#include <otf2/OTF2_GlobalDefWriter.h>
#include <otf2/OTF2_GlobalDefReader.h>
#include <otf2/OTF2_GlobalEvtReader.h>
#include <otf2/OTF2_GlobalSnapReader.h>
#include <otf2/OTF2_Thumbnail.h>
#include <otf2/OTF2_MarkerWriter.h>
#include <otf2/OTF2_MarkerReader.h>

Go to the source code of this file.

Macros

#define OTF2_CHUNK_SIZE_EVENTS_DEFAULT   ( 1024 * 1024 )
 Default size for OTF2's internal event chunk memory handling. More...
 
#define OTF2_CHUNK_SIZE_DEFINITIONS_DEFAULT   ( 4 * 1024 * 1024 )
 Default size for OTF2's internal event chunk memory handling. More...
 

Typedefs

typedef struct OTF2_Archive_struct OTF2_Archive
 Keeps all meta-data for an OTF2 archive. More...
 

Functions

OTF2_ArchiveOTF2_Archive_Open (const char *archivePath, const char *archiveName, const OTF2_FileMode fileMode, const uint64_t chunkSizeEvents, const uint64_t chunkSizeDefs, const OTF2_FileSubstrate fileSubstrate, const OTF2_Compression compression)
 Create a new archive. More...
 
OTF2_ErrorCode OTF2_Archive_Close (OTF2_Archive *archive)
 Close an opened archive. More...
 
OTF2_ErrorCode OTF2_Archive_SwitchFileMode (OTF2_Archive *archive, OTF2_FileMode newFileMode)
 Switch file mode of the archive. More...
 
OTF2_ErrorCode OTF2_Archive_SetDefChunkSize (OTF2_Archive *archive, uint64_t chunkSize)
 Set the definition chunksize. More...
 
OTF2_ErrorCode OTF2_Archive_SetMachineName (OTF2_Archive *archive, const char *machineName)
 Set machine name. More...
 
OTF2_ErrorCode OTF2_Archive_SetDescription (OTF2_Archive *archive, const char *description)
 Set a description. More...
 
OTF2_ErrorCode OTF2_Archive_SetCreator (OTF2_Archive *archive, const char *creator)
 Set creator. More...
 
OTF2_ErrorCode OTF2_Archive_SetFlushCallbacks (OTF2_Archive *archive, const OTF2_FlushCallbacks *flushCallbacks, void *flushData)
 Set the flush callbacks for the archive. More...
 
OTF2_ErrorCode OTF2_Archive_SetMemoryCallbacks (OTF2_Archive *archive, const OTF2_MemoryCallbacks *memoryCallbacks, void *memoryData)
 Set the memory callbacks for the archive. More...
 
OTF2_ErrorCode OTF2_Archive_SetCollectiveCallbacks (OTF2_Archive *archive, const OTF2_CollectiveCallbacks *collectiveCallbacks, void *collectiveData, OTF2_CollectiveContext *globalCommContext, OTF2_CollectiveContext *localCommContext)
 Set the collective callbacks for the archive. More...
 
OTF2_ErrorCode OTF2_Archive_SetSerialCollectiveCallbacks (OTF2_Archive *archive)
 Convenient function to set the collective callbacks to an serial implementation. More...
 
OTF2_ErrorCode OTF2_Archive_IsPrimary (OTF2_Archive *archive, bool *result)
 Determines if this archive is the primary archive which handles the global archive state (anchor file, global definitions, marker, ...). More...
 
OTF2_ErrorCode OTF2_Archive_IsMaster (OTF2_Archive *archive, bool *result)
 Same as OTF2_Archive_IsPrimary. More...
 
OTF2_ErrorCode OTF2_Archive_SetLockingCallbacks (OTF2_Archive *archive, const OTF2_LockingCallbacks *lockingCallbacks, void *lockingData)
 Set the locking callbacks for the archive. More...
 
OTF2_ErrorCode OTF2_Archive_SetHint (OTF2_Archive *archive, OTF2_Hint hint, void *value)
 Set the hint in the archive to the given value. More...
 
OTF2_ErrorCode OTF2_Archive_SetProperty (OTF2_Archive *archive, const char *name, const char *value, bool overwrite)
 Add or remove a trace file property to this archive. More...
 
OTF2_ErrorCode OTF2_Archive_SetBoolProperty (OTF2_Archive *archive, const char *name, bool value, bool overwrite)
 Add or remove a boolean trace file property to this archive. More...
 
OTF2_ErrorCode OTF2_Archive_GetPropertyNames (OTF2_Archive *archive, uint32_t *numberOfProperties, char ***names)
 Get the names of all trace file properties. More...
 
OTF2_ErrorCode OTF2_Archive_GetProperty (OTF2_Archive *archive, const char *name, char **value)
 Get the value of the named trace file property. More...
 
OTF2_ErrorCode OTF2_Archive_GetTraceId (OTF2_Archive *archive, uint64_t *id)
 Get the identifier of the trace file. More...
 
OTF2_ErrorCode OTF2_Archive_GetNumberOfLocations (OTF2_Archive *archive, uint64_t *numberOfLocations)
 Get the number of locations. More...
 
OTF2_ErrorCode OTF2_Archive_GetNumberOfGlobalDefinitions (OTF2_Archive *archive, uint64_t *numberOfDefinitions)
 Get the number of global definitions. More...
 
OTF2_ErrorCode OTF2_Archive_GetMachineName (OTF2_Archive *archive, char **machineName)
 Get machine name. More...
 
OTF2_ErrorCode OTF2_Archive_GetDescription (OTF2_Archive *archive, char **description)
 Get description. More...
 
OTF2_ErrorCode OTF2_Archive_GetCreator (OTF2_Archive *archive, char **creator)
 Get creator information. More...
 
OTF2_ErrorCode OTF2_Archive_GetVersion (OTF2_Archive *archive, uint8_t *major, uint8_t *minor, uint8_t *bugfix)
 Get format version. More...
 
OTF2_ErrorCode OTF2_Archive_GetChunkSize (OTF2_Archive *archive, uint64_t *chunkSizeEvents, uint64_t *chunkSizeDefs)
 Get the chunksize. More...
 
OTF2_ErrorCode OTF2_Archive_GetFileSubstrate (OTF2_Archive *archive, OTF2_FileSubstrate *substrate)
 Get the file substrate (posix, sion, none) More...
 
OTF2_ErrorCode OTF2_Archive_GetCompression (OTF2_Archive *archive, OTF2_Compression *compression)
 Get compression mode (none or zlib) More...
 
OTF2_EvtWriterOTF2_Archive_GetEvtWriter (OTF2_Archive *archive, OTF2_LocationRef location)
 Get a local event writer. More...
 
OTF2_DefWriterOTF2_Archive_GetDefWriter (OTF2_Archive *archive, OTF2_LocationRef location)
 Get a local definition writer. More...
 
OTF2_GlobalDefWriterOTF2_Archive_GetGlobalDefWriter (OTF2_Archive *archive)
 Get a global definition writer. More...
 
OTF2_SnapWriterOTF2_Archive_GetSnapWriter (OTF2_Archive *archive, OTF2_LocationRef location)
 Get a local snap writer. More...
 
OTF2_ThumbWriterOTF2_Archive_GetThumbWriter (OTF2_Archive *archive, const char *name, const char *description, OTF2_ThumbnailType type, uint32_t numberOfSamples, uint32_t numberOfMetrics, const uint64_t *refsToDefs)
 Get a thumb writer. More...
 
OTF2_MarkerWriterOTF2_Archive_GetMarkerWriter (OTF2_Archive *archive)
 Get a marker writer. More...
 
OTF2_EvtReaderOTF2_Archive_GetEvtReader (OTF2_Archive *archive, OTF2_LocationRef location)
 Get a local event reader. More...
 
OTF2_GlobalEvtReaderOTF2_Archive_GetGlobalEvtReader (OTF2_Archive *archive)
 Get a global event reader. More...
 
OTF2_DefReaderOTF2_Archive_GetDefReader (OTF2_Archive *archive, OTF2_LocationRef location)
 Get a local definition reader. More...
 
OTF2_GlobalDefReaderOTF2_Archive_GetGlobalDefReader (OTF2_Archive *archive)
 Get a global definition reader. More...
 
OTF2_SnapReaderOTF2_Archive_GetSnapReader (OTF2_Archive *archive, OTF2_LocationRef location)
 Get a local snap reader. More...
 
OTF2_GlobalSnapReaderOTF2_Archive_GetGlobalSnapReader (OTF2_Archive *archive)
 Get a global snap reader. More...
 
OTF2_ThumbReaderOTF2_Archive_GetThumbReader (OTF2_Archive *archive, uint32_t number)
 Get a thumb reader. More...
 
OTF2_MarkerReaderOTF2_Archive_GetMarkerReader (OTF2_Archive *archive)
 Get a marker reader. More...
 
OTF2_ErrorCode OTF2_Archive_CloseEvtWriter (OTF2_Archive *archive, OTF2_EvtWriter *writer)
 Close an opened local event writer. More...
 
OTF2_ErrorCode OTF2_Archive_CloseDefWriter (OTF2_Archive *archive, OTF2_DefWriter *writer)
 Close an opened local definition writer. More...
 
OTF2_ErrorCode OTF2_Archive_CloseMarkerWriter (OTF2_Archive *archive, OTF2_MarkerWriter *writer)
 Close an opened marker writer. More...
 
OTF2_ErrorCode OTF2_Archive_CloseSnapWriter (OTF2_Archive *archive, OTF2_SnapWriter *writer)
 Close an opened local snap writer. More...
 
OTF2_ErrorCode OTF2_Archive_CloseGlobalDefWriter (OTF2_Archive *archive, OTF2_GlobalDefWriter *writer)
 Close an opened global definition writer. More...
 
OTF2_ErrorCode OTF2_Archive_CloseEvtReader (OTF2_Archive *archive, OTF2_EvtReader *reader)
 Close an opened local event reader. More...
 
OTF2_ErrorCode OTF2_Archive_CloseThumbReader (OTF2_Archive *archive, OTF2_ThumbReader *reader)
 Close an opened thumbnail reader. More...
 
OTF2_ErrorCode OTF2_Archive_CloseGlobalEvtReader (OTF2_Archive *archive, OTF2_GlobalEvtReader *globalEvtReader)
 Closes the global event reader. More...
 
OTF2_ErrorCode OTF2_Archive_CloseDefReader (OTF2_Archive *archive, OTF2_DefReader *reader)
 Close an opened local definition reader. More...
 
OTF2_ErrorCode OTF2_Archive_CloseGlobalDefReader (OTF2_Archive *archive, OTF2_GlobalDefReader *globalDefReader)
 Closes the global definition reader. More...
 
OTF2_ErrorCode OTF2_Archive_CloseSnapReader (OTF2_Archive *archive, OTF2_SnapReader *reader)
 Close an opened local snap reader. More...
 
OTF2_ErrorCode OTF2_Archive_CloseGlobalSnapReader (OTF2_Archive *archive, OTF2_GlobalSnapReader *globalSnapReader)
 Close the opened global snapshot reader. More...
 
OTF2_ErrorCode OTF2_Archive_CloseMarkerReader (OTF2_Archive *archive, OTF2_MarkerReader *markerReader)
 Closes the marker reader. More...
 
OTF2_ErrorCode OTF2_Archive_GetNumberOfThumbnails (OTF2_Archive *archive, uint32_t *number)
 Get the number of thumbnails. More...
 
OTF2_ErrorCode OTF2_Archive_SetNumberOfSnapshots (OTF2_Archive *archive, uint32_t number)
 Set the number of snapshots. More...
 
OTF2_ErrorCode OTF2_Archive_GetNumberOfSnapshots (OTF2_Archive *archive, uint32_t *number)
 Get the number of snapshots. More...
 
OTF2_ErrorCode OTF2_Archive_OpenEvtFiles (OTF2_Archive *archive)
 Open the events file container. More...
 
OTF2_ErrorCode OTF2_Archive_CloseEvtFiles (OTF2_Archive *archive)
 Closes the events file container. More...
 
OTF2_ErrorCode OTF2_Archive_OpenDefFiles (OTF2_Archive *archive)
 Open the local definitions file container. More...
 
OTF2_ErrorCode OTF2_Archive_CloseDefFiles (OTF2_Archive *archive)
 Closes the local definitions file container. More...
 
OTF2_ErrorCode OTF2_Archive_OpenSnapFiles (OTF2_Archive *archive)
 Open the snapshots file container. More...
 
OTF2_ErrorCode OTF2_Archive_CloseSnapFiles (OTF2_Archive *archive)
 Closes the snapshots file container. More...
 
OTF2_ErrorCode OTF2_Archive_SelectLocation (OTF2_Archive *archive, OTF2_LocationRef location)
 Select a location to be read. More...
 

Detailed Description

Writing interface for OTF2 archives.

Macro Definition Documentation

#define OTF2_CHUNK_SIZE_EVENTS_DEFAULT   ( 1024 * 1024 )

Default size for OTF2's internal event chunk memory handling.

If you are not sure which chunk size is the best to use, use this default value.

#define OTF2_CHUNK_SIZE_DEFINITIONS_DEFAULT   ( 4 * 1024 * 1024 )

Default size for OTF2's internal event chunk memory handling.

If you are not sure which chunk size is the best to use, use this default value.

Typedef Documentation

typedef struct OTF2_Archive_struct OTF2_Archive

Keeps all meta-data for an OTF2 archive.

An OTF2 archive handle keeps all runtime information about an OTF2 archive. It is the central handle to get and set information about the archive and to request event and definition writer handles.

Function Documentation

OTF2_Archive* OTF2_Archive_Open ( const char *  archivePath,
const char *  archiveName,
const OTF2_FileMode  fileMode,
const uint64_t  chunkSizeEvents,
const uint64_t  chunkSizeDefs,
const OTF2_FileSubstrate  fileSubstrate,
const OTF2_Compression  compression 
)

Create a new archive.

Creates a new archive handle that keeps all meta data about the archive on runtime.

Parameters
archivePathPath to the archive i.e. the directory where the anchor file is located.
archiveNameName of the archive. It is used to generate sub paths e.g. 'archiveName.otf2'.
fileModeDetermines if in reading or writing mode. Available values are OTF2_FILEMODE_WRITE or OTF2_FILEMODE_READ.
chunkSizeEventsRequested size of OTF2's internal event chunks in writing mode. Available values are from 256kB to 16MB. The event chunk size affects performance as well as total memory usage. A value satisfying both is about 1MB. If you are not sure which chunk size is the best to use, use OTF2_CHUNK_SIZE_EVENTS_DEFAULT. In reading mode this value is ignored because the correct chunk size is extracted from the anchor file.
chunkSizeDefsRequested size of OTF2's internal definition chunks in writing mode. Available values are from 256kB to 16MB. The definition chunk size affects performance as well as total memory usage. In addition, the definition chunk size must be big enough to carry the largest possible definition record. Therefore, the definition chunk size must be at least 10 times the number of locations. A value satisfying these requirements is about 4MB. If you are not sure which chunk size is the best to use, use OTF2_CHUNK_SIZE_DEFINITIONS_DEFAULT. In reading mode this value is ignored because the correct chunk size is extracted from the anchor file.
fileSubstrateDetermines which file substrate should be used in writing mode. Available values are OTF2_SUBSTRATE_POSIX to use the standard Posix interface, OTF2_SUBSTRATE_SION to use an installed SION library to store multiple logical files into fewer or one physical file, and OTF2_SUBSTRATE_NONE to suppress file writing at all. In reading mode this value is ignored because the correct file substrate is extracted from the anchor file.
compressionDetermines if compression is used to reduce the size of data in files. Available values are OTF2_COMPRESSION_ZLIB to use an installed zlib and OTF2_COMPRESSION_NONE to disable compression. In reading mode this value is ignored because the correct file compression is extracted from the anchor file.
Returns
Returns an archive handle if successful, NULL otherwise.
Examples:
otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_ErrorCode OTF2_Archive_Close ( OTF2_Archive archive)

Close an opened archive.

Closes an opened archive and releases the associated resources. Closes also all opened writer and reader handles. Does nothing if NULL is passed.

Parameters
archiveArchive handle.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_ErrorCode OTF2_Archive_SwitchFileMode ( OTF2_Archive archive,
OTF2_FileMode  newFileMode 
)

Switch file mode of the archive.

Currently only a switch from OTF2_FILEMODE_READ to OTF2_FILEMODE_WRITE is permitted. Currently it is also only permitted when operating on an OTF2 archive with the OTF2_SUBSTRATE_POSIX file substrate.

Parameters
archiveArchive handle.
newFileModeNew OTF2_FileMode to switch to.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
Since
Version 1.2
OTF2_ErrorCode OTF2_Archive_SetDefChunkSize ( OTF2_Archive archive,
uint64_t  chunkSize 
)

Set the definition chunksize.

This maybe called for archives in the OTF2_FILEMODE_WRITE mode and with an initial value of OTF2_UNDEFINED_UINT64 for the definition chunksize when opening the archive, but before requesting any local or global definition, or marker writer.

This function is a collective operation. The actual value is taken from the primary archive. The chunkSize argument on non-primary archives must be OTF2_UNDEFINED_UINT64.

Parameters
archiveArchive handle.
chunkSizeChunk size for definition files.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_SetMachineName ( OTF2_Archive archive,
const char *  machineName 
)

Set machine name.

Sets the name for the machine the trace was recorded. This value is optional. When there is a primary archive, only the value provided for the primary archive will be used.

Parameters
archiveArchive handle.
machineNameMachine name.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_SetDescription ( OTF2_Archive archive,
const char *  description 
)

Set a description.

Sets a description for a trace archive. This value is optional. When there is a primary archive, only the value provided for the primary archive will be used.

Parameters
archiveArchive handle.
descriptionDescription.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_SetCreator ( OTF2_Archive archive,
const char *  creator 
)

Set creator.

Sets information about the creator of the trace archive. This value is optional. When there is a primary archive, only the value provided for the primary archive will be used.

Parameters
archiveArchive handle.
creatorCreator information.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_SetFlushCallbacks ( OTF2_Archive archive,
const OTF2_FlushCallbacks flushCallbacks,
void *  flushData 
)

Set the flush callbacks for the archive.

Parameters
archiveArchive handle.
flushCallbacksStruct holding the flush callback functions.
flushDataData passed to the flush callbacks in the userData argument.
Returns
OTF2_ErrorCode, or error code.
Examples:
otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_ErrorCode OTF2_Archive_SetMemoryCallbacks ( OTF2_Archive archive,
const OTF2_MemoryCallbacks memoryCallbacks,
void *  memoryData 
)

Set the memory callbacks for the archive.

Parameters
archiveArchive handle.
memoryCallbacksStruct holding the memory callback functions.
memoryDataData passed to the memory callbacks in the userData argument.
Returns
OTF2_ErrorCode, or error code.
OTF2_ErrorCode OTF2_Archive_SetCollectiveCallbacks ( OTF2_Archive archive,
const OTF2_CollectiveCallbacks collectiveCallbacks,
void *  collectiveData,
OTF2_CollectiveContext globalCommContext,
OTF2_CollectiveContext localCommContext 
)

Set the collective callbacks for the archive.

This function is a collective operation.

Parameters
archiveArchive handle.
collectiveCallbacksStruct holding the collective callback functions.
collectiveDataData passed to the collective callbacks in the userData argument.
globalCommContextGlobal communication context.
localCommContextLocal communication context.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_SetSerialCollectiveCallbacks ( OTF2_Archive archive)

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

Parameters
archiveArchive handle.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_ErrorCode OTF2_Archive_IsPrimary ( OTF2_Archive archive,
bool *  result 
)

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

Parameters
archiveArchive handle.
[out]resultStorage for the result.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_IsMaster ( OTF2_Archive archive,
bool *  result 
)

Same as OTF2_Archive_IsPrimary.

Parameters
archiveArchive handle.
[out]resultStorage for the result.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
Deprecated:
In version 3.0
OTF2_ErrorCode OTF2_Archive_SetLockingCallbacks ( OTF2_Archive archive,
const OTF2_LockingCallbacks lockingCallbacks,
void *  lockingData 
)

Set the locking callbacks for the archive.

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

Parameters
archiveArchive handle.
lockingCallbacksStruct holding the locking callback functions.
lockingDataData 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_Archive_SetHint ( OTF2_Archive archive,
OTF2_Hint  hint,
void *  value 
)

Set the hint in the archive to the given value.

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

Parameters
archiveArchive handle.
hintName of the hint.
valueReference 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_Archive_SetProperty ( OTF2_Archive archive,
const char *  name,
const char *  value,
bool  overwrite 
)

Add or remove a trace file property to this archive.

Removing a trace file property is done by passing "" in the value parameter. The overwrite parameter is ignored than.

Note
This call is only allowed when the archive was opened with mode OTF2_FILEMODE_WRITE.
Parameters
archiveArchive handle.
nameName of the trace file property (case insensitive, [A-Z0-9_]).
valueValue of property.
overwriteIf true a previous trace file property with the same name name will be overwritten.
Returns
OTF2_SUCCESS
if successful
OTF2_ERROR_PROPERTY_NAME_INVALID
if property name does not conform to the naming scheme
OTF2_ERROR_PROPERTY_NOT_FOUND
if property was not found, but requested to remove
OTF2_ERROR_PROPERTY_EXISTS
if property exists but overwrite was not set
OTF2_ErrorCode OTF2_Archive_SetBoolProperty ( OTF2_Archive archive,
const char *  name,
bool  value,
bool  overwrite 
)

Add or remove a boolean trace file property to this archive.

Note
This call is only allowed when the archive was opened with mode OTF2_FILEMODE_WRITE.
Parameters
archiveArchive handle.
nameName of the trace file property (case insensitive, [A-Z0-9_]).
valueBoolean value of property (e.g. true or false).
overwriteIf true a previous trace file property with the same name name will be overwritten.
Returns
OTF2_SUCCESS
if successful
OTF2_ERROR_PROPERTY_NAME_INVALID
if property name does not conform to the naming scheme
OTF2_ERROR_PROPERTY_NOT_FOUND
if property was not found, but requested to remove
OTF2_ERROR_PROPERTY_EXISTS
if property exists but overwrite was not set
OTF2_ErrorCode OTF2_Archive_GetPropertyNames ( OTF2_Archive archive,
uint32_t *  numberOfProperties,
char ***  names 
)

Get the names of all trace file properties.

Parameters
archiveArchive handle.
[out]numberOfPropertiesReturned number of trace file properties.
[out]namesReturned 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_Archive_GetProperty ( OTF2_Archive archive,
const char *  name,
char **  value 
)

Get the value of the named trace file property.

Parameters
archiveArchive handle.
nameName of the property.
[out]valueReturned 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_Archive_GetTraceId ( OTF2_Archive archive,
uint64_t *  id 
)

Get the identifier of the trace file.

Note
This call is only allowed when the archive was opened with mode OTF2_FILEMODE_READ.
Parameters
archiveArchive handle.
[out]idTrace identifier.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_GetNumberOfLocations ( OTF2_Archive archive,
uint64_t *  numberOfLocations 
)

Get the number of locations.

Parameters
archiveArchive handle.
[out]numberOfLocationsReturn pointer to the number of locations.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_GetNumberOfGlobalDefinitions ( OTF2_Archive archive,
uint64_t *  numberOfDefinitions 
)

Get the number of global definitions.

Parameters
archiveArchive handle.
[out]numberOfDefinitionsReturn pointer to the number of global definitions.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_GetMachineName ( OTF2_Archive archive,
char **  machineName 
)

Get machine name.

Parameters
archiveArchive handle.
[out]machineNameReturned machine name. Allocated with malloc.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_GetDescription ( OTF2_Archive archive,
char **  description 
)

Get description.

Parameters
archiveArchive handle.
[out]descriptionReturned description. Allocated with malloc.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_GetCreator ( OTF2_Archive archive,
char **  creator 
)

Get creator information.

Parameters
archiveArchive handle.
[out]creatorReturned creator. Allocated with malloc.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_GetVersion ( OTF2_Archive archive,
uint8_t *  major,
uint8_t *  minor,
uint8_t *  bugfix 
)

Get format version.

Parameters
archiveArchive handle
[out]majorMajor version number
[out]minorMinor version number
[out]bugfixBugfix revision
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_GetChunkSize ( OTF2_Archive archive,
uint64_t *  chunkSizeEvents,
uint64_t *  chunkSizeDefs 
)

Get the chunksize.

Parameters
archiveArchive handle.
[out]chunkSizeEventsChunk size for event files.
[out]chunkSizeDefsChunk size for definition files.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_GetFileSubstrate ( OTF2_Archive archive,
OTF2_FileSubstrate substrate 
)

Get the file substrate (posix, sion, none)

Parameters
archiveArchive handle.
[out]substrateReturned file substrate.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_GetCompression ( OTF2_Archive archive,
OTF2_Compression compression 
)

Get compression mode (none or zlib)

Parameters
archiveArchive handle.
[out]compressionReturned compression mode.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_EvtWriter* OTF2_Archive_GetEvtWriter ( OTF2_Archive archive,
OTF2_LocationRef  location 
)

Get a local event writer.

Parameters
archiveArchive handle.
locationLocation ID of the requested writer handle.
Returns
Returns a local event writer handle if successful, NULL if an error occurs.
Examples:
otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_DefWriter* OTF2_Archive_GetDefWriter ( OTF2_Archive archive,
OTF2_LocationRef  location 
)

Get a local definition writer.

Parameters
archiveArchive handle.
locationLocation ID of the requested writer handle.
Returns
Returns a local definition writer handle if successful, NULL if an error occurs.
Examples:
otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_GlobalDefWriter* OTF2_Archive_GetGlobalDefWriter ( OTF2_Archive archive)

Get a global definition writer.

Only the primary archive can call this function.

Parameters
archiveArchive handle.
Returns
Returns a global definition writer handle if successful, NULL if an error occurs.
Examples:
otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_SnapWriter* OTF2_Archive_GetSnapWriter ( OTF2_Archive archive,
OTF2_LocationRef  location 
)

Get a local snap writer.

Parameters
archiveArchive handle.
locationLocation ID of the requested writer handle.
Since
Version 1.2
Returns
Returns a local event writer handle if successful, NULL if an error occurs.
OTF2_ThumbWriter* OTF2_Archive_GetThumbWriter ( OTF2_Archive archive,
const char *  name,
const char *  description,
OTF2_ThumbnailType  type,
uint32_t  numberOfSamples,
uint32_t  numberOfMetrics,
const uint64_t *  refsToDefs 
)

Get a thumb writer.

Parameters
archiveArchive handle.
nameName of thumb.
descriptionDescription of thumb.
typeType of thumb.
numberOfSamplesNumber of samples.
numberOfMetricsNumber of metrics.
refsToDefsnumberOfMetrics references to definition matching the thumbnail type.
Since
Version 1.2
Returns
Returns a thumb writer handle if successful, NULL if an error occurs.
OTF2_MarkerWriter* OTF2_Archive_GetMarkerWriter ( OTF2_Archive archive)

Get a marker writer.

Parameters
archiveArchive handle.
Since
Version 1.2
Returns
Returns a marker writer handle if successful, NULL if an error occurs.
OTF2_EvtReader* OTF2_Archive_GetEvtReader ( OTF2_Archive archive,
OTF2_LocationRef  location 
)

Get a local event reader.

Parameters
archiveArchive handle.
locationLocation ID of the requested reader handle.
Returns
Returns a local event reader handle if successful, NULL if an error occurs.
OTF2_GlobalEvtReader* OTF2_Archive_GetGlobalEvtReader ( OTF2_Archive archive)

Get a global event reader.

Parameters
archiveArchive handle.
Returns
Returns a global event reader handle if successful, NULL if an error occurs.
OTF2_DefReader* OTF2_Archive_GetDefReader ( OTF2_Archive archive,
OTF2_LocationRef  location 
)

Get a local definition reader.

Parameters
archiveArchive handle.
locationLocation ID of the requested reader handle.
Returns
Returns a local definition reader handle if successful, NULL if an error occurs.
OTF2_GlobalDefReader* OTF2_Archive_GetGlobalDefReader ( OTF2_Archive archive)

Get a global definition reader.

Parameters
archiveArchive handle.
Returns
Returns a global definition reader handle if successful, NULL if an error occurs.
OTF2_SnapReader* OTF2_Archive_GetSnapReader ( OTF2_Archive archive,
OTF2_LocationRef  location 
)

Get a local snap reader.

Parameters
archiveArchive handle.
locationLocation ID of the requested snap handle.
Since
Version 1.2
Returns
Returns a local snap handle if successful, NULL if an error occurs.
OTF2_GlobalSnapReader* OTF2_Archive_GetGlobalSnapReader ( OTF2_Archive archive)

Get a global snap reader.

Parameters
archiveArchive handle.
Since
Version 1.2
Returns
Returns a global snap reader handle if successful, NULL if an error occurs.
OTF2_ThumbReader* OTF2_Archive_GetThumbReader ( OTF2_Archive archive,
uint32_t  number 
)

Get a thumb reader.

Parameters
archiveArchive handle.
numberThumbnail number.
Since
Version 1.2
Returns
Returns a global definition writer handle if successful, NULL if an error occurs.
OTF2_MarkerReader* OTF2_Archive_GetMarkerReader ( OTF2_Archive archive)

Get a marker reader.

Parameters
archiveArchive handle.
Since
Version 1.2
Returns
Returns a marker reader handle if successful, NULL if an error occurs.
OTF2_ErrorCode OTF2_Archive_CloseEvtWriter ( OTF2_Archive archive,
OTF2_EvtWriter writer 
)

Close an opened local event writer.

Parameters
archiveArchive handle.
writerWriter handle to be closed.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_ErrorCode OTF2_Archive_CloseDefWriter ( OTF2_Archive archive,
OTF2_DefWriter writer 
)

Close an opened local definition writer.

Parameters
archiveArchive handle.
writerWriter handle to be closed.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_ErrorCode OTF2_Archive_CloseMarkerWriter ( OTF2_Archive archive,
OTF2_MarkerWriter writer 
)

Close an opened marker writer.

Parameters
archiveArchive handle.
writerWriter handle to be closed.
Since
Version 1.2
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_CloseSnapWriter ( OTF2_Archive archive,
OTF2_SnapWriter writer 
)

Close an opened local snap writer.

Parameters
archiveArchive handle.
writerWriter handle to be closed.
Since
Version 1.2
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_CloseGlobalDefWriter ( OTF2_Archive archive,
OTF2_GlobalDefWriter writer 
)

Close an opened global definition writer.

Only the primary archive can call this function.

Parameters
archiveArchive handle.
writerWriter handle to be closed.
Returns
OTF2_SUCCESS
if successful
OTF2_ERROR_INVALID_ARGUMENT
if the archive or writer argument is invalid
OTF2_ERROR_INVALID_CALL
if this is not the primary archive
Examples:
otf2_mpi_writer_example.c.
OTF2_ErrorCode OTF2_Archive_CloseEvtReader ( OTF2_Archive archive,
OTF2_EvtReader reader 
)

Close an opened local event reader.

Parameters
archiveArchive handle.
readerReader handle to be closed.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_CloseThumbReader ( OTF2_Archive archive,
OTF2_ThumbReader reader 
)

Close an opened thumbnail reader.

Parameters
archiveArchive handle.
readerReader handle to be closed.
Since
Version 1.2
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_CloseGlobalEvtReader ( OTF2_Archive archive,
OTF2_GlobalEvtReader globalEvtReader 
)

Closes the global event reader.

This closes also all local event readers.

Parameters
archiveArchive handle.
globalEvtReaderThe global event reader.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_CloseDefReader ( OTF2_Archive archive,
OTF2_DefReader reader 
)

Close an opened local definition reader.

Parameters
archiveArchive handle.
readerReader handle to be closed.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_CloseGlobalDefReader ( OTF2_Archive archive,
OTF2_GlobalDefReader globalDefReader 
)

Closes the global definition reader.

Parameters
archiveArchive handle.
globalDefReaderThe global definition reader.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_CloseSnapReader ( OTF2_Archive archive,
OTF2_SnapReader reader 
)

Close an opened local snap reader.

Parameters
archiveArchive handle.
readerReader handle to be closed.
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
Since
Version 1.2
OTF2_ErrorCode OTF2_Archive_CloseGlobalSnapReader ( OTF2_Archive archive,
OTF2_GlobalSnapReader globalSnapReader 
)

Close the opened global snapshot reader.

Parameters
archiveArchive handle.
globalSnapReaderReader handle to be closed.
Since
Version 1.2
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_CloseMarkerReader ( OTF2_Archive archive,
OTF2_MarkerReader markerReader 
)

Closes the marker reader.

Parameters
archiveArchive handle.
markerReaderThe marker reader.
Since
Version 1.2
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_GetNumberOfThumbnails ( OTF2_Archive archive,
uint32_t *  number 
)

Get the number of thumbnails.

Parameters
archiveArchive handle.
numberThumb number.
Since
Version 1.2
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_SetNumberOfSnapshots ( OTF2_Archive archive,
uint32_t  number 
)

Set the number of snapshots.

Parameters
archiveArchive handle.
numberSnapshot number.
Since
Version 1.2
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_GetNumberOfSnapshots ( OTF2_Archive archive,
uint32_t *  number 
)

Get the number of snapshots.

Parameters
archiveArchive handle.
numberSnapshot number.
Since
Version 1.2
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_OpenEvtFiles ( OTF2_Archive archive)

Open the events file container.

This function is a collective operation.

Parameters
archiveArchive handle.
Since
Version 1.3
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_ErrorCode OTF2_Archive_CloseEvtFiles ( OTF2_Archive archive)

Closes the events file container.

This function is a collective operation.

Parameters
archiveArchive handle.
Since
Version 1.3
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_ErrorCode OTF2_Archive_OpenDefFiles ( OTF2_Archive archive)

Open the local definitions file container.

This function is a collective operation.

Parameters
archiveArchive handle.
Since
Version 1.3
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_ErrorCode OTF2_Archive_CloseDefFiles ( OTF2_Archive archive)

Closes the local definitions file container.

This function is a collective operation.

Parameters
archiveArchive handle.
Since
Version 1.3
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
Examples:
otf2_mpi_writer_example.c, otf2_openmp_writer_example.c, otf2_pthread_writer_example.c, and otf2_writer_example.c.
OTF2_ErrorCode OTF2_Archive_OpenSnapFiles ( OTF2_Archive archive)

Open the snapshots file container.

This function is a collective operation.

Parameters
archiveArchive handle.
Since
Version 1.3
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_CloseSnapFiles ( OTF2_Archive archive)

Closes the snapshots file container.

This function is a collective operation.

Parameters
archiveArchive handle.
Since
Version 1.3
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.
OTF2_ErrorCode OTF2_Archive_SelectLocation ( OTF2_Archive archive,
OTF2_LocationRef  location 
)

Select a location to be read.

Parameters
archiveArchive handle.
locationLocation ID.
Since
Version 1.3
Returns
OTF2_SUCCESS if successful, an error code if an error occurs.