H5P_SET_FAPL_LOG

Content Layer

id	1195548671

Content Column

width	50.00001%
id	1195578110
class	rm_pagetree_col mobile-hide

Content Block

id	1195578111

Content Column

width	50.00001%
id	1195548673
class	hdf-rm-main-column

Content Block

id	1195548672

Include Content

render-without-blocks	true
page	.rm-navbar

HTML Wrap

class	hdf-print-only

Page Title

HTML Wrap

class	hdf-rm-summary-block

Hdf rm anchor

AnchorName	summary

Excerpt
Sets up the logging virtual file driver (`H5FD_LOG`) for use

HTML Wrap

class	hdf-rm-content-block

Hdf rm anchor

AnchorName	procedure

Procedure:

HTML Wrap

class	hdf-rm-section

HTML Wrap

class	hdf_procedure

H5P_SET_FAPL_LOG ( fapl_id, logfile, flags, buf_size )

Hdf rm anchor

AnchorName	signature

Signature:

HTML Wrap

class	hdf-rm-section

HTML Wrap

class	hdf-togglebox hdf-c

HTML Add Class

	hdf-togglebutton-visible
	hdf-togglebutton-visible
selector	.hdf-togglebutton.hdf-c

HTML
<pre><code class="language-c">herr_t H5Pset_fapl_log( hid_t fapl_id, const char *logfile, unsigned long long flags, size_t buf_size ) </code></pre>

Hdf rm anchor

AnchorName	parameters

Parameters:

HTML Wrap

class	hdf-rm-section

hid_t `fapl_id`	IN: File access property list identifier
char *`logfile`	IN: Name of the log file
unsigned long long `flags`	IN: Flags specifying the types of logging activity
size_t `buf_size`	IN: The size of the logging buffers, in bytes (see description)

Hdf rm anchor

AnchorName	description

Description:

HTML Wrap

class	hdf-rm-section

H5P_SET_FAPL_LOG modifies the file access property list to use the logging driver, H5FD_LOG. The logging virtual file driver (VFD) is a clone of the standard SEC2 (H5FD_SEC2) driver with additional facilities for logging VFD metrics and activity to a file.

logfile is the name of the file in which the logging entries are to be recorded.

The actions to be logged are specified in the parameter flags using the pre-defined constants described in the following table. Multiple flags can be set through the use of a logical OR contained in parentheses. For example, logging read and write locations would be specified as (H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE).

Table 1: Logging flags
Flag	Description
H5FD_LOG_LOC_READ	Track the location and length of every read, write, or seek operation.
H5FD_LOG_LOC_WRITE
H5FD_LOG_LOC_SEEK
H5FD_LOG_LOC_IO	Track all I/O locations and lengths. The logical equivalent of the following: (H5FD_LOG_LOC_READ \| H5FD_LOG_LOC_WRITE \| H5FD_LOG_LOC_SEEK)
H5FD_LOG_FILE_READ	Track the number of times each byte is read or written.
H5FD_LOG_FILE_WRITE	Track the number of times each byte is read or written.
H5FD_LOG_FILE_IO	Track the number of times each byte is read and written. The logical equivalent of the following: (H5FD_LOG_FILE_READ \| H5FD_LOG_FILE_WRITE)
H5FD_LOG_FLAVOR	Track the type, or flavor, of information stored at each byte.
H5FD_LOG_NUM_READ	Track the total number of read, write, seek, or truncate operations that occur.
H5FD_LOG_NUM_WRITE
H5FD_LOG_NUM_SEEK
H5FD_LOG_NUM_TRUNCATE
H5FD_LOG_NUM_IO	Track the total number of all types of I/O operations. The logical equivalent of the following: (H5FD_LOG_NUM_READ \| H5FD_LOG_NUM_WRITE \| H5FD_LOG_NUM_SEEK \| H5FD_LOG_NUM_TRUNCATE)
H5FD_LOG_TIME_OPEN	Track the time spent in open, stat, read, write, seek, or close operations.
H5FD_LOG_TIME_STAT
H5FD_LOG_TIME_READ
H5FD_LOG_TIME_WRITE
H5FD_LOG_TIME_SEEK
H5FD_LOG_TIME_CLOSE
H5FD_LOG_TIME_IO	Track the time spent in each of the above operations. The logical equivalent of the following: (H5FD_LOG_TIME_OPEN \| H5FD_LOG_TIME_STAT \| H5FD_LOG_TIME_READ \| H5FD_LOG_TIME_WRITE \| H5FD_LOG_TIME_SEEK \| H5FD_LOG_TIME_CLOSE)
H5FD_LOG_ALLOC	Track the allocation of space in the file.
H5FD_LOG_ALL	Track everything. The logical equivalent of the following: (H5FD_LOG_ALLOC \| H5FD_LOG_TIME_IO \| H5FD_LOG_NUM_IO \| H5FD_LOG_FLAVOR \| H5FD_LOG_FILE_IO \| H5FD_LOG_LOC_IO)

The logging driver can track the number of times each byte in the file is read from or written to (using H5FD_LOG_FILE_READ and H5FD_LOG_FILE_WRITE) and what kind of data is at that location (e.g., metadata, raw data; using H5FD_LOG_FLAVOR). This information is tracked in internal buffers of size buf_size, which must be at least the maximum size in bytes of the file to be logged while the log driver is in use.

One buffer of size buf_size will be created for each of H5FD_LOG_FILE_READ, H5FD_LOG_FILE_WRITE and H5FD_LOG_FLAVOR when those flags are set; these buffers will not grow as the file increases in size.

Output:

HTML Wrap

class	hdf-rm-section

This section describes the logging driver (LOG VFD) output.

The table, immediately below, describes output of the various logging driver flags and function calls; error output is in red italic. A list of valid flavor values, describing the type of data stored, follows the table.

Table 2: Logging output
Flag (H5FD_LOG_)	VFD Call	Output and Comments
LOC_READ	Read()	%10a-%10a (%10Zu bytes) (%s) Read Start position End position Number of bytes Flavor of read Adds (%f s) and seek time if TIME_SEEK is also set.
LOC_READ	Read() Error	Error! Reading: %10a-%10a (%10Zu bytes) Same parameters as non-error entry.
LOC_WRITE	Write()	%10a-%10a (%10Zu bytes) (%s) Written Start position End position Number of bytes Flavor of write Adds (%f s) and seek time if TIME_SEEK is also set.
LOC_WRITE	Write() Error	Error! Writing: %10a-%10a (%10Zu bytes) Same parameters as non-error entry.
LOC_SEEK	Read() Write()	Seek: From %10a-%10a Start position End position Adds (%f s) and seek time if TIME_SEEK is also set.
FILE_READ	Close()	Begins with: Dumping read I/O information Then, for each range of identical values, there is this line: \tAddr %10-%10 (%10lu bytes) read from %3d times Start address End address Number of bytes Number of times read Note: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read.
FILE_WRITE	Close()	Begins with: Dumping write I/O information Then, for each range of identical values, there is this line: \tAddr %10-%10 (%10lu bytes) written to %3d times Start address End address Number of bytes Number of times written Note: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read.
FLAVOR	Close()	Begins with: Dumping I/O flavor information Then, for each range of identical values, there is this line: \tAddr %10-%10 (%10lu bytes) flavor is %s Start address End address Number of bytes Flavor Note: The data buffer is scanned and each range of identical values gets one entry in the log file to save space and make it easier to read.
NUM_READ	Close()	Total number of read operations: %11u
NUM_WRITE	Close()	Total number of write operations: %11u
NUM_SEEK	Close()	Total number of seek operations: %11u
NUM_TRUNCATE	Close()	Total number of truncate operations: %11u
TIME_OPEN	Open()	Open took: (%f s)
TIME_READ	Close() Read()	Total time in read operations: %f s See also: LOC_READ
TIME_WRITE	Close() Write()	Total time in write operations: %f s See also: LOC_WRITE
TIME_SEEK	Close() Read() Write()	Total time in seek operations: %f s See also: LOC_SEEK or LOC_WRITE
TIME_CLOSE	Close()	Close took: (%f s)
TIME_STAT	Open()	Stat took: (%f s)
ALLOC	Alloc()	%10-%10 (%10Hu bytes) (%s) Allocated Start of address space End of address space Total size of allocation Flavor of allocation

Flavors:
The flavor describes the type of stored information. The following table lists the flavors that appear in log output and briefly describes each. These terms are provided here to aid in the construction of log message parsers; a full description is beyond the scope of this document.

Table 3: Flavors of logged data
Flavor	Description
H5FD_MEM_NOLIST	Error value
H5FD_MEM_DEFAULT	Value not yet set. May also be a datatype set in a larger allocation that will be suballocated by the library.
H5FD_MEM_SUPER	Superblock data
H5FD_MEM_BTREE	B-tree data
H5FD_MEM_DRAW	Raw data (for example, contents of a dataset)
H5FD_MEM_GHEAP	Global heap data
H5FD_MEM_LHEAP	Local heap data
H5FD_MEM_OHDR	Object header data

Hdf rm anchor

AnchorName	returns

Returns:

HTML Wrap

class	hdf-rm-section

Returns non-negative if successful. Otherwise returns negative.

Hdf rm anchor

AnchorName	example

Example:

HTML Wrap

class	hdf-rm-section

Coming Soon!

Comment

HTML Wrap

class	hdf-togglebox hdf-c

Bitbucket Server file

repoSlug	hdf5
branchId	refs/heads/1.10/master
projectKey	HDFFV
filepath	examples/h5_subset.c
showLineNumbers	true
lineStart	32
progLang	cpp
lineEnd	42
applicationLink	5ac7b370-7412-3c8c-ad20-807a68261336

HTML Wrap

class	hdf-togglebox hdf-fortran hdf-togglebox-hidden

Bitbucket Server file

repoSlug	hdf5
branchId	refs/heads/1.10/master
projectKey	HDFFV
filepath	fortran/examples/compound.f90
showLineNumbers	true
lineStart	25
progLang	plain
lineEnd	35
applicationLink	5ac7b370-7412-3c8c-ad20-807a68261336

Hdf rm anchor

AnchorName	history

History:

HTML Wrap

class	hdf-rm-section

Release	Change
1.8.7	The `flags` parameter has been changed from unsigned int to unsigned long long. The implementation of the `H5FD_LOG_TIME_OPEN`, `H5FD_LOG_TIME_READ`, `H5FD_LOG_TIME_WRITE`, and `H5FD_LOG_TIME_SEEK` flags has been finished. New flags were added: `H5FD_LOG_NUM_TRUNCATE` and `H5FD_LOG_TIME_STAT`.
1.6.0	The `verbosity` parameter has been removed. Two new parameters have been added: `flags` of type unsigned and `buf_size` of type size_t.
1.4.0	Function introduced in this release.

Page tree

Versions Compared

Old Version 12

New Version Current

Key

Procedure:

Signature:

Parameters:

Description:

Output:

Returns:

Example:

History:

The HDF Group

Site

Resources

Connect