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

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
Atomic Datatypes
Datatypes (H5T)

## Detailed Description

## Functions
H5T_cset_t | H5Tget_cset (hid_t type_id)
| Retrieves the character set type of a string datatype.
size_t | H5Tget_ebias (hid_t type_id)
| Retrieves the exponent bias of a floating-point type.
herr_t | H5Tget_fields (hid_t type_id, size_t *spos, size_t *epos, size_t *esize, size_t *mpos, size_t *msize)
| Retrieves floating point datatype bit field information.
H5T_pad_t | H5Tget_inpad (hid_t type_id)
| Retrieves the internal padding type for unused bits in floating-point datatypes.
H5T_norm_t | H5Tget_norm (hid_t type_id)
| Retrieves mantissa normalization of a floating-point datatype.
int | H5Tget_offset (hid_t type_id)
| Retrieves the bit offset of the first significant bit.
H5T_order_t | H5Tget_order (hid_t type_id)
| Returns the byte order of an atomic datatype.
herr_t | H5Tget_pad (hid_t type_id, H5T_pad_t *lsb, H5T_pad_t *msb)
| Retrieves the padding type of the least and most-significant bit padding.
size_t | H5Tget_precision (hid_t type_id)
| Returns the precision of an atomic datatype.
H5T_sign_t | H5Tget_sign (hid_t type_id)
| Retrieves the sign type for an integer type.
H5T_str_t | H5Tget_strpad (hid_t type_id)
| Retrieves the type of padding used for a string datatype.
htri_t | H5Tis_variable_str (hid_t type_id)
| Determines whether datatype is a variable-length string.
herr_t | H5Tset_cset (hid_t type_id, H5T_cset_t cset)
| Sets character set to be used in a string or character datatype.
herr_t | H5Tset_ebias (hid_t type_id, size_t ebias)
| Sets the exponent bias of a floating-point type.
herr_t | H5Tset_fields (hid_t type_id, size_t spos, size_t epos, size_t esize, size_t mpos, size_t msize)
| Sets locations and sizes of floating point bit fields.
herr_t | H5Tset_inpad (hid_t type_id, H5T_pad_t pad)
| Fills unused internal floating-point bits.
herr_t | H5Tset_norm (hid_t type_id, H5T_norm_t norm)
| Sets the mantissa normalization of a floating-point datatype.
herr_t | H5Tset_offset (hid_t type_id, size_t offset)
| Sets the bit offset of the first significant bit.
herr_t | H5Tset_order (hid_t type_id, H5T_order_t order)
| Sets the byte order of a datatype.
herr_t | H5Tset_pad (hid_t type_id, H5T_pad_t lsb, H5T_pad_t msb)
| Sets the least and most-significant bits padding types.
herr_t | H5Tset_precision (hid_t type_id, size_t prec)
| Sets the precision of an atomic datatype.
herr_t | H5Tset_sign (hid_t type_id, H5T_sign_t sign)
| Sets the sign property for an integer type.
herr_t | H5Tset_strpad (hid_t type_id, H5T_str_t strpad)
| Defines the type of padding used for character strings.

## Function Documentation

## ◆ H5Tget_cset()

H5T_cset_t H5Tget_cset | ( | hid_t | type_id | ) |

Retrieves the character set type of a string datatype.

Parameters

  [in] | type_id | Datatype identifier

Returns
  Returns a valid character set type if successful; otherwise H5T_CSET_ERROR (-1).

H5Tget_cset() retrieves the character set type of a string datatype. Valid character set types are:

H5T_CSET_ASCII | US ASCII
H5T_CSET_UTF8 | UTF-8 Unicode encoding

Since
  1.0.0

## ◆ H5Tget_ebias()

size_t H5Tget_ebias | ( | hid_t | type_id | ) |

Retrieves the exponent bias of a floating-point type.

Parameters

  [in] | type_id | Datatype identifier

Returns
  Returns the bias if successful and 0, otherwise.

H5Tget_ebias() retrieves the exponent bias of a floating-point type.

Since
  1.0.0

## ◆ H5Tget_fields()

herr_t H5Tget_fields | ( | hid_t | type_id,
|  | size_t * | spos,
|  | size_t * | epos,
|  | size_t * | esize,
|  | size_t * | mpos,
|  | size_t * | msize )

Retrieves floating point datatype bit field information.

Parameters

  [in] | type_id | Datatype identifier
  [out] | spos | Pointer to location to return floating-point sign bit
  [out] | epos | Pointer to location to return exponent bit-position
  [out] | esize | Pointer to location to return size of exponent in bits
  [out] | mpos | Pointer to location to return mantissa bit-position
  [out] | msize | Pointer to location to return size of mantissa in bits

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

H5Tget_fields() retrieves information about the locations of the various bit fields of a floating point datatype. The field positions are bit positions in the significant region of the datatype. Bits are numbered with the least significant bit number zero. Any (or even all) of the arguments can be null pointers.

Since
  1.0.0

## ◆ H5Tget_inpad()

H5T_pad_t H5Tget_inpad | ( | hid_t | type_id | ) |

Retrieves the internal padding type for unused bits in floating-point datatypes.

Parameters

  [in] | type_id | Datatype identifier

Returns
  Returns a valid padding type if successful; otherwise returns H5T_PAD_ERROR (-1).

H5Tget_inpad() retrieves the internal padding type for unused bits in floating-point datatypes. Valid padding types are:

typedef enum H5T_pad_t {
H5T_PAD_ERROR = -1,
H5T_PAD_ZERO = 0,
H5T_PAD_ONE = 1,
H5T_PAD_BACKGROUND = 2,
H5T_NPAD = 3
} H5T_pad_t;

Since
  1.0.0

## ◆ H5Tget_norm()

H5T_norm_t H5Tget_norm | ( | hid_t | type_id | ) |

Retrieves mantissa normalization of a floating-point datatype.

Parameters

  [in] | type_id | Datatype identifier

Returns
  Returns a valid normalization type if successful; otherwise returns H5T_NORM_ERROR (-1)

H5Tget_norm() retrieves the mantissa normalization of a floating-point datatype. Valid normalization types are:

typedef enum H5T_norm_t {
H5T_NORM_ERROR = -1,
H5T_NORM_IMPLIED = 0,
H5T_NORM_MSBSET = 1,
H5T_NORM_NONE = 2
/*H5T_NORM_NONE must be last */
} H5T_norm_t;

Since
  1.0.0

## ◆ H5Tget_offset()

int H5Tget_offset | ( | hid_t | type_id | ) |

Retrieves the bit offset of the first significant bit.

Parameters

  [in] | type_id | Datatype identifier

Returns
  Returns an offset value if successful; otherwise returns a negative value.

H5Tget_offset() retrieves the bit offset of the first significant bit. The significant bits of an atomic datum can be offset from the beginning of the memory for that datum by an amount of padding. The 'offset' property specifies the number of bits of padding that appear to the "right of" the value. That is, if we have a 32-bit datum with 16-bits of precision having the value 0x1122 then it will be laid out in memory as (from small byte address toward larger byte addresses):

0: [ pad] [0x11] [0x22] [ pad]
1: [ pad] [0x22] [0x11] [ pad]
2: [0x11] [ pad] [ pad] [0x22]
3: [0x22] [ pad] [ pad] [0x11]

Since
  1.0.0

## ◆ H5Tget_order()

H5T_order_t H5Tget_order | ( | hid_t | type_id | ) |

Returns the byte order of an atomic datatype.

Parameters

  [in] | type_id | Datatype identifier

Returns
  Returns a byte order constant if successful; otherwise returns H5T_ORDER_ERROR (-1)

H5Tget_order() returns the byte order of an atomic datatype. Possible return values are:

typedef enum H5T_order_t {
H5T_ORDER_ERROR = -1,
H5T_ORDER_LE = 0,
H5T_ORDER_BE = 1,
H5T_ORDER_VAX = 2,
H5T_ORDER_MIXED = 3,
H5T_ORDER_NONE = 4
/*H5T_ORDER_NONE must be last */
} H5T_order_t;

Members of a compound datatype need not have the same byte order. If members of a compound datatype have more than one of little endian, big endian, or VAX byte order, H5Tget_order() will return H5T_ORDER_MIXED for the compound datatype. A byte order of H5T_ORDER_NONE will, however, be ignored; for example, if one or more members of a compound datatype have byte order H5T_ORDER_NONE but all other members have byte order H5T_ORDER_LE, H5Tget_order() will return H5T_ORDER_LE for the compound datatype.

Since
  1.0.0

## ◆ H5Tget_pad()

herr_t H5Tget_pad | ( | hid_t | type_id,
|  | H5T_pad_t * | lsb,
|  | H5T_pad_t * | msb )

Retrieves the padding type of the least and most-significant bit padding.

Parameters

  [in] | type_id | Datatype identifier
  [out] | lsb | Buffer for the least-significant bit padding type
  [out] | msb | Buffer for the most-significant bit padding type

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

H5Tget_pad() retrieves the padding type of the least and most-significant bit padding. Valid padding types are:

typedef enum H5T_pad_t {
H5T_PAD_ERROR = -1,
H5T_PAD_ZERO = 0,
H5T_PAD_ONE = 1,
H5T_PAD_BACKGROUND = 2,
H5T_NPAD = 3
} H5T_pad_t;

Since
  1.0.0

## ◆ H5Tget_precision()

size_t H5Tget_precision | ( | hid_t | type_id | ) |

Returns the precision of an atomic datatype.

Parameters

  [in] | type_id | Datatype identifier

Returns
  Returns the number of significant bits if successful; otherwise 0

H5Tget_precision() returns the precision of an atomic datatype (for example, integer or float) or a datatype whose base (parent) type is an atomic type (for example, array, enum and variable length). The precision is the number of significant bits which, unless padding is present, is 8 times larger than the value returned by H5Tget_size().

Since
  1.0.0

## ◆ H5Tget_sign()

H5T_sign_t H5Tget_sign | ( | hid_t | type_id | ) |

Retrieves the sign type for an integer type.

Parameters

  [in] | type_id | Datatype identifier

Returns
  Returns a valid sign type if successful; otherwise H5T_SGN_ERROR (-1)

H5Tget_sign() retrieves the sign type for an integer type. Valid types are:

typedef enum H5T_sign_t {
H5T_SGN_ERROR = -1,
H5T_SGN_NONE = 0,
H5T_SGN_2 = 1,
H5T_NSGN = 2
} H5T_sign_t;

Since
  1.0.0

## ◆ H5Tget_strpad()

H5T_str_t H5Tget_strpad | ( | hid_t | type_id | ) |

Retrieves the type of padding used for a string datatype.

Parameters

  [in] | type_id | Datatype identifier

Returns
  Returns a valid string of the padding if successful; otherwise returns H5T_STR_ERROR (-1)

H5Tget_strpad() retrieves the type of padding used for a string datatype.

The string padding type is set with H5Tset_strpad(). Possible values returned are:

H5T_STR_NULLTERM | 0 | Null terminate (as C does)
H5T_STR_NULLPAD | 1 | Pad with zeros
H5T_STR_SPACEPAD | 2 | Pad with spaces (as FORTRAN does)

Since
  1.0.0

## ◆ H5Tis_variable_str()

htri_t H5Tis_variable_str | ( | hid_t | type_id | ) |

Determines whether datatype is a variable-length string.

Parameters

  [in] | type_id | Datatype identifier

Returns
  Returns:
  - a positive value if the specified datatype is a variable-length string
  - 0 if the specified datatype is not a variable-length string
  - a negative value when the function fails
  H5Tis_variable_str() determines whether the datatype identified by `dtype_id` is a variable-length string.

This function can be used to distinguish between fixed and variable-length string datatypes.

Since
  1.6.0

## ◆ H5Tset_cset()

herr_t H5Tset_cset | ( | hid_t | type_id,
|  | H5T_cset_t | cset )

Sets character set to be used in a string or character datatype.

Parameters

  [in] | type_id | Datatype identifier
  [in] | cset | Character set type

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

H5Tset_cset() sets the character set to be used in a dataset with a string or character datatype.

Valid values for cset include the following:

H5T_CSET_ASCII | US ASCII
H5T_CSET_UTF8 | UTF-8 Unicode encoding

For example, if the character set for the datatype `type_id` is set to H5T_CSET_UTF8, string or character data of datatype dtype_id will be encoded using the UTF-8 Unicode character set.

ASCII and UTF-8 Unicode are the only currently supported character encodings. Extended ASCII encodings (for example, ISO 8859) are not supported. This encoding policy is not enforced by the HDF5 library. Using encodings other than ASCII and UTF-8 can lead to compatibility and usability problems.

Note that H5Tset_cset() sets the character set for a character or string datatype while H5Pset_char_encoding() sets the character set used for an HDF5 link or attribute name.

Since
  1.0.0

## ◆ H5Tset_ebias()

herr_t H5Tset_ebias | ( | hid_t | type_id,
|  | size_t | ebias )

Sets the exponent bias of a floating-point type.

Parameters

  [in] | type_id | Datatype identifier
  [in] | ebias | Exponent bias value

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

H5Tset_ebias() sets the exponent bias of a floating-point type.

Since
  1.0.0

## ◆ H5Tset_fields()

herr_t H5Tset_fields | ( | hid_t | type_id,
|  | size_t | spos,
|  | size_t | epos,
|  | size_t | esize,
|  | size_t | mpos,
|  | size_t | msize )

Sets locations and sizes of floating point bit fields.

Parameters

  [in] | type_id | Datatype identifier
  [in] | spos | Sign position, i.e., the bit offset of the floating-point sign bit
  [in] | epos | Exponent bit position
  [in] | esize | Size of exponent in bits
  [in] | mpos | Mantissa bit position
  [in] | msize | Size of mantissa in bits

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

H5Tset_fields() sets the locations and sizes of the various floating-point bit fields. The field positions are bit positions in the significant region of the datatype. Bits are numbered with the least significant bit number zero.

Fields are not allowed to extend beyond the number of bits of precision, nor are they allowed to overlap with one another.

Note
  The size and precision of, as well as any offset for, a floating-point datatype should generally be set appropriately before calling H5Tset_fields(). Otherwise, H5Tset_fields() may fail when checking that the values make sense for the datatype. However, if the precision of a floating-point datatype will be decreased during its creation with a call to H5Tset_precision(), then H5Tset_fields() should instead be called first to set appropriate values for `spos`, `epos`, `esize`, `mpos` and `msize` before reducing the precision of the datatype with H5Tset_precision(). This is of particular concern if another floating-point datatype was copied as a starting point.

Since
  1.0.0

## ◆ H5Tset_inpad()

herr_t H5Tset_inpad | ( | hid_t | type_id,
|  | H5T_pad_t | pad )

Fills unused internal floating-point bits.

Parameters

  [in] | type_id | Datatype identifier
  [in] | pad | Padding type

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

H5Tset_inpad() If any internal bits of a floating point-type are unused (that is, those significant bits which are not part of the sign, exponent, or mantissa), then H5Tset_inpad() will be filled according to the value of the padding value property inpad. Valid padding types are:

typedef enum H5T_pad_t {
H5T_PAD_ERROR = -1,
H5T_PAD_ZERO = 0,
H5T_PAD_ONE = 1,
H5T_PAD_BACKGROUND = 2,
H5T_NPAD = 3
} H5T_pad_t;

Since
  1.0.0

## ◆ H5Tset_norm()

herr_t H5Tset_norm | ( | hid_t | type_id,
|  | H5T_norm_t | norm )

Sets the mantissa normalization of a floating-point datatype.

Parameters

  [in] | type_id | Datatype identifier
  [in] | norm | Mantissa normalization type

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

H5Tset_norm() sets the mantissa normalization of a floating-point datatype. Valid normalization types are:

typedef enum H5T_norm_t {
H5T_NORM_ERROR = -1,
H5T_NORM_IMPLIED = 0,
H5T_NORM_MSBSET = 1,
H5T_NORM_NONE = 2
/*H5T_NORM_NONE must be last */
} H5T_norm_t;

Since
  1.0.0

## ◆ H5Tset_offset()

herr_t H5Tset_offset | ( | hid_t | type_id,
|  | size_t | offset )

Sets the bit offset of the first significant bit.

Parameters

  [in] | type_id | Datatype identifier
  [in] | offset | Offset of first significant bit

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

H5Tset_offset() sets the bit offset of the first significant bit. The significant bits of an atomic datum can be offset from the beginning of the memory for that datum by an amount of padding. The offset property specifies the number of bits of padding that appear “to the right of” the value. That is, if we have a 32-bit datum with 16-bits of precision having the value 0x1122, then it will be laid out in memory as (from small byte address toward larger byte addresses):

0: [ pad] [0x11] [0x22] [ pad]
1: [ pad] [0x22] [0x11] [ pad]
2: [0x11] [ pad] [ pad] [0x22]
3: [0x22] [ pad] [ pad] [0x11]

If the offset is incremented then the total size is incremented also if necessary to prevent significant bits of the value from hanging over the edge of the datatype.

The offset of an H5T_STRING cannot be set to anything but zero.

When called with a H5T_COMPLEX datatype, H5Tset_offset() sets the offset for the base datatype of the complex number datatype.

Since
  1.0.0

## ◆ H5Tset_order()

herr_t H5Tset_order | ( | hid_t | type_id,
|  | H5T_order_t | order )

Sets the byte order of a datatype.

Parameters

  [in] | type_id | Datatype identifier
  [in] | order | Byte order constant

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

H5Tset_order() sets the byte order of a datatype.
Byte order can currently be set to any of the following:

typedef enum H5T_order_t {
H5T_ORDER_ERROR = -1,
H5T_ORDER_LE = 0,
H5T_ORDER_BE = 1,
H5T_ORDER_VAX = 2,
H5T_ORDER_MIXED = 3,
H5T_ORDER_NONE = 4
/*H5T_ORDER_NONE must be last */
} H5T_order_t;

H5T_ORDER_MIXED (3) is a valid value for order only when returned by the function H5Tget_order(); it cannot be set with H5Tset_order().

H5T_ORDER_NONE (4) is a valid value for order, but it has no effect. It is valid only for fixed-length strings and object and region references and specifies “no particular order.”

The byte order of a derived datatype is initially the same as that of the parent type, but can be changed with H5Tset_order().

This function cannot be used with a datatype after it has been committed.

Note
  Special considerations:
  - ENUM datatypes: Byte order must be set before any member on an ENUM is defined.
  - Compound datatypes: Byte order is set individually on each member of a compound datatype; members of a compound datatype need not have the same byte order.
  - Opaque datatypes: Byte order can be set but has no effect.

Since
  1.0.0

## ◆ H5Tset_pad()

herr_t H5Tset_pad | ( | hid_t | type_id,
|  | H5T_pad_t | lsb,
|  | H5T_pad_t | msb )

Sets the least and most-significant bits padding types.

Parameters

  [in] | type_id | Datatype identifier
  [in] | lsb | Padding type for least-significant bits
  [in] | msb | Padding type for most-significant bits

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

H5Tset_pad() sets the least and most-significant bits padding types. Available values are:

H5T_PAD_ZERO | 0 | Set background to zeros
H5T_PAD_ONE | 1 | Set background to ones
H5T_PAD_BACKGROUND | 2 | Leave background alone

Since
  1.2.0

## ◆ H5Tset_precision()

herr_t H5Tset_precision | ( | hid_t | type_id,
|  | size_t | prec )

Sets the precision of an atomic datatype.

Parameters

  [in] | type_id | Datatype identifier
  [in] | prec | Number of bits of precision for datatype

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

H5Tset_precision() sets the precision of an atomic datatype. The precision is the number of significant bits which, unless padding is present, is 8 times larger than the value returned by H5Tget_size().

If the precision is increased then the offset is decreased and then the size is increased to insure that significant bits do not "hang over" the edge of the datatype.

Changing the precision of an H5T_STRING automatically changes the size as well. The precision must be a multiple of 8.

When decreasing the precision of a floating point type, set the locations and sizes of the sign, mantissa, and exponent fields first.

When called with a H5T_COMPLEX datatype, H5Tset_precision() sets the precision for the base datatype of the complex number datatype.

Since
  1.0.0

## ◆ H5Tset_sign()

herr_t H5Tset_sign | ( | hid_t | type_id,
|  | H5T_sign_t | sign )

Sets the sign property for an integer type.

Parameters

  [in] | type_id | Datatype identifier
  [in] | sign | Sign type

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

H5Tset_sign() sets the sign property for an integer type:

H5T_SGN_NONE | 0 | Unsigned integer type
H5T_SGN_2 | 1 | Two's complement signed integer type

Since
  1.0.0

## ◆ H5Tset_strpad()

herr_t H5Tset_strpad | ( | hid_t | type_id,
|  | H5T_str_t | strpad )

Defines the type of padding used for character strings.

Parameters

  [in] | type_id | Datatype identifier
  [in] | strpad | String padding type

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

H5Tset_strpad() defines the type of padding used for a string datatype.

The method used to store character strings differs with the programming language. C usually null terminates strings while Fortran left-justifies and space-pads strings.

Valid values of `strpad` are as follows:

H5T_STR_NULLTERM | 0 | Null terminate (as C does)
H5T_STR_NULLPAD | 1 | Pad with zeros
H5T_STR_SPACEPAD | 2 | Pad with spaces (as FORTRAN does)

When converting from a longer string to a shorter string, the behavior is as follows. If the shorter string is H5T_STR_NULLPAD or H5T_STR_SPACEPAD, then the string is simply truncated. If the short string is H5T_STR_NULLTERM, it is truncated and a null terminator is appended.

When converting from a shorter string to a longer string, the longer string is padded on the end by appending nulls or spaces.

Since
  1.0.0