Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2025-11-11 The HDF5 Field Guide

- Main Page
- Getting started
- User Guide
- Reference Manual
- Cookbook
- Technical Notes
- RFCs
- Specifications
- Glossary
- Full-Text Search
- About

Loading...
Searching...
No Matches
Functions
HDF5 Packet Table APIs (H5PT)

## Detailed Description

Creating and manipulating HDF5 datasets to support append- and read-only operations on table data (H5PT)

The HDF5 Packet Table API is designed to allow records to be appended to and read from a table. Packet Table datasets are chunked, allowing them to grow as needed.

The Packet Table API, with the H5PT prefix, is not to be confused with the H5TB Table API (H5TB prefix). The H5TB APIs are stateless (H5TB Tables do not need to be opened or closed) but H5PT Packet Tables require less performance overhead. Also, H5TB Tables support insertions and deletions, while H5PT Packet Tables support only append operations. H5TB functions should not be called on tables created with the H5PT API, or vice versa.

Packet Tables are datasets in an HDF5 file, so while their contents should not be changed outside of the H5PT API calls, the datatypes of Packet Tables can be queried using H5Dget_type. Packet Tables can also be given attributes using the normal HDF5 APIs.

Note
  Programming hints:
  The following line includes the HDF5 Packet Table package, H5PT, in C applications:
  #include "hdf5_hl.h"
  Without this include, an application will not have access to these functions.

- H5PTappend
  Appends packets to the end of a packet table.
- H5PTclose
  Closes an open packet table.
- H5PTcreate
  Creates a packet table to store fixed-length or variable-length packets.
- H5PTcreate_fl
  Creates a packet table to store fixed-length packets.
- H5PTcreate_index
  Resets a packet table's index to the first packet.
- H5PTfree_vlen_buff
  Releases memory allocated in the process of reading variable-length packets.
- H5PTget_dataset
  Returns the backend dataset of this packet table.
- H5PTget_index
  Gets the current record index for a packet table
- H5PTget_next
  Reads packets from a packet table starting at the current index.
- H5PTget_num_packets
  Returns the number of packets in a packet table.
- H5PTget_type
  Returns the backend datatype of this packet table.
- H5PTis_valid
  Determines whether an identifier points to a packet table.
- H5PTis_varlen
  Determines whether a packet table contains variable-length or fixed-length packets.
- H5PTopen
  Opens an existing packet table.
- H5PTread_packets
  Reads a number of packets from a packet table.
- H5PTset_index
  Sets a packet table's index.

## Functions
H5HL_DLL herr_t | H5PTappend (hid_t table_id, size_t nrecords, const void *data)
| Appends packets to the end of a packet table.
H5HL_DLL herr_t | H5PTclose (hid_t table_id)
| Closes an open packet table.
H5HL_DLL hid_t | H5PTcreate (hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size, hid_t plist_id)
| Creates a packet table to store fixed-length or variable-length packets.
H5HL_DLL hid_t | H5PTcreate_fl (hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size, int compression)
| Creates a packet table to store fixed-length packets.
H5HL_DLL herr_t | H5PTcreate_index (hid_t table_id)
| Resets a packet table's index to the first packet.
H5HL_DLL herr_t | H5PTfree_vlen_buff (hid_t table_id, size_t bufflen, void *buff)
| Releases memory allocated in the process of reading variable-length packets.
H5HL_DLL hid_t | H5PTget_dataset (hid_t table_id)
| Returns the backend dataset of this packet table.
H5HL_DLL herr_t | H5PTget_index (hid_t table_id, hsize_t *pt_index)
| Gets the current record index for a packet table.
H5HL_DLL herr_t | H5PTget_next (hid_t table_id, size_t nrecords, void *data)
| Reads packets from a packet table starting at the current index.
H5HL_DLL herr_t | H5PTget_num_packets (hid_t table_id, hsize_t *nrecords)
| Returns the number of packets in a packet table.
H5HL_DLL hid_t | H5PTget_type (hid_t table_id)
| Returns the backend datatype of this packet table.
H5HL_DLL herr_t | H5PTis_valid (hid_t table_id)
| Determines whether an identifier points to a packet table.
H5HL_DLL herr_t | H5PTis_varlen (hid_t table_id)
| Determines whether a packet table contains variable-length or fixed-length packets.
H5HL_DLL hid_t | H5PTopen (hid_t loc_id, const char *dset_name)
| Opens an existing packet table.
H5HL_DLL herr_t | H5PTread_packets (hid_t table_id, hsize_t start, size_t nrecords, void *data)
| Reads a number of packets from a packet table.
H5HL_DLL herr_t | H5PTset_index (hid_t table_id, hsize_t pt_index)
| Sets a packet table's index.

## Function Documentation

## ◆ H5PTappend()

H5HL_DLL herr_t H5PTappend | ( | hid_t | table_id,
|  | size_t | nrecords,
|  | const void * | data )

Appends packets to the end of a packet table.

Parameters

  [in] | table_id | Identifier of packet table to which packets should be appended
  [in] | nrecords | Number of packets to be appended
  [in] | data | Buffer holding data to write

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

The H5PTappend() writes `nrecords` packets to the end of a packet table specified by `table_id`. `data` is a buffer containing the data to be written. For a packet table holding fixed-length packets, this data should be in the packet table's datatype. For a variable-length packet table, the data should be in the form of hvl_t structs.

## ◆ H5PTclose()

H5HL_DLL herr_t H5PTclose | ( | hid_t | table_id | ) |

Closes an open packet table.

Parameters

  [in] | table_id | Identifier of packet table to be closed

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

The H5PTclose() ends access to a packet table specified by `table_id`.

## ◆ H5PTcreate()

H5HL_DLL hid_t H5PTcreate | ( | hid_t | loc_id,
|  | const char * | dset_name,
|  | hid_t | dtype_id,
|  | hsize_t | chunk_size,
|  | hid_t | plist_id )

Creates a packet table to store fixed-length or variable-length packets.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | dset_name | The name of the packet table to create
  [in] | dtype_id | The datatype of the packet
  [in] | chunk_size | The size in number of table entries per chunk
  [in] | plist_id | Identifier of the property list. Can be used to specify the compression of the packet table.

Returns
  Returns an identifier for the new packet table or H5I_INVALID_HID on error.

The H5PTcreate() creates and opens a packet table named `dset_name` attached to the object specified by the identifier `loc_id`. The created packet table should be closed with H5PTclose(), eventually.

The datatype, `dtype_id`, may specify any datatype, including variable-length data. If `dtype_id` specifies a compound datatype, one or more fields in that compound type may be variable-length.

`chunk_size` is the size in number of table entries per chunk. Packet table datasets use HDF5 chunked storage to allow them to grow. This value allows the user to set the size of a chunk. The chunk size affects performance.

Since
  1.10.0 and 1.8.17

## ◆ H5PTcreate_fl()

H5HL_DLL hid_t H5PTcreate_fl | ( | hid_t | loc_id,
|  | const char * | dset_name,
|  | hid_t | dtype_id,
|  | hsize_t | chunk_size,
|  | int | compression )

Creates a packet table to store fixed-length packets.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | dset_name | The name of the dataset to create
  [in] | dtype_id | The datatype of a packet.
  [in] | chunk_size | The size in number of table entries per chunk.
  [in] | compression | The compression level; a value of 0 through 9.

Returns
  Returns an identifier for the packet table or H5I_INVALID_HID on error.

Deprecated
  This function was deprecated in favor of the function H5PTcreate().

The H5PTcreate_fl() creates and opens a packet table named `dset_name` attached to the object specified by the identifier `loc_id`. It should be closed with H5PTclose().

The datatype, `dtype_id`, may specify any datatype, including variable-length data. If `dtype_id` specifies a compound datatype, one or more fields in that compound type may be variable-length.

`chunk_size` is the size in number of table entries per chunk. Packet table datasets use HDF5 chunked storage to allow them to grow. This value allows the user to set the size of a chunk. The chunk size affects performance.

`compression` is the compression level, a value of 0 through 9. Level 0 is faster but offers the least compression; level 9 is slower but offers maximum compression. A setting of -1 indicates that no compression is desired.

## ◆ H5PTcreate_index()

H5HL_DLL herr_t H5PTcreate_index | ( | hid_t | table_id | ) |

Resets a packet table's index to the first packet.

Parameters

  [in] | table_id | Identifier of packet table whose index should be initialized.

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

Each packet table keeps an index of the "current" packet so that `get_next` can iterate through the packets in order. H5PTcreate_index() initializes a packet table's index, and should be called before using `get_next`. The index must be initialized every time a packet table is created or opened; this information is lost when the packet table is closed.

## ◆ H5PTfree_vlen_buff()

H5HL_DLL herr_t H5PTfree_vlen_buff | ( | hid_t | table_id,
|  | size_t | bufflen,
|  | void * | buff )

Releases memory allocated in the process of reading variable-length packets.

Parameters

  [in] | table_id | Packet table whose memory should be freed.
  [in] | bufflen | Size of `buff`
  [in] | buff | Buffer that was used to read in variable-length packets

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

When variable-length packets are read, memory is automatically allocated to hold them, and must be freed. H5PTfree_vlen_buff() frees this memory, and should be called whenever packets are read from a variable-length packet table.

Version
  1.10.0 and 1.8.17 Function re-introduced. Function had been removed in 1.8.3.

## ◆ H5PTget_dataset()

H5HL_DLL hid_t H5PTget_dataset | ( | hid_t | table_id | ) |

Returns the backend dataset of this packet table.

Parameters

  [in] | table_id | Identifier of the packet table

Returns
  Returns a dataset identifier or H5I_INVALID_HID on error.

The H5PTget_dataset() returns the identifier of the dataset storing the packet table `table_id`. This dataset identifier will be closed by H5PTclose().

Since
  1.10.0 and 1.8.17

## ◆ H5PTget_index()

H5HL_DLL herr_t H5PTget_index | ( | hid_t | table_id,
|  | hsize_t * | pt_index )

Gets the current record index for a packet table.

Parameters

  [in] | table_id | Table identifier
  [out] | pt_index | Current record index

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

The H5PTget_index() returns the current record index `pt_index` for the table identified by `table_id`.

Since
  1.8.0

## ◆ H5PTget_next()

H5HL_DLL herr_t H5PTget_next | ( | hid_t | table_id,
|  | size_t | nrecords,
|  | void * | data )

Reads packets from a packet table starting at the current index.

Parameters

  [in] | table_id | Identifier of packet table to read from
  [in] | nrecords | Number of packets to be read
  [out] | data | Buffer into which to read data

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

The H5PTget_next() reads `nrecords` packets starting with the "current index" from a packet table specified by `table_id`. The packet table's index is set and reset with H5PTset_index() and H5PTcreate_index(). `data` is a buffer into which the data should be read.

For a packet table holding variable-length records, the data returned in the buffer will be in form of a hvl_t struct containing the length of the data and a pointer to it in memory. The memory used by this data must be freed using H5PTfree_vlen_buff().

## ◆ H5PTget_num_packets()

H5HL_DLL herr_t H5PTget_num_packets | ( | hid_t | table_id,
|  | hsize_t * | nrecords )

Returns the number of packets in a packet table.

Parameters

  [in] | table_id | Identifier of packet table to query
  [out] | nrecords | Number of packets in packet table

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

The H5PTget_num_packets() returns by reference the number of packets in a packet table specified by `table_id`.

## ◆ H5PTget_type()

H5HL_DLL hid_t H5PTget_type | ( | hid_t | table_id | ) |

Returns the backend datatype of this packet table.

Parameters

  [in] | table_id | Identifier of the packet table

Returns
  Returns a datatype identifier or H5I_INVALID_HID on error.

The H5PTget_type() returns the identifier of the datatype used by the packet table `table_id`. This datatype identifier will be closed by H5PTclose().

Since
  1.10.0 and 1.8.17

## ◆ H5PTis_valid()

H5HL_DLL herr_t H5PTis_valid | ( | hid_t | table_id | ) |

Determines whether an identifier points to a packet table.

Parameters

  [in] | table_id | Identifier to query

Returns
  Returns a non-negative value if `table_id` is a valid packet table, otherwise returns a negative value.

The H5PTis_valid() returns a non-negative value if `table_id` corresponds to an open packet table, and returns a negative value otherwise.

## ◆ H5PTis_varlen()

H5HL_DLL herr_t H5PTis_varlen | ( | hid_t | table_id | ) |

Determines whether a packet table contains variable-length or fixed-length packets.

Parameters

  [in] | table_id | Packet table to query

Returns
  Returns 1 for a variable-length packet table, 0 for fixed-length, or a negative value on error.

The H5PTis_varlen() returns 1 (TRUE) if `table_id` is a packet table containing variable-length records. It returns 0 (FALSE) if `table_id` is a packet table containing fixed-length records. If `table_id` is not a packet table, a negative value is returned.

Version
  1.10.0 and 1.8.17 Function re-introduced. Function had been removed in 1.8.3.

## ◆ H5PTopen()

H5HL_DLL hid_t H5PTopen | ( | hid_t | loc_id,
|  | const char * | dset_name )

Opens an existing packet table.

Parameters

  [in] | loc_id | Location identifier. The identifier may be that of a file or group.
  [in] | dset_name | The name of the packet table to open

Returns
  Returns an identifier for the packet table or H5I_INVALID_HID on error.

H5PTopen() opens an existing packet table in the file or group specified by `loc_id`. `dset_name` is the name of the packet table and is used to identify it in the file. This function is used to open both fixed-length packet tables and variable-length packet tables. The packet table should later be closed with H5PTclose().

## ◆ H5PTread_packets()

H5HL_DLL herr_t H5PTread_packets | ( | hid_t | table_id,
|  | hsize_t | start,
|  | size_t | nrecords,
|  | void * | data )

Reads a number of packets from a packet table.

Parameters

  [in] | table_id | Identifier of packet table to read from
  [in] | start | Packet to start reading from
  [in] | nrecords | Number of packets to be read
  [out] | data | Buffer into which to read data.

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

The H5PTread_packets() reads `nrecords` packets starting at packet number `start` from a packet table specified by `table_id`. `data` is a buffer into which the data should be read.

For a packet table holding variable-length records, the data returned in the buffer will be in form of hvl_t structs, each containing the length of the data and a pointer to it in memory. The memory used by this data must be freed using H5PTfree_vlen_buff().

## ◆ H5PTset_index()

H5HL_DLL herr_t H5PTset_index | ( | hid_t | table_id,
|  | hsize_t | pt_index )

Sets a packet table's index.

Parameters

  [in] | table_id | Identifier of packet table whose index is to be set
  [in] | pt_index | The packet to which the index should point

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

Each packet table keeps an index of the "current" packet so that `get_next` can iterate through the packets in order. H5PTset_index() sets this index to point to a user-specified packet (the packets are zero-indexed).