Last modified: 10 April 2013
Name: H5Oget_comment_by_name
Signature:
  ssize_t `H5Oget_comment_by_name`( hid_t `loc_id`, const char *`name`, char *`comment`, size_t `bufsize`, hid_t `lapl_id` )

Purpose:
  Retrieves comment for specified object.

Description:
  `H5Oget_comment_by_name` retrieves the comment for an object in the buffer `comment`.

  The target object is specified by `loc_id` and `name`. `loc_id` can specify any object in the file. `name` can be one of the following:
  — The name of the object relative to `loc_id`
  — An absolute name of the object, starting from `/`, the file’s root group
  — A dot (`.`), if `loc_id` fully specifies the object

  The size in bytes of the comment, including the `NULL` terminator, is specified in `bufsize`. If `bufsize` is unknown, a preliminary `H5Oget_comment_by_name` call with the pointer `comment` set to `NULL` will return the size of the comment without the `NULL` terminator.

  If `bufsize` is set to a smaller value than described above, only `bufsize` bytes of the comment, without a `NULL` terminator, are returned in `comment`.

  If an object does not have a comment, the empty string is returned in `comment`.

  `lapl_id` contains a link access property list identifier. A link access propety list can come into play when traversing links to access an object.

Parameters:

  hid_t `loc_id` | IN: Identifier of a file, group, dataset, or named datatype.
  const char *`name` | IN: Name of the object whose comment is to be retrieved, specified as a path relative to `loc_id`. `name` can be '.' (a dot) if `loc_id` fully specifies the object for which the associated comment is to be retrieved.
  char *`comment` | OUT: The comment.
  size_t `bufsize` | IN: Anticipated required size of the `comment` buffer.
  hid_t `lapl_id` | IN: Link access property list identifier.

Returns:
  Upon success, returns the number of characters in the comment, not including the `NULL` terminator, or zero (`0`) if the object has no comment. The value returned may be larger than `bufsize`. Otherwise returns a negative value.

Fortran90 Interface: h5oget_comment_by_name_f

History:

  Release | C
  1.8.11 | Fortran subroutine introduced in this release.
  1.8.0 | Function introduced in this release.