

<!--
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  * Copyright by The HDF Group.                                               *
  * Copyright by the Board of Trustees of the University of Illinois.         *
  * All rights reserved.                                                      *
  *                                                                           *
  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
  * terms governing use, modification, and redistribution, is contained in    *
  * the files COPYING and Copyright.html.  COPYING can be found at the root   *
  * of the source code distribution tree; Copyright.html can be found at the  *
  * root level of an installed copy of the electronic HDF5 document set and   *
  * is linked from the top-level documents page.  It can also be found at     *
  * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
  * access to either file, you may request a copy from help@hdfgroup.org.     *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 -->


<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Rget_name" -->
<hr>
<dl>

<dt><div align=right><font color=999999 size=-1><i>
    Last modified: 5 February 2013
    </i></font></div>
<br />
<dt><strong>Name:</strong> <a name="Reference-GetName">H5Rget_name</a></dt>
<br />
<dt><strong>Signature:</strong>
    <dd><code><em>ssize_t</em> H5Rget_name(<em>hid_t</em> loc_id,
                     <em>H5R_type_t</em> ref_type,
                     <em>void</em> *ref,
                     <em>char</em> *name,
                     <em>size_t</em> size)</code>

<p>
<dt><strong>Purpose:</strong> </dt>
    <dd>Retrieves a name for a referenced object.

<p>
<dt><strong>Description:</strong>
    <dd><code>H5Rget_name</code> retrieves a name for the object identified 
        by <code>ref</code>.
        <p>
        <code>loc_id</code> is used to identify the file containing the 
        reference.  It can be the file identifier for the file containing 
        the reference or an identifier for any object in that file.
        <p>
        <code>H5R_type_t</code> is the reference type of <code>ref</code>.
        Valid values include the following:
        <table border="0">
          <tr align=left valign=top><td>&nbsp;&nbsp;&nbsp;&nbsp;</td><td>
            <code>H5R_OBJECT</code></td><td>
            Object reference
          </td></tr>
          <tr align=left valign=top><td>&nbsp;</td><td>
            <code>H5R_DATASET_REGION&nbsp;&nbsp;</code></td><td>
            Dataset region reference
          </td></tr>
        </table>
        <p>
        <code>ref</code> is the reference for which the target object&rsquo;s 
        name is sought.
        <p>
        If <code>ref</code> is an object reference, <code>name</code> 
        will be returned with a name for the referenced object.
        If <code>ref</code> is a dataset region reference, 
        <code>name</code> will contain a name for the object containing 
        the referenced region.
        <p>
        Up to <code>size</code> characters of the name are returned in 
        <code>name</code>; additional characters, if any, are not returned
        to the user application.
        <p>
        If the length of the name, which determines the required 
        value of <code>size</code>, is unknown, a preliminary  
        <code>H5Rget_name</code> call can be made.  
        The return value of this call will be the size of the 
        object name.  
        That value can then be assigned to <code>size</code> 
        for a second <code>H5Rget_name</code> call, 
        which will retrieve the actual name.
        <p>
        If there is no name associated with the object identifier
        or if the name is <code>NULL</code>, <code>H5Rget_name</code>
        returns the size of the name buffer (the size does not include 
        the NULL terminator).
        <p>
        Note that an object in an HDF5 file may have multiple paths if there
        are multiple links pointing to it.  This function may return any one 
        of these paths.

<p>
<dt><strong>Parameters:</strong> 
    <dd><table width="100%">
      <tr>
        <td valign="top" width="30%"><code><em>hid_t</em> loc_id</code></td>
        <td valign="top" width="70%">IN: Identifier for the file containing the reference
            or for any object in that file.
            </td></tr>
      <tr>
        <td valign="top"><code><em>H5R_type_t</em> ref_type</code></td>
        <td valign="top">IN: Type of reference.
      <tr>
        <td valign="top"><code><em>void</em> *ref</code></td> 
        <td valign="top">IN: An object or dataset region reference.</td></tr>
      <tr>
        <td valign="top"><code><em>char</em> *name</code></td> 
        <td valign="top">OUT: A buffer to place the name of the referenced object or 
            dataset region. If NULL, then this call will return the size 
            in bytes of the name.</td></tr>
      <tr>
        <td valign="top"><code><em>size_t</em> size</code></td> 
        <td valign="top">IN: The size of the <code>name</code> buffer. When the 
        size is passed in, the NULL terminator needs to be included.</td></tr>
    </table></dd>

<p>
<dt><strong>Returns:</strong> 
    <dd>Returns the length of the name if successful, returning <code>0</code> 
        (zero) if no name is associated with the identifier.
        Otherwise returns a negative value.
<!-- NEW PAGE -->

<p>
<dt><strong>Fortran90 Interface:</strong> h5rget_name_object_f or h5rget_name_region_f

    <dd>
    <p><strong>To get name of an object reference:</strong> h5rget_name_object_f
    <br>

        <?php include("H5R/h5rget_name_object_f_F90.htm"); ?>

    <p>&nbsp;
    <p><strong>To get name of a region reference:</strong> h5rget_name_region_f
    <br>

        <?php include("H5R/h5rget_name_region_f_F90.htm"); ?>

<p>
<dt><strong>Fortran2003 Interface:</strong> h5rget_name_f
    <dd>

        <?php include("H5R/h5rget_name_f_F03.htm"); ?>


<p>
<dt><strong>History:</strong>
    <ul><table width="90%">
        <tr>
          <td valign="top" align="left" width="10%">
            <strong>Release</strong>&nbsp;&nbsp;&nbsp;&nbsp;</td>
          <td valign="top" align="left">
            <strong>Change</strong></td></tr>
        <tr>
          <td valign="top">1.8.8</td>
          <td valign="top">
            Fortran updated to Fortran2003.</td></tr>
        <tr>
          <td valign="top">1.8.0</td>
          <td valign="top">
            C function introduced in this release.</td></tr>
    </table></ul>
</dl>


