mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-09-25 04:09:44 +03:00
Scot Breitenfeld
05676d1abe
* Consolidate documentation under doc/ directory
Move user-facing guides from release_docs/ and doxygen/ into a single
doc/ root. release_docs/ now holds only release artifacts (changelogs,
history, release process, maintainer info).
- git mv release_docs/INSTALL*.md, USING_*.md, README_HPC.md,
BuildSystemNotes.md, AutotoolsToCMakeOptions.md,
HDF5_Library_2.0.0_Migration_Guide.md → doc/
- git mv doxygen/ → doc/doxygen/
- Update CMakeLists.txt: HDF5_DOXYGEN_DIR and add_subdirectory path
- Update CMakeInstallation.cmake: all install paths for moved files
- Update bin/make_vers: hardcoded doxygen/ path substitution
- Update doc/doxygen/CMakeLists.txt: EXAMPLES_DIRECTORY and comments
- Update README.md, CONTRIBUTING.md, SECURITY.md, config/README.md,
release_docs/RELEASE_PROCESS.md: links to moved files
- Update doxygen .dox files: release_docs/ URLs for moved guides
- Rewrite release_docs/README.md for narrowed scope
* Add HDF5_DOCS_DIR variable for doc/ root path
Introduce HDF5_DOCS_DIR = \${HDF5_SOURCE_DIR}/doc so that
CMakeInstallation.cmake and future callers reference the doc/
directory symbolically rather than by hardcoded path.
HDF5_DOXYGEN_DIR is now derived from HDF5_DOCS_DIR.
104 lines
4.4 KiB
Plaintext
104 lines
4.4 KiB
Plaintext
/** \page UsingIdentifiers Using Identifiers
|
||
*
|
||
* Navigate back: \ref index "Main" / \ref UG / \ref AR_UG
|
||
* <hr>
|
||
*
|
||
* \section sec_using_identifiers Using Identifiers
|
||
*
|
||
* The purpose of this topic is to describe how identifiers behave and how they should be treated by application programs.
|
||
*
|
||
* When an application program uses the HDF5 library to create or open an item, a unique identifier is
|
||
* returned. The items that return a unique identifier when they are created or opened include the following:
|
||
* \li dataset
|
||
* \li group
|
||
* \li datatype
|
||
* \li dataspace
|
||
* \li file
|
||
* \li attribute
|
||
* \li property list
|
||
* \li referenced object
|
||
* \li error stack
|
||
* \li error message
|
||
*
|
||
* An application may open one of the items listed above more than once at the same time. For example, an
|
||
* application might open a group twice, receiving two identifiers. Information from one dataset in the
|
||
* group could be handled through one identifier, and the information from another dataset in the group
|
||
* could be handled by a different identifier.
|
||
*
|
||
* An application program should track every identifier it receives as a result of creating or opening one of
|
||
* the items listed above. In order for an application to close properly, it must release every identifier it
|
||
* has opened. If an application opened a group twice for example, it would need to issue two #H5Gclose
|
||
* commands, one for each identifier. Not releasing identifiers causes resource leaks. Until an identifier
|
||
* is released, the item associated with the identifier is still open.
|
||
*
|
||
* The library considers a file open until all of the identifiers associated with the file and with the file’s
|
||
* various items have been released. The identifiers associated with these open items must be released separately.
|
||
* This means that an application can close a file and still work with one or more portions of the file. Suppose
|
||
* an application opened a file, a group within the file, and two datasets within the group. If the application
|
||
* closed the file with #H5Fclose, then the file would be considered closed to the application, but the group
|
||
* and two datasets would still be open.
|
||
*
|
||
* There are several exceptions to the above file closing rule. One is when the #H5close function is used
|
||
* instead of #H5Fclose. #H5close causes a general shut down of the library: all data is written to disk,
|
||
* all identifiers are closed, and all memory used by the library is cleaned up. Another exception occurs on
|
||
* parallel processing systems. Suppose on a parallel system an application has opened a file, a group in the
|
||
* file, and two datasets in the group. If the application uses the #H5Fclose function to close the file, the
|
||
* call will fail with an error. The open group and datasets must be closed before the file can be closed.
|
||
* A third exception is when the file access property list includes the property #H5F_CLOSE_STRONG. This
|
||
* property causes the closing of all of the file’s open items when the file is closed with #H5Fclose. For
|
||
* more information about #H5close, #H5Fclose, and #H5Pset_fclose_degree, see the \ref RM.
|
||
*
|
||
* The reference manual entries for functions that return identifiers describe what might be returned as
|
||
* follows:
|
||
* \b Returns:
|
||
* Returns an identifier if successful; otherwise returns a negative value.
|
||
*
|
||
* In other words, a successful operation will return a non-negative identifier which will never be 0
|
||
* (zero) and will always be a positive value.
|
||
*
|
||
* \subsection subsec_using_identifiers_func Functions that Return Identifiers
|
||
*
|
||
* Some of the functions that return identifiers are listed below.
|
||
*
|
||
* \li #H5Acreate
|
||
* \li #H5Acreate_by_name
|
||
* \li #H5Aget_type
|
||
* \li #H5Aopen
|
||
* \li #H5Aopen_by_idx
|
||
* \li #H5Aopen_by_name
|
||
* \li #H5Dcreate
|
||
* \li #H5Dcreate_anon
|
||
* \li #H5Dget_access_plist
|
||
* \li #H5Dget_create_plist
|
||
* \li #H5Dget_space
|
||
* \li #H5Dget_type
|
||
* \li #H5Dopen
|
||
* \li #H5Ecreate_msg
|
||
* \li #H5Ecreate_stack
|
||
* \li #H5Fcreate
|
||
* \li #H5Fopen
|
||
* \li #H5Freopen
|
||
* \li #H5Gcreate
|
||
* \li #H5Gcreate_anon
|
||
* \li #H5Gopen
|
||
* \li #H5Oopen
|
||
* \li #H5Oopen_by_addr
|
||
* \li #H5Oopen_by_idx
|
||
* \li #H5Pcreate
|
||
* \li #H5Pget_virtual_srcspace
|
||
* \li #H5Pget_virtual_vspace
|
||
* \li #H5Rdereference
|
||
* \li #H5Rget_region
|
||
* \li #H5Screate
|
||
* \li #H5Screate_simple
|
||
* \li #H5Tcopy
|
||
* \li #H5Tcreate
|
||
* \li #H5Tdecode
|
||
* \li #H5Tget_member_type
|
||
* \li #H5Tget_super
|
||
* \li #H5Topen
|
||
*
|
||
* <hr>
|
||
* Navigate back: \ref index "Main" / \ref UG / \ref AR_UG
|
||
*/
|