Last modified: 11 May 2015
Name: H5Oget_info
Signature:
  herr_t `H5Oget_info`( hid_t `object_id`, H5O_info_t *`object_info` )

Purpose:
  Retrieves the metadata for an object specified by an identifier.

Description:
  `H5Oget_info` specifies an object by its identifier, `object_id`, and retrieves the metadata describing that object in `object_info`, an H5O_info_t struct.

  An H5O_info_t struct is defined (in `H5Opublic.h`) as follows :

      typedef struct H5O_info_t {
          unsigned long       fileno;     /* Number of file where object is       */
                                          /*   located                            */
          haddr_t             addr;       /* Object address in file               */
          H5O_type_t          type;       /* Basic object type                    */
                                          /*   (See H5O_type_t below)             */
          unsigned            rc;         /* Reference count of object            */
          time_t              atime;      /* Access time                          */
          time_t              mtime;      /* Modification time                    */
          time_t              ctime;      /* Change time                          */
          time_t              btime;      /* Birth time                           */
          hsize_t             num_attrs;  /* # of attributes attached to object   */
          H5O_hdr_info_t      hdr         /* Object header information            */
                                          /*   (See H5O_hdr_info_t below)         */
          struct {
                                          /* Extra metadata storage for obj &     */
                                          /*   attributes                         */
              H5_ih_info_t    obj;        /* v1/v2 B-tree & local/fractal heap    */
                                          /*   for groups, B-tree for chunked     */
                                          /*   datasets.                          */
                                          /*   For internal library use only.     */
              H5_ih_info_t    attr;       /* v2 B-tree & heap for attributes.     */
                                          /*   For internal library use only.     */
          } meta_size;
      } H5O_info_t;

  Note the following about `H50_info_t`:

  Of the four time fields (`atime`, `mtime`, `ctime`, and `btime`) only `ctime` has been implemented.

  The `atime` value is the last time the object was read or written.

  The `mtime` value is the last time the raw data in the object was changed.

  The `ctime` value is the last time the metadata for the object was changed.

  The `btime` value is the time the object was created.

  The fields nested in the `meta_size` field are for internal library use only.

  An H5O_type_t enum indicates the object type and is defined (in `H5Opublic.h`) as follows:

      typedef enum H5O_type_t {
          H5O_TYPE_UNKNOWN = -1,      /* Unknown object type                      */
          H5O_TYPE_GROUP,             /* Object is a group                        */
          H5O_TYPE_DATASET,           /* Object is a dataset                      */
          H5O_TYPE_NAMED_DATATYPE,    /* Object is a committed (named) datatype   */
          H5O_TYPE_NTYPES             /* Number of different object types (must   */
                                      /* be last!)                                */
      } H5O_type_t;

  Note that `object_id` refers only to the types specified by `H5O_type_t`.

  An H5O_hdr_info_t struct holds object header metadata and is defined (in `H5Opublic.h`) as follows:

      typedef struct H5O_hdr_info_t {
          unsigned version;           /* Version number of header format in file  */
          unsigned nmesgs;            /* Number of object header messages         */
          unsigned nchunks;           /* Number of object header chunks           */
          unsigned flags;             /* Object header status flags               */
          struct {
              hsize_t total;          /* Total space for storing object header in */
                                      /*   file                                   */
              hsize_t meta;           /* Space within header for object header    */
                                      /*   metadata information                   */
              hsize_t mesg;           /* Space within header for actual message   */
                                      /*   information                            */
              hsize_t free;           /* Free space within object header          */
          } space;
          struct {
              uint64_t present;       /* Flags to indicate presence of message    */
                                      /*   type in header                         */
              uint64_t shared;        /* Flags to indicate message type is        */
                                      /*   shared in header                       */
          } mesg;
      } H5O_hdr_info_t;

  Valid values for the `version` field are `H5O_VERSION_1` and `H5O_VERSION_2`. Version 2 of the object header is smaller and more efficient than version 1.

  Note that the information held by H5O_hdr_info_t might be useful only to developers with extensive HDF5 experience.

Parameters:

  hid_t `object_id` | IN: Identifier for object of type specified by `H5O_type_t`
  H5O_info_t *`object_info` | OUT: Buffer in which to return object information

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

Fortran2003 Interface: h5oget_info_f

  Related Fortran2003 Derived Type: h5o_info_t

History:

  Release | Change
  1.8.15 | Added a note about the valid values for the `version` field in the H5O_hdr_info_t structure.
  1.8.11 | Fortran subroutine introduced in this release.
  1.8.10 | Added H5O_type_t structure to the Description section. Separated H5O_hdr_info_t structure from H5O_info_t in the Description section. Clarified the definition and implementation of the time fields.
  1.8.0 | Function introduced in this release.