Last modified: 12 May 2011
Name: H5Pset_fapl_log
Signature:
  herr_t `H5Pset_fapl_log`( hid_t `fapl_id`, const char *`logfile`, unsigned long long `flags`, size_t `buf_size` )

Purpose:
  Sets up the logging virtual file driver (`H5FD_LOG`) for use.

Description:
  `H5Pset_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`
  `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.

Parameters:

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

Output:
  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

Returns:
  Returns non-negative if successful. Otherwise returns negative.

Fortran90 Interface:
  None.

History:

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