diff options
171 files changed, 6857 insertions, 3020 deletions
diff --git a/CMakeLists.txt b/CMakeLists.txt index c3488f2..662d050 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -575,20 +575,6 @@ endif () # endif () #----------------------------------------------------------------------------- -# Option to build documentation -#----------------------------------------------------------------------------- -option (HDF5_BUILD_DOC "Build documentation" OFF) -if (HDF5_BUILD_DOC AND EXISTS "${HDF5_DOXYGEN_DIR}" AND IS_DIRECTORY "${HDF5_DOXYGEN_DIR}") -# check if Doxygen is installed - find_package(Doxygen) - if (DOXYGEN_FOUND) - message(STATUS "Doxygen version: ${DOXYGEN_VERSION}") - else () - message(STATUS "Doxygen needs to be installed to generate the doxygen documentation") - endif () -endif () - -#----------------------------------------------------------------------------- # Option to indicate using a memory checker #----------------------------------------------------------------------------- option (HDF5_ENABLE_USING_MEMCHECKER "Indicate that a memory checker is used" OFF) @@ -929,6 +915,21 @@ if (HDF5_ALLOW_EXTERNAL_SUPPORT MATCHES "GIT" OR HDF5_ALLOW_EXTERNAL_SUPPORT MAT endif () #----------------------------------------------------------------------------- +# Option to build documentation +#----------------------------------------------------------------------------- +option (HDF5_BUILD_DOC "Build documentation" OFF) +if (HDF5_BUILD_DOC AND EXISTS "${HDF5_DOXYGEN_DIR}" AND IS_DIRECTORY "${HDF5_DOXYGEN_DIR}") +# check if Doxygen is installed + find_package(Doxygen) + if (DOXYGEN_FOUND) + message(STATUS "Doxygen version: ${DOXYGEN_VERSION}") + add_subdirectory (doxygen) + else () + message(STATUS "Doxygen needs to be installed to generate the doxygen documentation") + endif () +endif () + +#----------------------------------------------------------------------------- # Dashboard and Testing Settings #----------------------------------------------------------------------------- option (BUILD_TESTING "Build HDF5 Unit Testing" ON) @@ -211,9 +211,10 @@ ./doc/branches-explained.md ./doc/code-conventions.md ./doc/contributing.md - ./doxygen/aliases +./doxygen/CMakeLists.txt ./doxygen/Doxyfile.in +./doxygen/dox/APIVersions.dox ./doxygen/dox/About.dox ./doxygen/dox/Cookbook.dox ./doxygen/dox/DDLBNF110.dox @@ -221,30 +222,23 @@ ./doxygen/dox/FileFormatSpec.dox ./doxygen/dox/GettingStarted.dox ./doxygen/dox/H5AC_cache_config_t.dox -./doxygen/dox/H5Acreate.dox -./doxygen/dox/H5Aiterate.dox -./doxygen/dox/H5Fget_info.dox -./doxygen/dox/H5Lget_info_by_idx.dox -./doxygen/dox/H5Lget_info.dox -./doxygen/dox/H5Literate_by_name.dox -./doxygen/dox/H5Literate.dox -./doxygen/dox/H5Lvisit_by_name.dox -./doxygen/dox/H5Lvisit.dox -./doxygen/dox/H5Oget_info_by_idx.dox -./doxygen/dox/H5Oget_info_by_name.dox -./doxygen/dox/H5Oget_info.dox -./doxygen/dox/H5Ovisit_by_name.dox -./doxygen/dox/H5Ovisit.dox -./doxygen/dox/H5Sencode.dox ./doxygen/dox/MetadataCachingInHDF5.dox ./doxygen/dox/OtherSpecs.dox ./doxygen/dox/Overview.dox ./doxygen/dox/ReferenceManual.dox +./doxygen/dox/RFC.dox ./doxygen/dox/Specifications.dox ./doxygen/dox/TechnicalNotes.dox ./doxygen/dox/api-compat-macros.dox ./doxygen/dox/maybe_metadata_reads.dox ./doxygen/dox/rm-template.dox +./doxygen/dox/cookbook/Accessibility.c +./doxygen/dox/cookbook/Accessibility.dox +./doxygen/dox/cookbook/Attributes.c +./doxygen/dox/cookbook/Attributes.dox +./doxygen/dox/cookbook/Files.c +./doxygen/dox/cookbook/Files.dox +./doxygen/dox/cookbook/Performance.dox ./doxygen/examples/FF-IH_FileGroup.gif ./doxygen/examples/FF-IH_FileObject.gif ./doxygen/examples/FileFormatSpecChunkDiagram.jpg @@ -256,13 +250,25 @@ ./doxygen/examples/H5.format.html ./doxygen/examples/H5A_examples.c ./doxygen/examples/H5D_examples.c +./doxygen/examples/H5E_examples.c ./doxygen/examples/H5Fclose.c ./doxygen/examples/H5Fcreate.c ./doxygen/examples/H5F_examples.c +./doxygen/examples/H5G_examples.c +./doxygen/examples/H5I_examples.c +./doxygen/examples/H5L_examples.c +./doxygen/examples/H5O_examples.c +./doxygen/examples/H5PL_examples.c ./doxygen/examples/H5Pget_metadata_read_attempts.1.c ./doxygen/examples/H5Pget_metadata_read_attempts.2.c ./doxygen/examples/H5Pget_metadata_read_attempts.3.c ./doxygen/examples/H5Pget_object_flush_cb.c +./doxygen/examples/H5P_examples.c +./doxygen/examples/H5R_examples.c +./doxygen/examples/H5S_examples.c +./doxygen/examples/H5T_examples.c +./doxygen/examples/H5Z_examples.c +./doxygen/examples/H5_examples.c ./doxygen/examples/ImageSpec.html ./doxygen/examples/PaletteExample1.gif ./doxygen/examples/Palettes.fm.anc.gif @@ -3576,6 +3582,7 @@ ./config/cmake/HDF5PluginMacros.cmake ./config/cmake/HDF5PluginCache.cmake ./config/cmake/HDF5UseFortran.cmake +./config/cmake/javaTargets.cmake.in ./config/cmake/jrunTest.cmake ./config/cmake/jvolTest.cmake ./config/cmake/libh5cc.in diff --git a/bin/release b/bin/release index 0726b8c..8774851 100755 --- a/bin/release +++ b/bin/release @@ -235,7 +235,7 @@ tar2cmakezip() # step 3: add LIBAEC.tar.gz, ZLib.tar.gz and cmake files cp /mnt/scr1/pre-release/hdf5/CMake/LIBAEC.tar.gz $cmziptmpsubdir cp /mnt/scr1/pre-release/hdf5/CMake/ZLib.tar.gz $cmziptmpsubdir - cp /mnt/scr1/pre-release/hdf5/CMake/HDF5Examples-1.14.3-Source.zip $cmziptmpsubdir + cp /mnt/scr1/pre-release/hdf5/CMake/HDF5Examples-1.14.4-Source.zip $cmziptmpsubdir cp /mnt/scr1/pre-release/hdf5/CMake/hdf5_plugins-master.zip $cmziptmpsubdir cp $cmziptmpsubdir/$version/config/cmake/scripts/CTestScript.cmake $cmziptmpsubdir cp $cmziptmpsubdir/$version/config/cmake/scripts/HDF5config.cmake $cmziptmpsubdir @@ -331,7 +331,7 @@ tar2cmaketgz() # step 3: add LIBAEC.tar.gz, ZLib.tar.gz and cmake files cp /mnt/scr1/pre-release/hdf5/CMake/LIBAEC.tar.gz $cmgztmpsubdir cp /mnt/scr1/pre-release/hdf5/CMake/ZLib.tar.gz $cmgztmpsubdir - cp /mnt/scr1/pre-release/hdf5/CMake/HDF5Examples-1.14.3-Source.tar.gz $cmgztmpsubdir + cp /mnt/scr1/pre-release/hdf5/CMake/HDF5Examples-1.14.4-Source.tar.gz $cmgztmpsubdir cp /mnt/scr1/pre-release/hdf5/CMake/hdf5_plugins-master.tar.gz $cmgztmpsubdir cp $cmgztmpsubdir/$version/config/cmake/scripts/CTestScript.cmake $cmgztmpsubdir cp $cmgztmpsubdir/$version/config/cmake/scripts/HDF5config.cmake $cmgztmpsubdir @@ -415,7 +415,7 @@ tar2hpccmaketgz() # step 3: add LIBAEC.tar.gz, ZLib.tar.gz and cmake files cp /mnt/scr1/pre-release/hdf5/CMake/LIBAEC.tar.gz $cmgztmpsubdir cp /mnt/scr1/pre-release/hdf5/CMake/ZLib.tar.gz $cmgztmpsubdir - cp /mnt/scr1/pre-release/hdf5/CMake/HDF5Examples-1.14.3-Source.tar.gz $cmgztmpsubdir + cp /mnt/scr1/pre-release/hdf5/CMake/HDF5Examples-1.14.4-Source.tar.gz $cmgztmpsubdir cp /mnt/scr1/pre-release/hdf5/CMake/hdf5_plugins-master.tar.gz $cmgztmpsubdir cp $cmgztmpsubdir/$version/config/cmake/scripts/CTestScript.cmake $cmgztmpsubdir cp $cmgztmpsubdir/$version/config/cmake/scripts/HDF5config.cmake $cmgztmpsubdir diff --git a/config/cmake/HDF5_Examples.cmake.in b/config/cmake/HDF5_Examples.cmake.in index d77e2df..2d8dc58 100644 --- a/config/cmake/HDF5_Examples.cmake.in +++ b/config/cmake/HDF5_Examples.cmake.in @@ -77,7 +77,7 @@ set(ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DSITE:STRING=${CTEST_SITE} -DBUILDN #TAR_SOURCE - name of tarfile #if(NOT DEFINED TAR_SOURCE) -# set(CTEST_USE_TAR_SOURCE "HDF5Examples-1.14.3-Source") +# set(CTEST_USE_TAR_SOURCE "HDF5Examples-1.14.4-Source") #endif() ############################################################################################################### diff --git a/config/cmake/HDFCXXCompilerFlags.cmake b/config/cmake/HDFCXXCompilerFlags.cmake index a121d0a..e76150f 100644 --- a/config/cmake/HDFCXXCompilerFlags.cmake +++ b/config/cmake/HDFCXXCompilerFlags.cmake @@ -27,15 +27,14 @@ if (WIN32 AND CMAKE_CXX_COMPILER_ID STREQUAL "Intel") set (_INTEL_WINDOWS 1) endif () -if (WIN32 AND CMAKE_CXX_COMPILER_ID STREQUAL "Clang" - AND "x${CMAKE_CXX_SIMULATE_ID}" STREQUAL "xMSVC") +if (WIN32 AND CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang" AND "x${CMAKE_CXX_SIMULATE_ID}" STREQUAL "xMSVC") set (_CLANG_MSVC_WINDOWS 1) endif() # MSVC 14.28 enables C5105, but the Windows SDK 10.0.18362.0 triggers it. -if (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC" AND CMAKE_CXX_COMPILER_LOADED) +if ((_CLANG_MSVC_WINDOWS OR CMAKE_CXX_COMPILER_ID STREQUAL "MSVC") AND CMAKE_CXX_COMPILER_LOADED) set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /EHsc") - if (NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS 19.28) + if (CMAKE_CXX_COMPILER_ID STREQUAL "MSVC" AND NOT CMAKE_CXX_COMPILER_VERSION VERSION_LESS 19.28) set (CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -wd5105") endif () endif () @@ -140,7 +139,7 @@ else () ADD_H5_FLAGS (H5_CXXFLAGS "${HDF5_SOURCE_DIR}/config/gnu-warnings/cxx-noerror-general") endif () endif () - elseif (CMAKE_CXX_COMPILER_ID STREQUAL "Clang") + elseif (CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") ADD_H5_FLAGS (HDF5_CMAKE_CXX_FLAGS "${HDF5_SOURCE_DIR}/config/clang-warnings/general") elseif (CMAKE_CXX_COMPILER_ID STREQUAL "PGI") list (APPEND HDF5_CMAKE_CXX_FLAGS "-Minform=inform") @@ -161,14 +160,14 @@ if (HDF5_ENABLE_DEV_WARNINGS) elseif (CMAKE_CXX_COMPILER_ID STREQUAL "GNU") # Use the C warnings as CXX warnings are the same ADD_H5_FLAGS (H5_CXXFLAGS "${HDF5_SOURCE_DIR}/config/gnu-warnings/developer-general") - elseif (CMAKE_CXX_COMPILER_ID STREQUAL "Clang") + elseif (CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") ADD_H5_FLAGS (H5_CXXFLAGS "${HDF5_SOURCE_DIR}/config/clang-warnings/developer-general") endif () else () if (CMAKE_CXX_COMPILER_ID STREQUAL "GNU") # Use the C warnings as CXX warnings are the same ADD_H5_FLAGS (H5_CXXFLAGS "${HDF5_SOURCE_DIR}/config/gnu-warnings/no-developer-general") - elseif (CMAKE_CXX_COMPILER_ID STREQUAL "Clang") + elseif (CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") ADD_H5_FLAGS (H5_CXXFLAGS "${HDF5_SOURCE_DIR}/config/clang-warnings/no-developer-general") endif () endif () diff --git a/config/cmake/HDFCompilerFlags.cmake b/config/cmake/HDFCompilerFlags.cmake index de5b563..210e475 100644 --- a/config/cmake/HDFCompilerFlags.cmake +++ b/config/cmake/HDFCompilerFlags.cmake @@ -24,8 +24,7 @@ if(WIN32 AND CMAKE_C_COMPILER_ID STREQUAL "Intel") set(_INTEL_WINDOWS 1) endif() -if(WIN32 AND CMAKE_C_COMPILER_ID STREQUAL "Clang" - AND "x${CMAKE_C_SIMULATE_ID}" STREQUAL "xMSVC") +if(WIN32 AND CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" AND "x${CMAKE_C_SIMULATE_ID}" STREQUAL "xMSVC") set(_CLANG_MSVC_WINDOWS 1) endif() diff --git a/config/cmake/HDFFortranCompilerFlags.cmake b/config/cmake/HDFFortranCompilerFlags.cmake index 18ab621..94c40aa 100644 --- a/config/cmake/HDFFortranCompilerFlags.cmake +++ b/config/cmake/HDFFortranCompilerFlags.cmake @@ -91,9 +91,10 @@ if (NOT MSVC AND NOT MINGW) #endif () # Append more extra warning flags that only gcc 5.x+ knows about - if (NOT CMAKE_Fortran_COMPILER_VERSION VERSION_LESS 5.0) - ADD_H5_FLAGS (HDF5_CMAKE_Fortran_FLAGS "${HDF5_SOURCE_DIR}/config/gnu-warnings/gfort-5") - endif () + # do not include -Wuse-without-only + #if (NOT CMAKE_Fortran_COMPILER_VERSION VERSION_LESS 5.0) + # ADD_H5_FLAGS (HDF5_CMAKE_Fortran_FLAGS "${HDF5_SOURCE_DIR}/config/gnu-warnings/gfort-5") + #endif () # Append more extra warning flags that only gcc 6.x+ knows about if (NOT CMAKE_Fortran_COMPILER_VERSION VERSION_LESS 6.0) diff --git a/config/cmake/README.txt.cmake.in b/config/cmake/README.txt.cmake.in index f621515..9289870 100644 --- a/config/cmake/README.txt.cmake.in +++ b/config/cmake/README.txt.cmake.in @@ -75,6 +75,6 @@ For more information see USING_CMake_Examples.txt in the install folder. =========================================================================== Documentation for this release can be found at the following URL: - https://portal.hdfgroup.org/display/support + https://portal.hdfgroup.org/display/HDF5/HDF5 Bugs should be reported to help@hdfgroup.org. diff --git a/config/cmake/UseJava.cmake b/config/cmake/UseJava.cmake index 375004e..2351ce8 100644 --- a/config/cmake/UseJava.cmake +++ b/config/cmake/UseJava.cmake @@ -4,369 +4,516 @@ UseJava ------- -Use Module for Java - -This file provides functions for Java. It is assumed that +This file provides support for ``Java``. It is assumed that :module:`FindJava` has already been loaded. See :module:`FindJava` for -information on how to load Java into your CMake project. +information on how to load Java into your ``CMake`` project. + +Synopsis +^^^^^^^^ + +.. parsed-literal:: + + `Creating and Installing JARS`_ + `add_jar`_ (<target_name> [SOURCES] <source1> [<source2>...] ...) + `install_jar`_ (<target_name> DESTINATION <destination> [COMPONENT <component>]) + `install_jni_symlink`_ (<target_name> DESTINATION <destination> [COMPONENT <component>]) + + `Header Generation`_ + `create_javah`_ ((TARGET <target> | GENERATED_FILES <VAR>) CLASSES <class>... ...) + + `Exporting JAR Targets`_ + `install_jar_exports`_ (TARGETS <jars>... FILE <filename> DESTINATION <destination> ...) + `export_jars`_ (TARGETS <jars>... [NAMESPACE <namespace>] FILE <filename>) + + `Finding JARs`_ + `find_jar`_ (<VAR> NAMES <name1> [<name2>...] [PATHS <path1> [<path2>... ENV <var>]] ...) + + `Creating Java Documentation`_ + `create_javadoc`_ (<VAR> (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...]) ...) Creating And Installing JARs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code-block:: cmake +.. _add_jar: - add_jar(<target_name> - [SOURCES] <source1> [<source2>...] [<resource1>...] - [INCLUDE_JARS <jar1> [<jar2>...]] - [ENTRY_POINT <entry>] - [VERSION <version>] - [OUTPUT_NAME <name>] - [OUTPUT_DIR <dir>] - [GENERATE_NATIVE_HEADERS <target> [DESTINATION <dir>]] - ) +.. command:: add_jar -This command creates a ``<target_name>.jar``. It compiles the given -``<source>`` files and adds the given ``<resource>`` files to -the jar file. Source files can be java files or listing files -(prefixed by ``@``). If only resource files are given then just a jar file -is created. The list of ``INCLUDE_JARS`` are added to the classpath when -compiling the java sources and also to the dependencies of the target. -``INCLUDE_JARS`` also accepts other target names created by ``add_jar()``. -For backwards compatibility, jar files listed as sources are ignored (as -they have been since the first version of this module). + Creates a jar file containing java objects and, optionally, resources:: -The default ``OUTPUT_DIR`` can also be changed by setting the variable -``CMAKE_JAVA_TARGET_OUTPUT_DIR``. + add_jar(<target_name> + [SOURCES] <source1> [<source2>...] [<resource1>...] + [INCLUDE_JARS <jar1> [<jar2>...]] + [ENTRY_POINT <entry>] + [VERSION <version>] + [MANIFEST <manifest>] + [OUTPUT_NAME <name>] + [OUTPUT_DIR <dir>] + [GENERATE_NATIVE_HEADERS <target> + [DESTINATION (<dir>|INSTALL <dir> [BUILD <dir>])]] + ) -Optionally, using option ``GENERATE_NATIVE_HEADERS``, native header files can -be generated for methods declared as native. These files provide the -connective glue that allow your Java and C code to interact. An INTERFACE -target will be created for an easy usage of generated files. Sub-option -``DESTINATION`` can be used to specify the output directory for generated -header files. + This command creates a ``<target_name>.jar``. It compiles the given + ``<source>`` files and adds the given ``<resource>`` files to + the jar file. Source files can be java files or listing files + (prefixed by ``@``). If only resource files are given then just a jar file + is created. -``GENERATE_NATIVE_HEADERS`` option requires, at least, version 1.8 of the JDK. + ``SOURCES`` + Compiles the specified source files and adds the result in the jar file. -The ``add_jar()`` function sets the following target properties on -``<target_name>``: + .. versionadded:: 3.4 + Support for response files, prefixed by ``@``. -``INSTALL_FILES`` - The files which should be installed. This is used by ``install_jar()``. -``JNI_SYMLINK`` - The JNI symlink which should be installed. This is used by - ``install_jni_symlink()``. -``JAR_FILE`` - The location of the jar file so that you can include it. -``CLASSDIR`` - The directory where the class files can be found. For example to use them - with ``javah``. + ``INCLUDE_JARS`` + The list of jars are added to the classpath when compiling the java sources + and also to the dependencies of the target. ``INCLUDE_JARS`` also accepts + other target names created by ``add_jar()``. For backwards compatibility, + jar files listed as sources are ignored (as they have been since the first + version of this module). -.. code-block:: cmake + ``ENTRY_POINT`` + Defines an entry point in the jar file. - install_jar(<target_name> <destination>) - install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>]) + ``VERSION`` + Adds a version to the target output name. -This command installs the ``<target_name>`` files to the given -``<destination>``. It should be called in the same scope as ``add_jar()`` or -it will fail. + The following example will create a jar file with the name + ``shibboleet-1.2.0.jar`` and will create a symlink ``shibboleet.jar`` + pointing to the jar with the version information. -The ``install_jar()`` function sets the ``INSTALL_DESTINATION`` target -property on jars so installed. This property holds the ``<destination>`` as -described above, and is used by ``install_jar_exports()``. You can get this -information with :command:`get_property` and the ``INSTALL_DESTINATION`` -property key. + .. code-block:: cmake -.. code-block:: cmake + add_jar(shibboleet shibbotleet.java VERSION 1.2.0) - install_jni_symlink(<target_name> <destination>) - install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>]) + ``MANIFEST`` + Defines a custom manifest for the jar. -This command installs the ``<target_name>`` JNI symlinks to the given -``<destination>``. It should be called in the same scope as ``add_jar()`` or -it will fail. + ``OUTPUT_NAME`` + Specify a different output name for the target. -.. code-block:: cmake + ``OUTPUT_DIR`` + Sets the directory where the jar file will be generated. If not specified, + :variable:`CMAKE_CURRENT_BINARY_DIR` is used as the output directory. - install_jar_exports(TARGETS <jars>... - [NAMESPACE <namespace>] - FILE <filename> - DESTINATION <destination> [COMPONENT <component>]) + ``GENERATE_NATIVE_HEADERS`` + .. versionadded:: 3.11 -This command installs a target export file ``<filename>`` for the named jar -targets to the given ``<destination>`` directory. Its function is similar to -that of :command:`install(EXPORTS)`. + Generates native header files for methods declared as native. These files + provide the connective glue that allow your Java and C code to interact. + An INTERFACE target will be created for an easy usage of generated files. + Sub-option ``DESTINATION`` can be used to specify the output directory for + generated header files. -.. code-block:: cmake + This option requires, at least, version 1.8 of the JDK. - export_jars(TARGETS <jars>... - [NAMESPACE <namespace>] - FILE <filename>) + For an optimum usage of this option, it is recommended to include module + JNI before any call to ``add_jar()``. The produced target for native + headers can then be used to compile C/C++ sources with the + :command:`target_link_libraries` command. -This command writes a target export file ``<filename>`` for the named ``<jars>`` -targets. Its function is similar to that of :command:`export`. + .. code-block:: cmake + find_package(JNI) + add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native) + add_library(bar bar.cpp) + target_link_libraries(bar PRIVATE foo-native) -Examples -"""""""" + .. versionadded:: 3.20 + ``DESTINATION`` sub-option now supports the possibility to specify + different output directories for ``BUILD`` and ``INSTALL`` steps. If + ``BUILD`` directory is not specified, a default directory will be used. -To add compile flags to the target you can set these flags with the following -variable: + To export the interface target generated by ``GENERATE_NATIVE_HEADERS`` + option, sub-option ``INSTALL`` of ``DESTINATION`` is required: -.. code-block:: cmake + .. code-block:: cmake - set(CMAKE_JAVA_COMPILE_FLAGS -nowarn) + add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native + DESTINATION INSTALL include) + install(TARGETS foo-native EXPORT native) + install(DIRECTORY "$<TARGET_PROPERTY:foo-native,NATIVE_HEADERS_DIRECTORY>/" + DESTINATION include) + install(EXPORT native DESTINATION /to/export NAMESPACE foo) + Some variables can be set to customize the behavior of ``add_jar()`` as well + as the java compiler: -To add a path or a jar file to the class path you can do this with the -``CMAKE_JAVA_INCLUDE_PATH`` variable. + ``CMAKE_JAVA_COMPILE_FLAGS`` + Specify additional flags to java compiler. -.. code-block:: cmake + ``CMAKE_JAVA_INCLUDE_PATH`` + Specify additional paths to the class path. - set(CMAKE_JAVA_INCLUDE_PATH /usr/share/java/shibboleet.jar) + ``CMAKE_JNI_TARGET`` + If the target is a JNI library, sets this boolean variable to ``TRUE`` to + enable creation of a JNI symbolic link (see also + :ref:`install_jni_symlink() <install_jni_symlink>`). -To use a different output name for the target you can set it with: + ``CMAKE_JAR_CLASSES_PREFIX`` + If multiple jars should be produced from the same java source filetree, + to prevent the accumulation of duplicate class files in subsequent jars, + set/reset ``CMAKE_JAR_CLASSES_PREFIX`` prior to calling the ``add_jar()``: -.. code-block:: cmake + .. code-block:: cmake - add_jar(foobar foobar.java OUTPUT_NAME shibboleet.jar) + set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo) + add_jar(foo foo.java) -To use a different output directory than ``CMAKE_CURRENT_BINARY_DIR`` you can -set it with: + set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar) + add_jar(bar bar.java) -.. code-block:: cmake + The ``add_jar()`` function sets the following target properties on + ``<target_name>``: - add_jar(foobar foobar.java OUTPUT_DIR ${PROJECT_BINARY_DIR}/bin) + ``INSTALL_FILES`` + The files which should be installed. This is used by + :ref:`install_jar() <install_jar>`. + ``JNI_SYMLINK`` + The JNI symlink which should be installed. This is used by + :ref:`install_jni_symlink() <install_jni_symlink>`. + ``JAR_FILE`` + The location of the jar file so that you can include it. + ``CLASSDIR`` + The directory where the class files can be found. For example to use them + with ``javah``. + ``NATIVE_HEADERS_DIRECTORY`` + .. versionadded:: 3.20 -To define an entry point in your jar you can set it with the ``ENTRY_POINT`` -named argument: + The directory where native headers are generated. Defined when option + ``GENERATE_NATIVE_HEADERS`` is specified. -.. code-block:: cmake +.. _install_jar: - add_jar(example ENTRY_POINT com/examples/MyProject/Main) +.. command:: install_jar -To define a custom manifest for the jar, you can set it with the ``MANIFEST`` -named argument: + This command installs the jar file to the given destination:: -.. code-block:: cmake + install_jar(<target_name> <destination>) + install_jar(<target_name> DESTINATION <destination> [COMPONENT <component>]) - add_jar(example MANIFEST /path/to/manifest) + This command installs the ``<target_name>`` file to the given + ``<destination>``. It should be called in the same scope as + :ref:`add_jar() <add_jar>` or it will fail. -To add a version to the target output name you can set it using the ``VERSION`` -named argument to ``add_jar()``. The following example will create a jar file -with the name ``shibboleet-1.0.0.jar`` and will create a symlink -``shibboleet.jar`` pointing to the jar with the version information. + .. versionadded:: 3.4 + The second signature with ``DESTINATION`` and ``COMPONENT`` options. -.. code-block:: cmake + ``DESTINATION`` + Specify the directory on disk to which a file will be installed. - add_jar(shibboleet shibbotleet.java VERSION 1.2.0) + ``COMPONENT`` + Specify an installation component name with which the install rule is + associated, such as "runtime" or "development". -If the target is a JNI library, utilize the following commands to -create a JNI symbolic link: + The ``install_jar()`` command sets the following target properties + on ``<target_name>``: -.. code-block:: cmake + ``INSTALL_DESTINATION`` + Holds the ``<destination>`` as described above, and is used by + :ref:`install_jar_exports() <install_jar_exports>`. - set(CMAKE_JNI_TARGET TRUE) - add_jar(shibboleet shibbotleet.java VERSION 1.2.0) - install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet) - install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR}) +.. _install_jni_symlink: -If a single target needs to produce more than one jar from its -java source code, to prevent the accumulation of duplicate class -files in subsequent jars, set/reset ``CMAKE_JAR_CLASSES_PREFIX`` prior -to calling the ``add_jar()`` function: +.. command:: install_jni_symlink -.. code-block:: cmake + Installs JNI symlinks for target generated by :ref:`add_jar() <add_jar>`:: - set(CMAKE_JAR_CLASSES_PREFIX com/redhat/foo) - add_jar(foo foo.java) + install_jni_symlink(<target_name> <destination>) + install_jni_symlink(<target_name> DESTINATION <destination> [COMPONENT <component>]) - set(CMAKE_JAR_CLASSES_PREFIX com/redhat/bar) - add_jar(bar bar.java) + This command installs the ``<target_name>`` JNI symlinks to the given + ``<destination>``. It should be called in the same scope as + :ref:`add_jar() <add_jar>` or it will fail. -For an optimum usage of option ``GENERATE_NATIVE_HEADERS``, it is recommended to -include module JNI before any call to ``add_jar()``. The produced target for -native headers can then be used to compile C/C++ sources with the -:command:`target_link_libraries` command. + .. versionadded:: 3.4 + The second signature with ``DESTINATION`` and ``COMPONENT`` options. -.. code-block:: cmake + ``DESTINATION`` + Specify the directory on disk to which a file will be installed. - find_package(JNI) - add_jar(foo foo.java GENERATE_NATIVE_HEADERS foo-native) - add_library(bar bar.cpp) - target_link_libraries(bar PRIVATE foo-native) + ``COMPONENT`` + Specify an installation component name with which the install rule is + associated, such as "runtime" or "development". + Utilize the following commands to create a JNI symbolic link: -Finding JARs -^^^^^^^^^^^^ + .. code-block:: cmake -.. code-block:: cmake - - find_jar(<VAR> - <name> | NAMES <name1> [<name2>...] - [PATHS <path1> [<path2>... ENV <var>]] - [VERSIONS <version1> [<version2>]] - [DOC "cache documentation string"] - ) - -This command is used to find a full path to the named jar. A cache -entry named by ``<VAR>`` is created to store the result of this command. -If the full path to a jar is found the result is stored in the -variable and the search will not repeated unless the variable is -cleared. If nothing is found, the result will be ``<VAR>-NOTFOUND``, and -the search will be attempted again next time ``find_jar()`` is invoked with -the same variable. The name of the full path to a file that is -searched for is specified by the names listed after ``NAMES`` argument. -Additional search locations can be specified after the ``PATHS`` argument. -If you require special a version of a jar file you can specify it with -the ``VERSIONS`` argument. The argument after ``DOC`` will be used for the -documentation string in the cache. - - -Javadoc -^^^^^^^ - -The ``create_javadoc()`` command can be used to create java documentation -based on files or packages. For more details please read the javadoc manpage. - -There are two main signatures for ``create_javadoc()``. The first signature -works with package names on a path with source files. - -.. code-block:: cmake - - create_javadoc(<VAR> - PACKAGES <pkg1> [<pkg2>...] - [SOURCEPATH <sourcepath>] - [CLASSPATH <classpath>] - [INSTALLPATH <install path>] - [DOCTITLE "the documentation title"] - [WINDOWTITLE "the title of the document"] - [AUTHOR TRUE|FALSE] - [USE TRUE|FALSE] - [VERSION TRUE|FALSE] - ) + set(CMAKE_JNI_TARGET TRUE) + add_jar(shibboleet shibbotleet.java VERSION 1.2.0) + install_jar(shibboleet ${LIB_INSTALL_DIR}/shibboleet) + install_jni_symlink(shibboleet ${JAVA_LIB_INSTALL_DIR}) + +Header Generation +^^^^^^^^^^^^^^^^^ + +.. _create_javah: + +.. command:: create_javah -For example: - -.. code-block:: cmake - - create_javadoc(my_example_doc - PACKAGES com.example.foo com.example.bar - SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}" - CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH} - WINDOWTITLE "My example" - DOCTITLE "<h1>My example</h1>" - AUTHOR TRUE - USE TRUE - VERSION TRUE - ) - -The second signature for ``create_javadoc()`` works on a given list of -files. - -.. code-block:: cmake - - create_javadoc(<VAR> - FILES <file1> [<file2>...] - [CLASSPATH <classpath>] - [INSTALLPATH <install path>] - [DOCTITLE "the documentation title"] - [WINDOWTITLE "the title of the document"] - [AUTHOR TRUE|FALSE] - [USE TRUE|FALSE] - [VERSION TRUE|FALSE] + .. versionadded:: 3.4 + + Generates C header files for java classes:: + + create_javah(TARGET <target> | GENERATED_FILES <VAR> + CLASSES <class>... + [CLASSPATH <classpath>...] + [DEPENDS <depend>...] + [OUTPUT_NAME <path>|OUTPUT_DIR <path>] ) -For example: + .. deprecated:: 3.11 + This command will no longer be supported starting with version 10 of the JDK + due to the `suppression of javah tool <http://openjdk.java.net/jeps/313>`_. + The :ref:`add_jar(GENERATE_NATIVE_HEADERS) <add_jar>` command should be + used instead. + + Create C header files from java classes. These files provide the connective + glue that allow your Java and C code to interact. + + There are two main signatures for ``create_javah()``. The first signature + returns generated files through variable specified by the ``GENERATED_FILES`` + option. For example: -.. code-block:: cmake + .. code-block:: cmake - create_javadoc(my_example_doc - FILES ${example_SRCS} - CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH} - WINDOWTITLE "My example" - DOCTITLE "<h1>My example</h1>" - AUTHOR TRUE - USE TRUE - VERSION TRUE - ) + create_javah(GENERATED_FILES files_headers + CLASSES org.cmake.HelloWorld + CLASSPATH hello.jar + ) -Both signatures share most of the options. These options are the same -as what you can find in the javadoc manpage. Please look at the -manpage for ``CLASSPATH``, ``DOCTITLE``, ``WINDOWTITLE``, ``AUTHOR``, ``USE`` -and ``VERSION``. + The second signature for ``create_javah()`` creates a target which + encapsulates header files generation. E.g. -If you don't set the ``INSTALLPATH``, then by default the documentation will -be installed to : + .. code-block:: cmake -:: + create_javah(TARGET target_headers + CLASSES org.cmake.HelloWorld + CLASSPATH hello.jar + ) - ${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR> + Both signatures share same options. + ``CLASSES`` + Specifies Java classes used to generate headers. -Header Generation -^^^^^^^^^^^^^^^^^ + ``CLASSPATH`` + Specifies various paths to look up classes. Here ``.class`` files, jar + files or targets created by command add_jar can be used. + + ``DEPENDS`` + Targets on which the javah target depends. + + ``OUTPUT_NAME`` + Concatenates the resulting header files for all the classes listed by + option ``CLASSES`` into ``<path>``. Same behavior as option ``-o`` of + ``javah`` tool. + + ``OUTPUT_DIR`` + Sets the directory where the header files will be generated. Same behavior + as option ``-d`` of ``javah`` tool. If not specified, + :variable:`CMAKE_CURRENT_BINARY_DIR` is used as the output directory. + +Exporting JAR Targets +^^^^^^^^^^^^^^^^^^^^^ + +.. _install_jar_exports: + +.. command:: install_jar_exports + + .. versionadded:: 3.7 + + Installs a target export file:: -.. code-block:: cmake + install_jar_exports(TARGETS <jars>... + [NAMESPACE <namespace>] + FILE <filename> + DESTINATION <destination> [COMPONENT <component>]) - create_javah(TARGET <target> | GENERATED_FILES <VAR> - CLASSES <class>... - [CLASSPATH <classpath>...] - [DEPENDS <depend>...] - [OUTPUT_NAME <path>|OUTPUT_DIR <path>] - ) + This command installs a target export file ``<filename>`` for the named jar + targets to the given ``<destination>`` directory. Its function is similar to + that of :command:`install(EXPORT)`. -Create C header files from java classes. These files provide the connective glue -that allow your Java and C code to interact. + ``TARGETS`` + List of targets created by :ref:`add_jar() <add_jar>` command. -.. deprecated:: 3.11 + ``NAMESPACE`` + .. versionadded:: 3.9 -.. note:: + The ``<namespace>`` value will be prepend to the target names as they are + written to the import file. - This command will no longer be supported starting with version 10 of the JDK - due to the `suppression of javah tool <http://openjdk.java.net/jeps/313>`_. - The ``add_jar(GENERATE_NATIVE_HEADERS)`` command should be used instead. + ``FILE`` + Specify name of the export file. -There are two main signatures for ``create_javah()``. The first signature -returns generated files through variable specified by the ``GENERATED_FILES`` -option. For example: -.. code-block:: cmake + ``DESTINATION`` + Specify the directory on disk to which a file will be installed. - create_javah(GENERATED_FILES files_headers - CLASSES org.cmake.HelloWorld - CLASSPATH hello.jar - ) + ``COMPONENT`` + Specify an installation component name with which the install rule is + associated, such as "runtime" or "development". -The second signature for ``create_javah()`` creates a target which encapsulates -header files generation. E.g. +.. _export_jars: -.. code-block:: cmake +.. command:: export_jars - create_javah(TARGET target_headers - CLASSES org.cmake.HelloWorld - CLASSPATH hello.jar - ) + .. versionadded:: 3.7 -Both signatures share same options. + Writes a target export file:: -``CLASSES <class>...`` - Specifies Java classes used to generate headers. + export_jars(TARGETS <jars>... + [NAMESPACE <namespace>] + FILE <filename>) -``CLASSPATH <classpath>...`` - Specifies various paths to look up classes. Here .class files, jar files or - targets created by command add_jar can be used. + This command writes a target export file ``<filename>`` for the named ``<jars>`` + targets. Its function is similar to that of :command:`export`. -``DEPENDS <depend>...`` - Targets on which the javah target depends. + ``TARGETS`` + List of targets created by :ref:`add_jar() <add_jar>` command. -``OUTPUT_NAME <path>`` - Concatenates the resulting header files for all the classes listed by option - ``CLASSES`` into ``<path>``. Same behavior as option ``-o`` of javah tool. + ``NAMESPACE`` + .. versionadded:: 3.9 -``OUTPUT_DIR <path>`` - Sets the directory where the header files will be generated. Same behavior - as option ``-d`` of javah tool. If not specified, - :variable:`CMAKE_CURRENT_BINARY_DIR` is used as the output directory. + The ``<namespace>`` value will be prepend to the target names as they are + written to the import file. + + ``FILE`` + Specify name of the export file. + +Finding JARs +^^^^^^^^^^^^ + +.. _find_jar: + +.. command:: find_jar + + Finds the specified jar file:: + + find_jar(<VAR> + <name> | NAMES <name1> [<name2>...] + [PATHS <path1> [<path2>... ENV <var>]] + [VERSIONS <version1> [<version2>]] + [DOC "cache documentation string"] + ) + + This command is used to find a full path to the named jar. A cache + entry named by ``<VAR>`` is created to store the result of this command. + If the full path to a jar is found the result is stored in the + variable and the search will not repeated unless the variable is + cleared. If nothing is found, the result will be ``<VAR>-NOTFOUND``, and + the search will be attempted again next time ``find_jar()`` is invoked with + the same variable. + + ``NAMES`` + Specify one or more possible names for the jar file. + + ``PATHS`` + Specify directories to search in addition to the default locations. + The ``ENV`` var sub-option reads paths from a system environment variable. + + ``VERSIONS`` + Specify jar versions. + + ``DOC`` + Specify the documentation string for the ``<VAR>`` cache entry. + +Creating Java Documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. _create_javadoc: + +.. command:: create_javadoc + + Creates java documentation based on files and packages:: + + create_javadoc(<VAR> + (PACKAGES <pkg1> [<pkg2>...] | FILES <file1> [<file2>...]) + [SOURCEPATH <sourcepath>] + [CLASSPATH <classpath>] + [INSTALLPATH <install path>] + [DOCTITLE <the documentation title>] + [WINDOWTITLE <the title of the document>] + [AUTHOR (TRUE|FALSE)] + [USE (TRUE|FALSE)] + [VERSION (TRUE|FALSE)] + ) + + The ``create_javadoc()`` command can be used to create java documentation. + There are two main signatures for ``create_javadoc()``. + + The first signature works with package names on a path with source files: + + .. code-block:: cmake + + create_javadoc(my_example_doc + PACKAGES com.example.foo com.example.bar + SOURCEPATH "${CMAKE_CURRENT_SOURCE_DIR}" + CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH} + WINDOWTITLE "My example" + DOCTITLE "<h1>My example</h1>" + AUTHOR TRUE + USE TRUE + VERSION TRUE + ) + + The second signature for ``create_javadoc()`` works on a given list of files: + + .. code-block:: cmake + + create_javadoc(my_example_doc + FILES java/A.java java/B.java + CLASSPATH ${CMAKE_JAVA_INCLUDE_PATH} + WINDOWTITLE "My example" + DOCTITLE "<h1>My example</h1>" + AUTHOR TRUE + USE TRUE + VERSION TRUE + ) + + Both signatures share most of the options. For more details please read the + javadoc manpage. + + ``PACKAGES`` + Specify java packages. + + ``FILES`` + Specify java source files. If relative paths are specified, they are + relative to :variable:`CMAKE_CURRENT_SOURCE_DIR`. + + ``SOURCEPATH`` + Specify the directory where to look for packages. By default, + :variable:`CMAKE_CURRENT_SOURCE_DIR` directory is used. + + ``CLASSPATH`` + Specify where to find user class files. Same behavior as option + ``-classpath`` of ``javadoc`` tool. + + ``INSTALLPATH`` + Specify where to install the java documentation. If you specified, the + documentation will be installed to + ``${CMAKE_INSTALL_PREFIX}/share/javadoc/<VAR>``. + + ``DOCTITLE`` + Specify the title to place near the top of the overview summary file. + Same behavior as option ``-doctitle`` of ``javadoc`` tool. + + ``WINDOWTITLE`` + Specify the title to be placed in the HTML ``<title>`` tag. Same behavior + as option ``-windowtitle`` of ``javadoc`` tool. + + ``AUTHOR`` + When value ``TRUE`` is specified, includes the ``@author`` text in the + generated docs. Same behavior as option ``-author`` of ``javadoc`` tool. + + ``USE`` + When value ``TRUE`` is specified, creates class and package usage pages. + Includes one Use page for each documented class and package. Same behavior + as option ``-use`` of ``javadoc`` tool. + + ``VERSION`` + When value ``TRUE`` is specified, includes the version text in the + generated docs. Same behavior as option ``-version`` of ``javadoc`` tool. #]=======================================================================] include(CMakeParseArguments) @@ -378,7 +525,8 @@ function (__java_copy_file src dest comment) ARGS ${src} ${dest} DEPENDS ${src} - COMMENT ${comment}) + COMMENT ${comment} + ) endfunction () function(__java_lcat VAR) @@ -409,6 +557,12 @@ set(_JAVA_EXPORT_TARGETS_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/javaTargets.cmake.in) set(_JAVA_CLASS_FILELIST_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/UseJavaClassFilelist.cmake) set(_JAVA_SYMLINK_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/UseJavaSymlinks.cmake) +if (CMAKE_HOST_WIN32 AND NOT CYGWIN AND CMAKE_HOST_SYSTEM_NAME MATCHES "Windows") + set(_UseJava_PATH_SEP "$<SEMICOLON>") +else () + set(_UseJava_PATH_SEP ":") +endif() + function(add_jar _TARGET_NAME) cmake_parse_arguments(_add_jar @@ -440,6 +594,9 @@ function(add_jar _TARGET_NAME) set(_add_jar_ENTRY_POINT "${CMAKE_JAVA_JAR_ENTRY_POINT}") endif() + # This *should* still work if <resources1>... are included without a + # named RESOURCES argument. In that case, the old behavior of potentially + # misplacing the within the Jar will behave as previously (incorrectly) set(_JAVA_SOURCE_FILES ${_add_jar_SOURCES} ${_add_jar_UNPARSED_ARGUMENTS}) if (NOT DEFINED _add_jar_OUTPUT_DIR) @@ -467,7 +624,10 @@ function(add_jar _TARGET_NAME) if (Java_VERSION VERSION_LESS 1.8) message (FATAL_ERROR "ADD_JAR: GENERATE_NATIVE_HEADERS is not supported with this version of Java.") endif() - cmake_parse_arguments (_add_jar_GENERATE_NATIVE_HEADERS "" "DESTINATION" "" ${_add_jar_GENERATE_NATIVE_HEADERS}) + + unset (_GENERATE_NATIVE_HEADERS_OUTPUT_DESC) + + cmake_parse_arguments (_add_jar_GENERATE_NATIVE_HEADERS "" "" "DESTINATION" ${_add_jar_GENERATE_NATIVE_HEADERS}) if (NOT _add_jar_GENERATE_NATIVE_HEADERS_UNPARSED_ARGUMENTS) message (FATAL_ERROR "ADD_JAR: GENERATE_NATIVE_HEADERS: missing required argument.") endif() @@ -478,11 +638,30 @@ function(add_jar _TARGET_NAME) endif() if (NOT _add_jar_GENERATE_NATIVE_HEADERS_DESTINATION) set (_add_jar_GENERATE_NATIVE_HEADERS_DESTINATION "${CMAKE_CURRENT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/${_TARGET_NAME}.dir/native_headers") + else() + list (LENGTH _add_jar_GENERATE_NATIVE_HEADERS_DESTINATION length) + if (NOT length EQUAL 1) + cmake_parse_arguments (_add_jar_GENERATE_NATIVE_HEADERS_DESTINATION "" "BUILD;INSTALL" "" "${_add_jar_GENERATE_NATIVE_HEADERS_DESTINATION}") + if (_add_jar_GENERATE_NATIVE_HEADERS_DESTINATION_UNPARSED_ARGUMENTS) + message (FATAL_ERROR "ADD_JAR: GENERATE_NATIVE_HEADERS: DESTINATION: ${_add_jar_GENERATE_NATIVE_HEADERS_DESTINATION_UNPARSED_ARGUMENTS}: unexpected argument(s).") + endif() + if (NOT _add_jar_GENERATE_NATIVE_HEADERS_DESTINATION_INSTALL) + message (FATAL_ERROR "ADD_JAR: GENERATE_NATIVE_HEADERS: DESTINATION: INSTALL sub-option is required.") + endif() + if (NOT _add_jar_GENERATE_NATIVE_HEADERS_DESTINATION_BUILD) + set(_add_jar_GENERATE_NATIVE_HEADERS_DESTINATION_BUILD "${CMAKE_CURRENT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/${_TARGET_NAME}.dir/native_headers") + endif() + set(_add_jar_GENERATE_NATIVE_HEADERS_DESTINATION "${_add_jar_GENERATE_NATIVE_HEADERS_DESTINATION_BUILD}") + set(_GENERATE_NATIVE_HEADERS_OUTPUT_DESC "$<BUILD_INTERFACE:${_add_jar_GENERATE_NATIVE_HEADERS_DESTINATION_BUILD}>" "$<INSTALL_INTERFACE:${_add_jar_GENERATE_NATIVE_HEADERS_DESTINATION_INSTALL}>") + endif() endif() set (_GENERATE_NATIVE_HEADERS_TARGET ${_add_jar_GENERATE_NATIVE_HEADERS_UNPARSED_ARGUMENTS}) set (_GENERATE_NATIVE_HEADERS_OUTPUT_DIR "${_add_jar_GENERATE_NATIVE_HEADERS_DESTINATION}") set (_GENERATE_NATIVE_HEADERS -h "${_GENERATE_NATIVE_HEADERS_OUTPUT_DIR}") + if(NOT _GENERATE_NATIVE_HEADERS_OUTPUT_DESC) + set(_GENERATE_NATIVE_HEADERS_OUTPUT_DESC "${_GENERATE_NATIVE_HEADERS_OUTPUT_DIR}") + endif() endif() if (LIBRARY_OUTPUT_PATH) @@ -498,14 +677,8 @@ function(add_jar _TARGET_NAME) ${CMAKE_JAVA_LIBRARY_OUTPUT_PATH} ) - if (CMAKE_HOST_WIN32 AND NOT CYGWIN AND CMAKE_HOST_SYSTEM_NAME MATCHES "Windows") - set(CMAKE_JAVA_INCLUDE_FLAG_SEP ";") - else () - set(CMAKE_JAVA_INCLUDE_FLAG_SEP ":") - endif() - foreach (JAVA_INCLUDE_DIR IN LISTS CMAKE_JAVA_INCLUDE_PATH) - string(APPEND CMAKE_JAVA_INCLUDE_PATH_FINAL "${CMAKE_JAVA_INCLUDE_FLAG_SEP}${JAVA_INCLUDE_DIR}") + string(APPEND CMAKE_JAVA_INCLUDE_PATH_FINAL "${_UseJava_PATH_SEP}${JAVA_INCLUDE_DIR}") endforeach() set(CMAKE_JAVA_CLASS_OUTPUT_PATH "${CMAKE_CURRENT_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/${_TARGET_NAME}.dir") @@ -536,7 +709,7 @@ function(add_jar _TARGET_NAME) if (_JAVA_SOURCE_FILE MATCHES "^@(.+)$") get_filename_component(_JAVA_FULL ${CMAKE_MATCH_1} ABSOLUTE) - list (APPEND _JAVA_COMPILE_FILELISTS ${_JAVA_FULL}) + list(APPEND _JAVA_COMPILE_FILELISTS ${_JAVA_FULL}) elseif (_JAVA_EXT MATCHES ".java") file(RELATIVE_PATH _JAVA_REL_BINARY_PATH ${CMAKE_CURRENT_BINARY_DIR} ${_JAVA_FULL}) @@ -550,7 +723,7 @@ function(add_jar _TARGET_NAME) endif () get_filename_component(_JAVA_REL_PATH ${_JAVA_REL_PATH} PATH) - list (APPEND _JAVA_COMPILE_FILES ${_JAVA_SOURCE_FILE}) + list(APPEND _JAVA_COMPILE_FILES ${_JAVA_SOURCE_FILE}) set(_JAVA_CLASS_FILE "${CMAKE_JAVA_CLASS_OUTPUT_PATH}/${_JAVA_REL_PATH}/${_JAVA_FILE}.class") set(_JAVA_CLASS_FILES ${_JAVA_CLASS_FILES} ${_JAVA_CLASS_FILE}) @@ -561,15 +734,15 @@ function(add_jar _TARGET_NAME) # Ignored for backward compatibility elseif (_JAVA_EXT STREQUAL "") - list (APPEND CMAKE_JAVA_INCLUDE_PATH ${JAVA_JAR_TARGET_${_JAVA_SOURCE_FILE}} ${JAVA_JAR_TARGET_${_JAVA_SOURCE_FILE}_CLASSPATH}) - list (APPEND _JAVA_DEPENDS ${JAVA_JAR_TARGET_${_JAVA_SOURCE_FILE}}) + list(APPEND CMAKE_JAVA_INCLUDE_PATH ${JAVA_JAR_TARGET_${_JAVA_SOURCE_FILE}} ${JAVA_JAR_TARGET_${_JAVA_SOURCE_FILE}_CLASSPATH}) + list(APPEND _JAVA_DEPENDS ${JAVA_JAR_TARGET_${_JAVA_SOURCE_FILE}}) else () __java_copy_file(${CMAKE_CURRENT_SOURCE_DIR}/${_JAVA_SOURCE_FILE} ${CMAKE_JAVA_CLASS_OUTPUT_PATH}/${_JAVA_SOURCE_FILE} "Copying ${_JAVA_SOURCE_FILE} to the build directory") - list (APPEND _JAVA_RESOURCE_FILES ${CMAKE_JAVA_CLASS_OUTPUT_PATH}/${_JAVA_SOURCE_FILE}) - list (APPEND _JAVA_RESOURCE_FILES_RELATIVE ${_JAVA_SOURCE_FILE}) + list(APPEND _JAVA_RESOURCE_FILES ${CMAKE_JAVA_CLASS_OUTPUT_PATH}/${_JAVA_SOURCE_FILE}) + list(APPEND _JAVA_RESOURCE_FILES_RELATIVE ${_JAVA_SOURCE_FILE}) endif () endforeach() @@ -577,18 +750,18 @@ function(add_jar _TARGET_NAME) if (TARGET ${_JAVA_INCLUDE_JAR}) get_target_property(_JAVA_JAR_PATH ${_JAVA_INCLUDE_JAR} JAR_FILE) if (_JAVA_JAR_PATH) - string(APPEND CMAKE_JAVA_INCLUDE_PATH_FINAL "${CMAKE_JAVA_INCLUDE_FLAG_SEP}${_JAVA_JAR_PATH}") - list (APPEND CMAKE_JAVA_INCLUDE_PATH ${_JAVA_JAR_PATH}) - list (APPEND _JAVA_DEPENDS ${_JAVA_INCLUDE_JAR}) - list (APPEND _JAVA_COMPILE_DEPENDS ${_JAVA_JAR_PATH}) + string(APPEND CMAKE_JAVA_INCLUDE_PATH_FINAL "${_UseJava_PATH_SEP}${_JAVA_JAR_PATH}") + list(APPEND CMAKE_JAVA_INCLUDE_PATH ${_JAVA_JAR_PATH}) + list(APPEND _JAVA_DEPENDS ${_JAVA_INCLUDE_JAR}) + list(APPEND _JAVA_COMPILE_DEPENDS ${_JAVA_JAR_PATH}) else () message(SEND_ERROR "add_jar: INCLUDE_JARS target ${_JAVA_INCLUDE_JAR} is not a jar") endif () else () - string(APPEND CMAKE_JAVA_INCLUDE_PATH_FINAL "${CMAKE_JAVA_INCLUDE_FLAG_SEP}${_JAVA_INCLUDE_JAR}") - list (APPEND CMAKE_JAVA_INCLUDE_PATH "${_JAVA_INCLUDE_JAR}") - list (APPEND _JAVA_DEPENDS "${_JAVA_INCLUDE_JAR}") - list (APPEND _JAVA_COMPILE_DEPENDS "${_JAVA_INCLUDE_JAR}") + string(APPEND CMAKE_JAVA_INCLUDE_PATH_FINAL "${_UseJava_PATH_SEP}${_JAVA_INCLUDE_JAR}") + list(APPEND CMAKE_JAVA_INCLUDE_PATH "${_JAVA_INCLUDE_JAR}") + list(APPEND _JAVA_DEPENDS "${_JAVA_INCLUDE_JAR}") + list(APPEND _JAVA_COMPILE_DEPENDS "${_JAVA_INCLUDE_JAR}") endif () endforeach() @@ -627,14 +800,14 @@ function(add_jar _TARGET_NAME) OUTPUT ${CMAKE_JAVA_CLASS_OUTPUT_PATH}/java_class_filelist COMMAND ${CMAKE_COMMAND} -DCMAKE_JAVA_CLASS_OUTPUT_PATH=${CMAKE_JAVA_CLASS_OUTPUT_PATH} - -DCMAKE_JAR_CLASSES_PREFIX="${CMAKE_JAR_CLASSES_PREFIX}" + -DCMAKE_JAR_CLASSES_PREFIX=${CMAKE_JAR_CLASSES_PREFIX} -P ${_JAVA_CLASS_FILELIST_SCRIPT} DEPENDS ${CMAKE_JAVA_CLASS_OUTPUT_PATH}/java_compiled_${_TARGET_NAME} WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} ) else () # create an empty java_class_filelist - if (NOT EXISTS "${CMAKE_JAVA_CLASS_OUTPUT_PATH}/java_class_filelist") + if (NOT EXISTS ${CMAKE_JAVA_CLASS_OUTPUT_PATH}/java_class_filelist) file(WRITE ${CMAKE_JAVA_CLASS_OUTPUT_PATH}/java_class_filelist "") endif() endif () @@ -731,8 +904,9 @@ function(add_jar _TARGET_NAME) # create an INTERFACE library encapsulating include directory for generated headers add_library (${_GENERATE_NATIVE_HEADERS_TARGET} INTERFACE) target_include_directories (${_GENERATE_NATIVE_HEADERS_TARGET} INTERFACE - "${_GENERATE_NATIVE_HEADERS_OUTPUT_DIR}" + "${_GENERATE_NATIVE_HEADERS_OUTPUT_DESC}" ${JNI_INCLUDE_DIRS}) + set_property(TARGET ${_GENERATE_NATIVE_HEADERS_TARGET} PROPERTY NATIVE_HEADERS_DIRECTORY "${_GENERATE_NATIVE_HEADERS_OUTPUT_DIR}") # this INTERFACE library depends on jar generation add_dependencies (${_GENERATE_NATIVE_HEADERS_TARGET} ${_TARGET_NAME}) @@ -985,7 +1159,7 @@ function(create_javadoc _target) elseif (arg STREQUAL "VERSION") set(_state "version") else () - list (APPEND _javadoc_packages ${arg}) + list(APPEND _javadoc_packages ${arg}) endif () elseif (_state STREQUAL "files") if (arg STREQUAL "PACKAGES") @@ -1009,7 +1183,7 @@ function(create_javadoc _target) elseif (arg STREQUAL "VERSION") set(_state "version") else () - list (APPEND _javadoc_files ${arg}) + list(APPEND _javadoc_files ${arg}) endif () elseif (_state STREQUAL "sourcepath") if (arg STREQUAL "PACKAGES") @@ -1033,7 +1207,7 @@ function(create_javadoc _target) elseif (arg STREQUAL "VERSION") set(_state "version") else () - list (APPEND _javadoc_sourcepath ${arg}) + list(APPEND _javadoc_sourcepath ${arg}) endif () elseif (_state STREQUAL "classpath") if (arg STREQUAL "PACKAGES") @@ -1057,7 +1231,7 @@ function(create_javadoc _target) elseif (arg STREQUAL "VERSION") set(_state "version") else () - list (APPEND _javadoc_classpath ${arg}) + list(APPEND _javadoc_classpath ${arg}) endif () elseif (_state STREQUAL "installpath") if (arg STREQUAL "PACKAGES") @@ -1238,68 +1412,45 @@ function(create_javadoc _target) set(_javadoc_options -d ${_javadoc_builddir}) if (_javadoc_sourcepath) - set(_start TRUE) - foreach(_path IN LISTS _javadoc_sourcepath) - if (_start) - set(_sourcepath ${_path}) - set(_start FALSE) - else () - set(_sourcepath ${_sourcepath}:${_path}) - endif () - endforeach() - set(_javadoc_options ${_javadoc_options} -sourcepath ${_sourcepath}) + list(JOIN _javadoc_sourcepath "${_UseJava_PATH_SEP}" _javadoc_sourcepath) + list(APPEND _javadoc_options -sourcepath "\"${_javadoc_sourcepath}\"") endif () if (_javadoc_overview) - set(_start TRUE) - foreach(_path IN LISTS _javadoc_overview) - if (_start) - set(_overview ${_path}) - set(_start FALSE) - else () - set(_overview ${_overview}:${_path}) - endif () - endforeach () - set(_javadoc_options ${_javadoc_options} -overview ${_overview}) + list(JOIN _javadoc_overview "${_UseJava_PATH_SEP}" _javadoc_overview) + list(APPEND _javadoc_options -overview "\"${_javadoc_overview}\"") endif () if (_javadoc_classpath) - set(_start TRUE) - foreach(_path IN LISTS _javadoc_classpath) - if (_start) - set(_classpath ${_path}) - set(_start FALSE) - else () - set(_classpath ${_classpath}:${_path}) - endif () - endforeach() - set(_javadoc_options ${_javadoc_options} -classpath "${_classpath}") + list(JOIN _javadoc_classpath "${_UseJava_PATH_SEP}" _javadoc_classpath) + list(APPEND _javadoc_options -classpath "\"${_javadoc_classpath}\"") endif () if (_javadoc_doctitle) - set(_javadoc_options ${_javadoc_options} -doctitle '${_javadoc_doctitle}') + list(APPEND _javadoc_options -doctitle '${_javadoc_doctitle}') endif () if (_javadoc_windowtitle) - set(_javadoc_options ${_javadoc_options} -windowtitle '${_javadoc_windowtitle}') + list(APPEND _javadoc_options -windowtitle '${_javadoc_windowtitle}') endif () if (_javadoc_author) - set(_javadoc_options ${_javadoc_options} -author) + list(APPEND _javadoc_options -author) endif () if (_javadoc_use) - set(_javadoc_options ${_javadoc_options} -use) + list(APPEND _javadoc_options -use) endif () if (_javadoc_version) - set(_javadoc_options ${_javadoc_options} -version) + list(APPEND _javadoc_options -version) endif () add_custom_target(${_target}_javadoc ALL - COMMAND ${Java_JAVADOC_EXECUTABLE} ${_javadoc_options} - ${_javadoc_files} - ${_javadoc_packages} + COMMAND ${Java_JAVADOC_EXECUTABLE} + ${_javadoc_options} + ${_javadoc_files} + ${_javadoc_packages} WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} ) @@ -1335,11 +1486,6 @@ function (create_javah) endif() set (_output_files) - if (WIN32 AND NOT CYGWIN AND CMAKE_HOST_SYSTEM_NAME MATCHES "Windows") - set(_classpath_sep "$<SEMICOLON>") - else () - set(_classpath_sep ":") - endif() # handle javah options set (_javah_options) @@ -1365,7 +1511,7 @@ function (create_javah) message(SEND_ERROR "create_javah: CLASSPATH entry ${_path} does not exist.") endif() endforeach() - string (REPLACE ";" "${_classpath_sep}" _classpath "${_classpath}") + string (REPLACE ";" "${_UseJava_PATH_SEP}" _classpath "${_classpath}") list (APPEND _javah_options -classpath "${_classpath}") endif() diff --git a/config/cmake/UseJavaClassFilelist.cmake b/config/cmake/UseJavaClassFilelist.cmake index 8348e4c..d90ca48 100644 --- a/config/cmake/UseJavaClassFilelist.cmake +++ b/config/cmake/UseJavaClassFilelist.cmake @@ -1,17 +1,8 @@ # Distributed under the OSI-approved BSD 3-Clause License. See https://cmake.org/licensing for details. -#[=======================================================================[.rst: -UseJavaClassFilelist --------------------- - - - - - -This script create a list of compiled Java class files to be added to -a jar file. This avoids including cmake files which get created in -the binary directory. -#]=======================================================================] +# This script creates a list of compiled Java class files to be added to +# a jar file. This avoids including cmake files which get created in +# the binary directory. if (CMAKE_JAVA_CLASS_OUTPUT_PATH) if (EXISTS "${CMAKE_JAVA_CLASS_OUTPUT_PATH}") @@ -23,7 +14,7 @@ if (CMAKE_JAVA_CLASS_OUTPUT_PATH) file(GLOB_RECURSE _JAVA_GLOBBED_TMP_FILES "${CMAKE_JAVA_CLASS_OUTPUT_PATH}/${JAR_CLASS_PREFIX}/*.class") if (_JAVA_GLOBBED_TMP_FILES) - list (APPEND _JAVA_GLOBBED_FILES ${_JAVA_GLOBBED_TMP_FILES}) + list(APPEND _JAVA_GLOBBED_FILES ${_JAVA_GLOBBED_TMP_FILES}) endif () endforeach() else() diff --git a/config/cmake/UseJavaSymlinks.cmake b/config/cmake/UseJavaSymlinks.cmake index a4db5c1..cb2e282 100644 --- a/config/cmake/UseJavaSymlinks.cmake +++ b/config/cmake/UseJavaSymlinks.cmake @@ -1,15 +1,6 @@ # Distributed under the OSI-approved BSD 3-Clause License. See https://cmake.org/licensing for details. -#[=======================================================================[.rst: -UseJavaSymlinks ---------------- - - - - - -Helper script for UseJava.cmake -#]=======================================================================] +# Helper script for UseJava.cmake if (UNIX AND _JAVA_TARGET_OUTPUT_LINK) if (_JAVA_TARGET_OUTPUT_NAME) diff --git a/config/cmake/hdf5-config.cmake.in b/config/cmake/hdf5-config.cmake.in index 4d02c9c..8faa2fe 100644 --- a/config/cmake/hdf5-config.cmake.in +++ b/config/cmake/hdf5-config.cmake.in @@ -38,6 +38,7 @@ set (${HDF5_PACKAGE_NAME}_BUILD_CPP_LIB @HDF5_BUILD_CPP_LIB@) set (${HDF5_PACKAGE_NAME}_BUILD_JAVA @HDF5_BUILD_JAVA@) set (${HDF5_PACKAGE_NAME}_BUILD_TOOLS @HDF5_BUILD_TOOLS@) set (${HDF5_PACKAGE_NAME}_BUILD_HL_LIB @HDF5_BUILD_HL_LIB@) +set (${HDF5_PACKAGE_NAME}_BUILD_HL_TOOLS @HDF5_BUILD_HL_TOOLS@) set (${HDF5_PACKAGE_NAME}_ENABLE_THREADSAFE @HDF5_ENABLE_THREADSAFE@) set (${HDF5_PACKAGE_NAME}_ENABLE_PLUGIN_SUPPORT @HDF5_ENABLE_PLUGIN_SUPPORT@) set (${HDF5_PACKAGE_NAME}_ENABLE_Z_LIB_SUPPORT @HDF5_ENABLE_Z_LIB_SUPPORT@) diff --git a/config/cmake/javaTargets.cmake.in b/config/cmake/javaTargets.cmake.in new file mode 100644 index 0000000..6e14256 --- /dev/null +++ b/config/cmake/javaTargets.cmake.in @@ -0,0 +1,39 @@ +cmake_minimum_required(VERSION 2.8.12) +cmake_policy(PUSH) +cmake_policy(VERSION 2.8) + +#---------------------------------------------------------------- +# Generated CMake Java target import file. +#---------------------------------------------------------------- + +# Protect against multiple inclusion, which would fail when already imported targets are added once more. +set(_targetsDefined) +set(_targetsNotDefined) +set(_expectedTargets) +foreach(_expectedTarget @__targets__@) + list(APPEND _expectedTargets ${_expectedTarget}) + if(TARGET ${_expectedTarget}) + list(APPEND _targetsDefined ${_expectedTarget}) + else() + list(APPEND _targetsNotDefined ${_expectedTarget}) + endif() +endforeach() +if("%${_targetsDefined}" STREQUAL "%${_expectedTargets}") + unset(_targetsDefined) + unset(_targetsNotDefined) + unset(_expectedTargets) + cmake_policy(POP) + return() +endif() +if(NOT "${_targetsDefined}" STREQUAL "") + message(FATAL_ERROR + "Some (but not all) targets in this export set were already defined.\n" + "Targets Defined: ${_targetsDefined}\n" + "Targets not yet defined: ${_targetsNotDefined}\n") +endif() +unset(_targetsDefined) +unset(_targetsNotDefined) +unset(_expectedTargets) + +@__targetdefs__@ +cmake_policy(POP) diff --git a/config/cmake/libh5cc.in b/config/cmake/libh5cc.in index c98d9ca..ecdd13e 100644 --- a/config/cmake/libh5cc.in +++ b/config/cmake/libh5cc.in @@ -29,4 +29,4 @@ printf 'dir is %s\n' "$dir" export PKG_CONFIG_PATH=$dir/lib/pkgconfig -@_PKG_CONFIG_COMPILER@ `pkg-config --define-variable=prefix=$dir --cflags --libs @_PKG_CONFIG_LIBNAME@` $@ +@_PKG_CONFIG_COMPILER@ $@ `pkg-config --define-variable=prefix=$dir --cflags --libs @_PKG_CONFIG_LIBNAME@` diff --git a/config/cmake/libhdf5.settings.cmake.in b/config/cmake/libhdf5.settings.cmake.in index ebcbd61..eb83c3a 100644 --- a/config/cmake/libhdf5.settings.cmake.in +++ b/config/cmake/libhdf5.settings.cmake.in @@ -70,6 +70,7 @@ Parallel Filtered Dataset Writes: @PARALLEL_FILTERED_WRITES@ High-level library: @HDF5_BUILD_HL_LIB@ Build HDF5 Tests: @BUILD_TESTING@ Build HDF5 Tools: @HDF5_BUILD_TOOLS@ + Build High-level HDF5 Tools: @HDF5_BUILD_HL_TOOLS@ Threadsafety: @HDF5_ENABLE_THREADSAFE@ Default API mapping: @DEFAULT_API_VERSION@ With deprecated public symbols: @HDF5_ENABLE_DEPRECATED_SYMBOLS@ diff --git a/config/cmake/scripts/HDF5options.cmake b/config/cmake/scripts/HDF5options.cmake index 8a152d1..136f55d 100644 --- a/config/cmake/scripts/HDF5options.cmake +++ b/config/cmake/scripts/HDF5options.cmake @@ -69,7 +69,7 @@ set (ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_ALLOW_EXTERNAL_SUPPORT:STRIN #set (ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_ENABLE_SZIP_ENCODING:BOOL=OFF") #### package examples #### -#set (ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_PACK_EXAMPLES:BOOL=ON -DHDF5_EXAMPLES_COMPRESSED:STRING=HDF5Examples-1.14.3-Source.tar.gz -DHDF5_EXAMPLES_COMPRESSED_DIR:PATH=${CTEST_SCRIPT_DIRECTORY}") +#set (ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF5_PACK_EXAMPLES:BOOL=ON -DHDF5_EXAMPLES_COMPRESSED:STRING=HDF5Examples-1.14.4-Source.tar.gz -DHDF5_EXAMPLES_COMPRESSED_DIR:PATH=${CTEST_SCRIPT_DIRECTORY}") ############################################################################################# ### enable parallel builds diff --git a/config/gnu-fflags b/config/gnu-fflags index ec4fcab..ce12561 100644 --- a/config/gnu-fflags +++ b/config/gnu-fflags @@ -161,10 +161,10 @@ if test "X-gfortran" = "X-$f9x_vendor"; then # gfortran 4.9 (nothing new) - # gfortran >= 5 - if test $f9x_vers_major -ge 5; then - H5_FCFLAGS="$H5_FCFLAGS $(load_gnu_arguments gfort-5)" - fi + # gfortran >= 5 (do not include -Wuse-without-only) + #if test $f9x_vers_major -ge 5; then + # H5_FCFLAGS="$H5_FCFLAGS $(load_gnu_arguments gfort-5)" + #fi # gfortran >= 6 if test $f9x_vers_major -ge 6; then diff --git a/config/sanitizer/code-coverage.cmake b/config/sanitizer/code-coverage.cmake index 8d765f7..c79aeac 100644 --- a/config/sanitizer/code-coverage.cmake +++ b/config/sanitizer/code-coverage.cmake @@ -99,8 +99,7 @@ if(CODE_COVERAGE AND NOT CODE_COVERAGE_ADDED) ${CMAKE_COVERAGE_OUTPUT_DIRECTORY} DEPENDS ccov-clean) - if(CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" - OR CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") + if(CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" OR CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") # Messages message(STATUS "Building with llvm Code Coverage Tools") @@ -206,8 +205,7 @@ function(target_code_coverage TARGET_NAME) if(CODE_COVERAGE) # Add code coverage instrumentation to the target's linker command - if(CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" - OR CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") + if(CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" OR CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") target_compile_options(${TARGET_NAME} PRIVATE -fprofile-instr-generate -fcoverage-mapping) set_property( @@ -229,8 +227,7 @@ function(target_code_coverage TARGET_NAME) # Add shared library to processing for 'all' targets if(target_type STREQUAL "SHARED_LIBRARY" AND target_code_coverage_ALL) - if(CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" - OR CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") + if(CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" OR CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") add_custom_target( ccov-run-${TARGET_NAME} COMMAND echo "-object=$<TARGET_FILE:${TARGET_NAME}>" >> @@ -250,8 +247,7 @@ function(target_code_coverage TARGET_NAME) # For executables add targets to run and produce output if(target_type STREQUAL "EXECUTABLE") - if(CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" - OR CMAKE_CXX_COMPILER_ID MATCHES "(Apple)?Cc]lang") + if(CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" OR CMAKE_CXX_COMPILER_ID MATCHES "(Apple)?Cc]lang") # If there are shared objects to also work with, generate the string to # add them here @@ -409,8 +405,7 @@ endfunction() # any subdirectories. To add coverage instrumentation to only specific targets, # use `target_code_coverage`. function(add_code_coverage) - if(CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" - OR CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") + if(CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" OR CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") add_compile_options(-fprofile-instr-generate -fcoverage-mapping) add_link_options(-fprofile-instr-generate -fcoverage-mapping) elseif(CMAKE_C_COMPILER_ID MATCHES "GNU" OR CMAKE_CXX_COMPILER_ID MATCHES "GNU") @@ -435,8 +430,7 @@ function(add_code_coverage_all_targets) "${multi_value_keywords}" ${ARGN}) if(CODE_COVERAGE) - if(CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" - OR CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") + if(CMAKE_C_COMPILER_ID MATCHES "[Cc]lang" OR CMAKE_CXX_COMPILER_ID MATCHES "[Cc]lang") # Merge the profile data for all of the run executables add_custom_target( diff --git a/config/sanitizer/sanitizers.cmake b/config/sanitizer/sanitizers.cmake index 58c4050..8bf1d5b 100644 --- a/config/sanitizer/sanitizers.cmake +++ b/config/sanitizer/sanitizers.cmake @@ -30,7 +30,7 @@ endfunction() message(STATUS "USE_SANITIZER=${USE_SANITIZER}, CMAKE_C_COMPILER_ID=${CMAKE_C_COMPILER_ID}") if(USE_SANITIZER) - if(INTEL_CLANG OR "${CMAKE_C_COMPILER_ID}" MATCHES "Clang") + if(INTEL_CLANG OR CMAKE_C_COMPILER_ID MATCHES "[Cc]lang") set(CMAKE_EXPORT_COMPILE_COMMANDS ON) if(UNIX) diff --git a/configure.ac b/configure.ac index 258f96c..eb101cb 100644 --- a/configure.ac +++ b/configure.ac @@ -786,6 +786,7 @@ AC_LANG_POP(C++) ## This needs to be exposed for the library info file even if the HL ## library is disabled. AC_SUBST([HDF5_HL]) +AC_SUBST([HDF5_HL_TOOLS]) ## The high-level library is enabled unless the build mode is clean. if test "X-$BUILD_MODE" = "X-clean" ; then @@ -802,6 +803,9 @@ HL="" ## Fortran high-level library AC_SUBST(HL_FOR) HL_FOR="" +## Tools high-level library +AC_SUBST(HL_TOOLS) +HL_TOOLS="" AC_MSG_CHECKING([if the high-level library is enabled]) AC_ARG_ENABLE([hl], @@ -820,6 +824,21 @@ else AC_MSG_RESULT([no]) fi +AC_MSG_CHECKING([if the high-level tools are enabled]) +AC_ARG_ENABLE([hltools], + [AS_HELP_STRING([--enable-hltools], + [Enable the high-level tools. + [default=yes)] + ])], + [HDF5_HL_TOOLS=$enableval]) + +if test "X${HDF5_HL}" = "Xyes" -a "X-$HDF5_HL_TOOLS" = "X-yes"; then + AC_MSG_RESULT([yes]) + HL_TOOLS="tools" +else + AC_MSG_RESULT([no]) +fi + ## ---------------------------------------------------------------------- ## Check which archiving tool to use. This needs to be done before @@ -1102,29 +1121,35 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then AC_SUBST([DOXYGEN_HTML_FOOTER]) AC_SUBST([DOXYGEN_HTML_EXTRA_STYLESHEET]) AC_SUBST([DOXYGEN_HTML_EXTRA_FILES]) + AC_SUBST([DOXYGEN_TAG_FILE]) AC_SUBST([DOXYGEN_SERVER_BASED_SEARCH]) AC_SUBST([DOXYGEN_EXTERNAL_SEARCH]) AC_SUBST([DOXYGEN_SEARCHENGINE_URL]) + AC_SUBST([DOXYGEN_STRIP_FROM_PATH]) + AC_SUBST([DOXYGEN_PREDEFINED]) # SRCDIR Environment variables used inside doxygen macro for the source location: DOXYGEN_PACKAGE=${PACKAGE_NAME} DOXYGEN_VERSION_STRING=${PACKAGE_VERSION} DOXYGEN_INCLUDE_ALIASES='$(SRCDIR)/doxygen/aliases' DOXYGEN_PROJECT_LOGO='$(SRCDIR)/doxygen/img/HDFG-logo.png' - DOXYGEN_PROJECT_BRIEF= + DOXYGEN_PROJECT_BRIEF='C-API Reference' DOXYGEN_INPUT_DIRECTORY='$(SRCDIR) $(SRCDIR)/doxygen/dox' DOXYGEN_OPTIMIZE_OUTPUT_FOR_C=YES DOXYGEN_MACRO_EXPANSION=YES DOXYGEN_OUTPUT_DIRECTORY=hdf5lib_docs - DOXYGEN_EXAMPLES_DIRECTORY='$(SRCDIR)/doxygen/examples $(SRCDIR)/src $(SRCDIR)/examples $(SRCDIR)/test' + DOXYGEN_EXAMPLES_DIRECTORY='$(SRCDIR)/doxygen/dox/cookbook $(SRCDIR)/doxygen/examples $(SRCDIR)/src $(SRCDIR)/examples $(SRCDIR)/test' DOXYGEN_LAYOUT_FILE='$(SRCDIR)/doxygen/hdf5doxy_layout.xml' DOXYGEN_HTML_HEADER='$(SRCDIR)/doxygen/hdf5_header.html' DOXYGEN_HTML_FOOTER='$(SRCDIR)/doxygen/hdf5_footer.html' DOXYGEN_HTML_EXTRA_STYLESHEET='$(SRCDIR)/doxygen/hdf5doxy.css' DOXYGEN_HTML_EXTRA_FILES='$(SRCDIR)/doxygen/hdf5_navtree_hacks.js $(SRCDIR)/doxygen/img/ftv2node.png $(SRCDIR)/doxygen/img/ftv2pnode.png' + DOXYGEN_TAG_FILE=hdf5.tag DOXYGEN_SERVER_BASED_SEARCH=NO DOXYGEN_EXTERNAL_SEARCH=NO DOXYGEN_SEARCHENGINE_URL= + DOXYGEN_STRIP_FROM_PATH='$(SRCDIR)' + DOXYGEN_PREDEFINED='H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD' DX_INIT_DOXYGEN([HDF5], [./doxygen/Doxyfile], [hdf5lib_docs]) @@ -3844,6 +3869,7 @@ AM_CONDITIONAL([BUILD_HDF5_HL_CONDITIONAL], [test "X$HDF5_HL" = "Xyes"]) AM_CONDITIONAL([BUILD_TESTS_CONDITIONAL], [test "X$HDF5_TESTS" = "Xyes"]) AM_CONDITIONAL([BUILD_TESTS_PARALLEL_CONDITIONAL], [test -n "$TESTPARALLEL"]) AM_CONDITIONAL([BUILD_TOOLS_CONDITIONAL], [test "X$HDF5_TOOLS" = "Xyes"]) +AM_CONDITIONAL([BUILD_TOOLS_HL_CONDITIONAL], [test "X$HDF5_HL_TOOLS" = "Xyes"]) AM_CONDITIONAL([BUILD_DOXYGEN_CONDITIONAL], [test "X$HDF5_DOXYGEN" = "Xyes"]) ## ---------------------------------------------------------------------- diff --git a/doc/contributing.md b/doc/contributing.md index 7f9e8d3..d32ab4d 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -1,10 +1,10 @@ # How to contribute to HDF5 -The HDF Group encourages community members to contribute to the HDF5 project. We accept and are very grateful for any contributions, +The HDF Group encourages community members to contribute to the HDF5 project. We accept and are very grateful for any contributions, from minor typos and bug fixes to new features. The HDF Group is committed to work with the code contributors and make contribution process enjoyable and straightforward. -This document describes guiding principles for the HDF5 code contributors and does not pretend to address any possible -contribution. If in doubt, please do not hesitate to ask us for guidance. +This document describes guiding principles for the HDF5 code contributors and does not pretend to address any possible +contribution. If in doubt, please do not hesitate to ask us for guidance. ***Note that no contribution may be accepted unless the donor agrees with the HDF Group software license terms found in the COPYING file in every branch's top source directory.*** @@ -23,38 +23,38 @@ The process for contributing code to HDF5 is as follows: * Open an issue on [HDF5 GitHub](https://github.com/HDFGroup/hdf5/issues). -> This step is ***required*** unless the change is minor (e.g., typo fix). +> This step is ***required*** unless the change is minor (e.g., typo fix). * Fork the [HDF5](https://github.com/HDFGroup/hdf5) repository. * Make the desired changes to the HDF5 software. * New features should always go to _develop_ branch first and later should be merged to the appropriate maintenance branches. - * Bug fixes should go to all appropriate branches (_develop_ and maintenance). + * Bug fixes should go to all appropriate branches (_develop_ and maintenance). * Build and test your changes. Detailed instructions on building and testing HDF5 can be found in the `INSTALL*` files in the `release_docs` directory. * Push your changes to GitHub. * Issue a pull request and address any code formatting and testing issues reported. Once a pull request is correctly formatted and passes **ALL** CI tests, it will be reviewed and evaluated by The HDF Group developers and HDF5 community members who can approve pull requests. -The HDF Group developers will work with you to ensure that the pull request satisfies the acceptance criteria described in the next section. +The HDF Group developers will work with you to ensure that the pull request satisfies the acceptance criteria described in the next section. # Acceptance criteria for a pull request <A NAME="criteria"></A> We appreciate every contribution we receive, but we may not accept them all. Those that we *do* satisfy the following criteria: -* **The pull request has a clear purpose** - What does the pull request address? How does it benefit the HDF5 community? -If the pull request does not have a clear purpose and benefits, it will not be accepted. +* **The pull request has a clear purpose** - What does the pull request address? How does it benefit the HDF5 community? +If the pull request does not have a clear purpose and benefits, it will not be accepted. * **The pull request is documented** - The HDF5 developers must understand not only *what* a change is doing, but *how* it is doing it. - Documenting the code makes it easier for us to understand your patch and maintain the code in the future. + Documenting the code makes it easier for us to understand your patch and maintain the code in the future. -* **The pull request passes HDF5 regression testing** - Any issue fixed or functionality added should be accompanied by the corresponding -tests and pass HDF5 regression testing run by The HDF Group. We do not expect you to perform comprehensive testing across multiple platforms -before we accept the pull request. If the pull request does not pass regression testing after the merge, The HDF Group developers will work with you on the fixes. +* **The pull request passes HDF5 regression testing** - Any issue fixed or functionality added should be accompanied by the corresponding +tests and pass HDF5 regression testing run by The HDF Group. We do not expect you to perform comprehensive testing across multiple platforms +before we accept the pull request. If the pull request does not pass regression testing after the merge, The HDF Group developers will work with you on the fixes. -* **The pull request does not compromise the principles behind HDF5** - HDF5 has a 100% commitment to backward compatibility. +* **The pull request does not compromise the principles behind HDF5** - HDF5 has a 100% commitment to backward compatibility. * Any file ever created with HDF5 must be readable by any future version of HDF5. If your patch's purpose is to modify the HDF5 data model or file format, - **please** discuss this with us first. File format changes and features required by those changes can be introduced only in a new major release. - * HDF5 has a commitment to remaining *machine-independent*; data created on one platform/environment/architecture **must** remain readable by HDF5 on any other. + **please** discuss this with us first. File format changes and features required by those changes can be introduced only in a new major release. + * HDF5 has a commitment to remaining *machine-independent*; data created on one platform/environment/architecture **must** remain readable by HDF5 on any other. * For binary compatibility, no changes are allowed to public APIs and data structures in the maintenance releases; new APIs can be added. * **New features are documented** - Any new features should have proper documentation; talk to us if you have any questions. @@ -64,7 +64,7 @@ before we accept the pull request. If the pull request does not pass regression Please make sure that you check the items applicable to your pull request: -* Code +* Code * [ ] Does the pull request have a corresponding GitHub issue and clear purpose? * [ ] Does the pull request follow HDF5 best practices (naming conventions, code portability, code structure, etc.)? <<TODO: link to the document>> * [ ] If changes were done to Autotools build, were they added to CMake and vice versa? @@ -74,7 +74,7 @@ Please make sure that you check the items applicable to your pull request: * Documentation * [ ] Was the change described in the release_docs/RELEASE.txt file? * [ ] Was MANIFEST updated if new files had been added to the source? - * [ ] Was the new function documented in the corresponding public header file using Doxygen? <<TODO: link to Doxygen instructions>> + * [ ] Was the new function documented in the corresponding public header file using [Doxygen](https://docs.hdfgroup.org/hdf5/develop/_r_m_t.html)? * [ ] Was new functionality documented for the HDF5 community (the level of documentation depends on the feature; ask us what would be appropriate) * Testing * [ ] Does the pull request have tests? @@ -83,4 +83,3 @@ Please make sure that you check the items applicable to your pull request: We want as many contributions as we can get, and we are here to help. Feel free to reach out to us if you have any questions Thank you for your contribution! - diff --git a/doxygen/CMakeLists.txt b/doxygen/CMakeLists.txt new file mode 100644 index 0000000..36ce590 --- /dev/null +++ b/doxygen/CMakeLists.txt @@ -0,0 +1,46 @@ +cmake_minimum_required (VERSION 3.12) +project (HDF5_DOXYGEN C) + +#----------------------------------------------------------------------------- +# Option to build documentation +#----------------------------------------------------------------------------- +if (DOXYGEN_FOUND) + set (DOXYGEN_PACKAGE ${HDF5_PACKAGE_NAME}) + set (DOXYGEN_VERSION_STRING ${HDF5_PACKAGE_VERSION_STRING}) + set (DOXYGEN_INCLUDE_ALIASES_PATH ${HDF5_DOXYGEN_DIR}) + set (DOXYGEN_INCLUDE_ALIASES aliases) + set (DOXYGEN_VERBATIM_VARS DOXYGEN_INCLUDE_ALIASES) + set (DOXYGEN_PROJECT_LOGO ${HDF5_DOXYGEN_DIR}/img/HDFG-logo.png) + set (DOXYGEN_PROJECT_BRIEF "C-API Reference") + set (DOXYGEN_INPUT_DIRECTORY "${HDF5_SOURCE_DIR} ${HDF5_DOXYGEN_DIR}/dox ${HDF5_GENERATED_SOURCE_DIR}") + set (DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) + set (DOXYGEN_MACRO_EXPANSION YES) + set (DOXYGEN_OUTPUT_DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs) + set (DOXYGEN_EXAMPLES_DIRECTORY "${HDF5_DOXYGEN_DIR}/dox/cookbook ${HDF5_DOXYGEN_DIR}/examples ${HDF5_SRC_DIR} ${HDF5_SOURCE_DIR}/examples ${HDF5_TEST_SRC_DIR}") + set (DOXYGEN_LAYOUT_FILE ${HDF5_DOXYGEN_DIR}/hdf5doxy_layout.xml) + set (DOXYGEN_HTML_HEADER ${HDF5_DOXYGEN_DIR}/hdf5_header.html) + set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html) + set (DOXYGEN_HTML_EXTRA_STYLESHEET ${HDF5_DOXYGEN_DIR}/hdf5doxy.css) + set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png") + set (DOXYGEN_TAG_FILE ${HDF5_BINARY_DIR}/hdf5.tag) + set (DOXYGEN_SERVER_BASED_SEARCH NO) + set (DOXYGEN_EXTERNAL_SEARCH NO) + set (DOXYGEN_SEARCHENGINE_URL) + set (DOXYGEN_STRIP_FROM_PATH ${HDF5_SOURCE_DIR}) + set (DOXYGEN_PREDEFINED "H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD") + +# This configure and individual custom targets work together + # Replace variables inside @@ with the current values + configure_file (${HDF5_DOXYGEN_DIR}/Doxyfile.in ${HDF5_BINARY_DIR}/Doxyfile @ONLY) + + install ( + DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs/html + DESTINATION ${HDF5_INSTALL_DATA_DIR} + COMPONENT Documents + ) + + if (NOT TARGET doxygen) + add_custom_target (doxygen) + endif () + +endif () diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 29f3028..44d9974 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -170,7 +170,7 @@ FULL_PATH_NAMES = YES # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = +STRIP_FROM_PATH = @DOXYGEN_STRIP_FROM_PATH@ # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -858,16 +858,21 @@ FILE_PATTERNS = H5*public.h \ H5FDcore.h \ H5FDdirect.h \ H5FDfamily.h \ + H5FDhdfs.h \ H5FDlog.h \ + H5FDmirror.h \ H5FDmpi.h \ H5FDmpio.h \ H5FDmulti.h \ + H5FDros3.h \ H5FDsec2.h \ + H5FDsplitter.h \ H5FDstdio.h \ H5FDwindows.h \ H5VLconnector.h \ H5VLconnector_passthru.h \ H5VLnative.h \ + H5Zdevelop.h \ H5version.h \ *.dox @@ -1121,13 +1126,6 @@ CLANG_DATABASE_PATH = ALPHABETICAL_INDEX = YES -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored @@ -2177,7 +2175,7 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = H5_HAVE_PARALLEL +PREDEFINED = @DOXYGEN_PREDEFINED@ # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The @@ -2221,7 +2219,7 @@ TAGFILES = # tag file that is based on the input files it reads. See section "Linking to # external documentation" for more information about the usage of tag files. -GENERATE_TAGFILE = +GENERATE_TAGFILE = @DOXYGEN_TAG_FILE@ # If the ALLEXTERNALS tag is set to YES, all external class will be listed in # the class index. If set to NO, only the inherited external classes will be diff --git a/doxygen/aliases b/doxygen/aliases index af43902..06c3445 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -16,11 +16,17 @@ ALIASES += success{1}="\Bold{Success:} \1" ALIASES += failure{1}="\Bold{Failure:} \1" ALIASES += herr_t="Returns a non-negative value if successful; otherwise returns a negative value." +ALIASES += herr_t_iter="\li Zero causes the iterator to continue, returning zero when the iteration is complete. \li A positive value causes the iterator to immediately return that positive value, indicating short-circuit success. \li A negative value causes the iterator to immediately return that value, indicating failure." ALIASES += hid_t{1}="Returns a \1 identifier if successful; otherwise returns #H5I_INVALID_HID. " ALIASES += hid_ti{1}="Returns an \1 identifier if successful; otherwise returns #H5I_INVALID_HID. " ALIASES += hid_tv{1}="Returns an \1 identifier if successful; otherwise returns a negative value. " ALIASES += htri_t="Returns zero (false), a positive (true) or a negative (failure) value." +ALIASES += api_vers_2{3}="\1() is a macro that is mapped to either \2() or \3().\n\see \ref api-compat-macros" +ALIASES += api_vers_3{4}="\1() is a macro that is mapped to either \2() or \3() or \4().\n\see \ref api-compat-macros" + +ALIASES += deprecation_note{1}="\deprecated Superseded by \1." + ################################################################################ # General ################################################################################ @@ -131,6 +137,8 @@ ALIASES += map_id{1}="\param[in] \1 Map identifier" # Property lists ################################################################################ +ALIASES += plist_unused{1}="\note The \p \1 parameter is currently not used; specify #H5P_DEFAULT." + ALIASES += aapl_id="\param[in] aapl_id Attribute access property list identifier" ALIASES += aapl_id{1}="\param[in] \1 Attribute access property list identifier" @@ -217,9 +225,8 @@ ALIASES += es_id{1}="\param[in] \1 Event set identifier" # Others ################################################################################ -ALIASES += estack_id="\param[in] estack_id Error stack identifier" -ALIASES += estack_id{1}="\param[in] \1 Error stack identifier" ALIASES += cpp_c_api_note="\attention \Bold{C++ Developers using HDF5 C-API functions beware:}\n Several functions in this C-API take function pointers or callbacks as arguments. Examples include H5Pset_elink_cb(), H5Pset_type_conv_cb(), H5Tconvert(), and H5Ewalk2(). Application code must ensure that those callback functions return normally such to allow the HDF5 to manage its resources and maintain a consistent state. For instance, those functions must not use the C \c setjmp / \c longjmp mechanism to leave those callback functions. Within the context of C++, any exceptions thrown within the callback function must be caught, such as with a \Code{catch(…)} statement. Any exception state can be placed within the provided user data function call arguments, and may be thrown again once the calling function has returned. Exceptions raised and not handled inside the callback are not supported as it might leave the HDF5 library in an inconsistent state. Similarly, using C++20 coroutines cannot be used as callbacks, since they do not support plain return statements. If a callback function yields execution to another C++20 coroutine calling HDF5 functions as well, this may lead to undefined behavior." +ALIASES += par_compr_note="\attention If you are planning to use compression with parallel HDF5, ensure that calls to H5Dwrite() occur in collective mode. In other words, all MPI ranks (in the relevant communicator) call H5Dwrite() and pass a dataset transfer property list with the MPI-IO collective option property set to #H5FD_MPIO_COLLECTIVE_IO.\n Note that data transformations are currently \Bold{not} supported when writing to datasets in parallel and with compression enabled." ALIASES += sa_metadata_ops="\sa \li H5Pget_all_coll_metadata_ops() \li H5Pget_coll_metadata_write() \li H5Pset_all_coll_metadata_ops() \li H5Pset_coll_metadata_write() \li \ref maybe_metadata_reads" ################################################################################ @@ -241,6 +248,95 @@ ALIASES += ref_vlen_strings="\Emph{Creating variable-length string datatypes}" ALIASES += ref_vol_doc="VOL documentation" ################################################################################ +# RFCs +################################################################################ + +ALIASES += ref_rfc20210528="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_multi_thread.pdf\">Multi-Thread HDF5</a>" +ALIASES += ref_rfc20190923="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/2019-09-23-RFC_VOL_feature_flags.pdf\">Virtual Object Layer (VOL) API Compatibility</a>" +ALIASES += ref_rfc20190410="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_VFD_Plugin.docx.pdf\">A Plugin Interface for HDF5 Virtual File Drivers</a>" +ALIASES += ref_rfc20181231="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Min_Obj_Headers_181231.pdf\">Dataset Object Header Size</a>" +ALIASES += ref_rfc20181220="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/3.2.1_3.2.2_deliverable_181220_v4.pdf\">MS 3.2 – Addressing Scalability: Scalability of open, close, flush CASE STUDY: CGNS Hotspot analysis of CGNS cgp_open</a>" +ALIASES += ref_rfc20180620="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-Chunking%20Functions-2018-06-20-v3.docx.pdf\">Chunk query functionality in HDF5</a>" +ALIASES += ref_rfc20180610="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/VFD_SWMR_RFC_200916.pdf\">VFD SWMR</a>" +ALIASES += ref_rfc20180321="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-API_Contexts-2018-03-21.docx.pdf\">API Contexts</a>" +ALIASES += ref_rfc20180125="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/enhance_h5clear.docx.pdf\">Enhancement to the tool <tt>h5clear</tt></a>" +ALIASES += ref_rfc20170707="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/H5Sencode_format.docx.pdf\"><tt>H5Sencode/H5Sdecode</tt> Format Change</a>" +ALIASES += ref_rfc20160105="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-bounds.pdf\">Setting Bounds for Object Creation in HDF5 1.10.0</a>" +ALIASES += ref_rfc20150915="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/2015-09-28-RFC-HDF5-1.10.0-File-Format-Superblock-Changes-EP.docx.pdf\">File Format Changes in HDF5 1.10.0</a>" +ALIASES += ref_rfc20150709="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-Page_Buffering.pdf\">Page Buffering</a>" +ALIASES += ref_rfc20150615="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/cache_image_RFC_150929-QAK.docx.pdf\">Metadata Cache Image</a>" +ALIASES += ref_rfc20150429="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/new_datatypes.pdf\">New Datatypes</a>" +ALIASES += ref_rfc20150424="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-CollectiveMetadataWrites.pdf\">Collective Metadata Writes</a>" +ALIASES += ref_rfc20150423="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-CollectiveMetadataReads.pdf\">Enabling Collective Metadata Reads</a>" +ALIASES += ref_rfc20150301="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/sent_RFC_format_convert-v3.docx.pdf\">The Tool to Handle HDF5 File Format Compatibility for Chunked Datasets</a>" +ALIASES += ref_rfc20150212="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_H5LTget_hardlinkds.docx.pdf\"><tt>H5LTget_hardlinks</tt> – High-level API to list all the hard links to an object</a>" +ALIASES += ref_rfc20150205="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_F2003_v6.docx.pdf\">HDF5 Fortran Wrappers Maintenance: Dropping Support for Non-Fortran 2003 Standard Compliant Compilers</a>" +ALIASES += ref_rfc20150202="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20New%20Autotools%20Behavior.docx.pdf\">New Autotools Behavior</a>" +ALIASES += ref_rfc20141210="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/HDF5-VDS-requirements-use-cases-2014-12-10.pdf\">HDF5 Virtual Dataset</a>" +ALIASES += ref_rfc20141201="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20filter%20memory%20issues%20on%20Windows.docx.pdf\">Allocate/Free Mismatches in HDF5 Filter Code on Windows</a>" +ALIASES += ref_rfc20140916="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_VOL.pdf\">Virtual Object Layer</a>" +ALIASES += ref_rfc20140827="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/CompressNChunk_RFC.pdf\">Chunking and Compression Performance Tool Requirements</a>" +ALIASES += ref_rfc20140729="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/h5fis_accessible.pdf\">Replacing H5Fis_hdf5() with H5Fis_accessible()</a>" +ALIASES += ref_rfc20140722="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/64bit_hid_t-v1.docx.pdf\">Switching to a 64-bit <tt>hid_t</tt> Space in HDF5</a>" +ALIASES += ref_rfc20140717="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/analysis_ext.pdf\">Data Analysis Extensions</a>" +ALIASES += ref_rfc20140707="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/2014-08-28-RFC_VOL.pdf\">Virtual Object Layer</a>" +ALIASES += ref_rfc20140524="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-Why%20does%20not%20compression%20work-GH-EP.docx.pdf\">HDF5 Compression Demystified</a>" +ALIASES += ref_rfc20140318="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20H5free_memory%20v2.pdf\">Freeing Memory Allocated by the HDF5 Library</a>" +ALIASES += ref_rfc20140313="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-Compat-Tool-v2.docx.pdf\">Options to handle compatibility issues for HDF5 files</a>" +ALIASES += ref_rfc20140224="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/Design-MetadataCache-Logging-THG20140224-v4.pdf\">Design: Metadata Cache Logging</a>" +ALIASES += ref_rfc20131211="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20H5Ocork%20v5%20new%20fxn%20names.pdf\">Fine-Grained Control of Metadata Cache Flushes</a>" +ALIASES += ref_rfc20130930="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-Read-Attempts-for-Metadata-with-Checksum-v3.pdf\">Read Attempts for Metadata with Checksum</a>" +ALIASES += ref_rfc20130919="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/core%20CFD%20paging%20v5.docx.pdf\">Core VFD Backing Store Paged Writes</a>" +ALIASES += ref_rfc20130630="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/Design-HDF5-FlushDependencyTesting-20130630-v1.1.pdf\">Flush Dependency Testing</a>" +ALIASES += ref_rfc20130316="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/HDF5DynamicallyLoadedFilters.pdf\">HDF5 Dynamically Loaded Filters</a>" +ALIASES += ref_rfc20121114="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/DECTRIS%20Integration%20RFC%202012-11-29.pdf\">Direct Chunk Write</a>" +ALIASES += ref_rfc20121024="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/FileSpaceManagement.pdf\">HDF5 File Space Management</a>" +ALIASES += ref_rfc20120828="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/H5HPC_MultiDset_RW_IO_RFC_v4_20130320.docx.pdf\">New HDF5 API Routines for HPC Applications</a>" +ALIASES += ref_rfc20120523="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/paged_aggregation.pdf\">HDF5 File Space Management: Paged Aggregation</a>" +ALIASES += ref_rfc20120501="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/HDF5FileImageOperations.pdf\">HDF5 File Image Operations</a>" +ALIASES += ref_rfc20120305="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20PHDF5%20Consistency%20Semantics%20MC%20120328.docx.pdf\">Enabling a Strict Consistency Semantics Model in Parallel HDF5</a>" +ALIASES += ref_rfc20120220="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/h5repack_improve_hyperslab_over_chunked_dataset_v1.pdf\"><tt>h5repack</tt>: Improved Hyperslab selections for Large Chunked Datasets</a>" +ALIASES += ref_rfc20120120="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/2012-1-25-Maintainers-guide-for-datatype.docx.pdf\">A Maintainer’s Guide for the Datatype Module in HDF5 Library</a>" +ALIASES += ref_rfc20120104="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_actual_io_v4-1_done.docx.pdf\">Actual I/O Mode</a>" +ALIASES += ref_rfc20111119="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-H5Ocompare-review_v6.pdf\">New public functions to handle comparison</a>" +ALIASES += ref_rfc20110825="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/2011-08-31-RFC_H5Ocopy_Named_DT_v2.docx.pdf\">Merging Named Datatypes in H5Ocopy()</a>" +ALIASES += ref_rfc20110811="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Enhancement_Hyperslab_Selection-1.4.docx.pdf\">Expanding the HDF5 Hyperslab Selection Interface</a>" +ALIASES += ref_rfc20110726="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/metadata_aggregation_RFC_v03.docx.pdf\">HDF5 File Space Allocation and Aggregation</a>" +ALIASES += ref_rfc20110614="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_h5dump_refactor_v3.docx.pdf\"> Refactor <tt>h5dump</tt> to Improve Maintenance</a>" +ALIASES += ref_rfc20110329="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Tools_Extlink_Cache_v3_r2.docx.pdf\">Support External Link Open File Cache in HDF5 Tools</a>" +ALIASES += ref_rfc20110118="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20for%20h5diff%20Attribute%20Comparisons_v7.docx.pdf\"><tt>h5diff</tt> Attribute Comparisons</a>" +ALIASES += ref_rfc20101122="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_swmr_timeouts_v2.docx.pdf\">SWMR Timeouts</a>" +ALIASES += ref_rfc20101104="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/CacheExternalLinkFileOpens.pdf\">Caching Files Opened Through External Links</a>" +ALIASES += ref_rfc20101018="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/HDF5-comparisons_v3-RFC-2011-08-03.pdf\">HDF5 File and Object Comparison Specification</a>" +ALIASES += ref_rfc20100902="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/H5edit-RFC-Draft-v5.pdf\"><tt>h5edit</tt> – An HDF5 File Editing Tool</a>" +ALIASES += ref_rfc20100727="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_HDF5_reservedCharacters-v2.pdf\">Reserved Characters for HDF5 Applications</a>" +ALIASES += ref_rfc20100726="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/H5HPC_RFC-2010-09-28.pdf\">High-Level HDF5 API routines for HPC Applications</a>" +ALIASES += ref_rfc20100511="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_h5diff_exclude_obj_v1_3.pdf\"><tt>h5diff</tt> – Exclude Object(s) from Comparison</a>" +ALIASES += ref_rfc20100422="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_gen_attribute_tool_v2_f.pdf\">Generating attributes into an object with a tool</a>" +ALIASES += ref_rfc20100312="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Support_HDF518_in_Tools.pdf\">Supporting HDF5 1.8 in HDF5 Command Line Tools</a>" +ALIASES += ref_rfc20091218="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RCF_h5diff_link_v1.2.docx.pdf\">Supporting soft-link and external-link for <tt>h5diff</tt></a>" +ALIASES += ref_rfc20090907="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Tools_Lib_v2.pdf\">HDF5 Tools Library Functions</a>" +ALIASES += ref_rfc20090612="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_h5diff_default_epsilon.pdf\">Default EPSILON values for comparing floating point data</a>" +ALIASES += ref_rfc20081218="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_h5diff_NonComparable.pdf\">Reporting of Non-Comparable Datasets by <tt>h5diff</tt></a>" +ALIASES += ref_rfc20080915="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/FileFreeSpacePerformance.pdf\">Performance Report for Free-space Manager</a>" +ALIASES += ref_rfc20080904="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/ExternalLinkFileAccessProperty.pdf\">Setting File Access Property List for accessing External Link</a>" +ALIASES += ref_rfc20080301="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/DynamicTransformations_RFC.pdf\">Dynamic Transformations to HDF5 Data</a>" +ALIASES += ref_rfc20080209="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-Using-SVN-branching-Feb9.pdf\">Using SVN branching to improve software development process at THG</a>" +ALIASES += ref_rfc20080206="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-HIS-REL-1.8_Feb6.pdf\">Maintaining the <tt>HISTORY.txt</tt> and <tt>RELEASE.txt</tt> files in HDF5</a>" +ALIASES += ref_rfc20071111="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/AURA-corruption-2007-11-12.pdf\">Addressing HDF5 file corruption issue</a>" +ALIASES += ref_rfc20071018="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_NaNsHDF5.pdf\"><tt>NaN</tt> detection in HDF5</a>" +ALIASES += ref_rfc20070801="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/Metadata_Journaling_RFC.pdf\">Metadata Journaling to Improve Crash Survivability</a>" +ALIASES += ref_rfc20070413="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/API_Compatibility_RFC.txt.pdf\">API Compatibility Strategies for HDF5</a>" +ALIASES += ref_rfc20070115="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/PrivateHeap.pdf\">A 'Private' Heap for HDF5</a>" +ALIASES += ref_rfc20060623="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/coll_ind_dd6.pdf\">Performance Comparison of Collective I/O and Independent I/O with Derived Datatypes</a>" +ALIASES += ref_rfc20060604="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/h5stat_spec_v3_2006-06-04.pdf\"><tt>h5stat</tt> tool</a>" +ALIASES += ref_rfc20060505="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/Simple%20Performance%20Test%20on%20Fletcher32%20Filter.pdf\">Simple Performance Test on Fletcher32 Filter</a>" +ALIASES += ref_rfc20060410="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/h5chk_Requirements.pdf\">Requirement Specifications of an HDF5 File Format Validation Tool</a>" +ALIASES += ref_rfc20060317="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/sec2driver-RFC.pdf\">Proposed changes to the <tt>sec2</tt> driver </a>" +ALIASES += ref_rfc20060124="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/FITS%20to%20HDF5%20mapping.pdf\">Mapping FITS data to HDF5</a>" +ALIASES += ref_rfc20040811="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/text-dtype.htm.pdf\">Conversion Between Text and Datatype</a>" + +################################################################################ # The Usual Suspects ################################################################################ diff --git a/doxygen/dox/APIVersions.dox b/doxygen/dox/APIVersions.dox new file mode 100644 index 0000000..3658f06 --- /dev/null +++ b/doxygen/dox/APIVersions.dox @@ -0,0 +1,173 @@ +/** + * \ingroup H5A + * \def H5Acreate + * \api_vers_2{H5Acreate,H5Acreate1,H5Acreate2} + */ + +/** + * \ingroup H5A + * \def H5Aiterate + * \api_vers_2{H5Aiterate,H5Aiterate1,H5Aiterate2} + */ + +/** + * \ingroup H5D + * \def H5Dcreate + * \api_vers_2{H5Dcreate,H5Dcreate1,H5Dcreate2} + */ + +/** + * \ingroup H5E + * \def H5Eget_auto + * \api_vers_2{H5Eget_auto,H5Eget_auto1,H5Eget_auto2} + */ + +/** + * \ingroup H5E + * \def H5Eprint + * \api_vers_2{H5Eprint,H5Eprint1,H5Eprint2} + */ + +/** + * \ingroup H5E + * \def H5Epush + * \api_vers_2{H5Epush,H5Epush1,H5Epush2} + */ + +/** + * \ingroup H5E + * \def H5Eset_auto + * \api_vers_2{H5Eset_auto,H5Eset_auto1,H5Eset_auto2} + */ + +/** + * \ingroup H5E + * \def H5Ewalk + * \api_vers_2{H5Ewalk,H5Ewalk1,H5Ewalk2} + */ + +/** + * \ingroup H5F + * \def H5Fget_info + * \api_vers_2{H5Fget_info,H5Fget_info1,H5Fget_info2} + */ + +/** + * \ingroup H5G + * \def H5Gcreate + * \api_vers_2{H5Gcreate,H5Gcreate1,H5Gcreate2} + */ + +/** + * \ingroup H5G + * \def H5Gopen + * \api_vers_2{H5Gopen,H5Gopen1,H5Gopen2} + */ + +/** + * \ingroup H5L + * \def H5Lget_info + * \api_vers_2{H5Lget_info,H5Lget_info1,H5Lget_info2} + */ + +/** + * \ingroup H5L + * \def H5Lget_info_by_idx + * \api_vers_2{H5Lget_info_by_idx,H5Lget_info_by_idx1,H5Lget_info_by_idx2} + */ + +/** + * \ingroup TRAV + * \def H5Literate + * \api_vers_2{H5Literate,H5Literate1,H5Literate2} + */ + +/** + * \ingroup TRAV + * \def H5Literate_by_name + * \api_vers_2{H5Literate_by_name,H5Literate_by_name1,H5Literate_by_name2} + */ + +/** + * \ingroup TRAV + * \def H5Lvisit + * \api_vers_2{H5Lvisit,H5Lvisit1,H5Lvisit2} + */ + +/** + * \ingroup TRAV + * \def H5Lvisit_by_name + * \api_vers_2{H5Lvisit_by_name,H5Lvisit_by_name1,H5Lvisit_by_name2} + */ + +/** + * \ingroup H5O + * \def H5Oget_info + * \api_vers_3{H5Oget_info,H5Oget_info1,H5Oget_info2,H5Oget_info3} + */ + +/** + * \ingroup H5O + * \def H5Oget_info_by_idx + * \api_vers_3{H5Oget_info_by_idx,H5Oget_info_by_idx1,H5Oget_info_by_idx2,H5Oget_info_by_idx3} + */ + +/** + * \ingroup H5O + * \def H5Oget_info_by_name + * \api_vers_3{H5Oget_info_by_name,H5Oget_info_by_name1,H5Oget_info_by_name2,H5Oget_info_by_name3} + */ + +/** + * \ingroup H5O + * \def H5Ovisit + * \api_vers_3{H5Ovisit,H5Ovisit1,H5Ovisit2,H5Ovisit3} + */ + +/** + * \ingroup H5O + * \def H5Ovisit_by_name + * \api_vers_3{H5Ovisit_by_name,H5Ovisit_by_name1,H5Ovisit_by_name2,H5Ovisit_by_name3} + */ + +/** + * \ingroup H5R + * \def H5Rdereference + * \api_vers_2{H5Rdereference,H5Rdereference1,H5Rdereference2} + */ + +/** + * \ingroup H5R + * \def H5Rget_obj_type + * \api_vers_3{H5Rget_obj_type,H5Rget_obj_type1,H5Rget_obj_type2,H5R_get_obj_type3} + */ + +/** + * \ingroup H5S + * \def H5Sencode + * \api_vers_2{H5Sencode,H5Sencode1,H5Sencode2} + */ + +/** + * \ingroup H5T + * \def H5Tcommit + * \api_vers_2{H5Tcommit,H5Tcommit1,H5Tcommit2} + */ + +/** + * \ingroup H5T + * \def H5Topen + * \api_vers_2{H5Topen,H5Topen1,H5Topen2} + */ + +/** + * \ingroup ARRAY + * \def H5Tarray_create + * \api_vers_2{H5Tarray_create,H5Tarray_create1,H5Tarray_create2} + */ + +/** + * \ingroup ARRAY + * \def H5Tget_array_dims + * \api_vers_2{H5Tget_array_dims,H5Tget_array_dims1,H5Tget_array_dims2} + */ diff --git a/doxygen/dox/About.dox b/doxygen/dox/About.dox index 3be9202..32930a8 100644 --- a/doxygen/dox/About.dox +++ b/doxygen/dox/About.dox @@ -1,5 +1,7 @@ /** \page About About +\section about_history History + The implementation of this documentation set is based on the fantastic work of the <a href="https://eigen.tuxfamily.org/index.php?title=Main_Page">Eigen project</a>. Please refer to their <a href="https://gitlab.com/libeigen/eigen">GitLab repository</a> @@ -8,4 +10,14 @@ and the online version of their Not only does Eigen set a standard as a piece of software, but also as an example of <em>documentation done right</em>. +\section about_documentation Documentation about Documentation + +\li \todo Describe how to add a reference or a new RFC +\li \todo Describe how to add an example +\li \todo Describe how to include plain HTML +\li \todo Describe how to add an API macro +\li \todo Describe the custom commands +\li \todo Describe the S3 bucket layout and update routine +\li \todo Link the RM template + */
\ No newline at end of file diff --git a/doxygen/dox/Cookbook.dox b/doxygen/dox/Cookbook.dox index 4abc896..56523e2 100644 --- a/doxygen/dox/Cookbook.dox +++ b/doxygen/dox/Cookbook.dox @@ -2,4 +2,18 @@ Healthy, everyday recipes for every taste and budget... +\ref Files +\li \ref CB_FreeSpace +\li \ref CB_RemoveUnusedSpace +\li \ref CB_UserBlock + +\ref Attributes +\li \ref CB_LargeAttributes + +\ref Accessibility +\li \ref CB_MaintainCompat + +\ref Performance +\li \ref CB_MDCPerf + */
\ No newline at end of file diff --git a/doxygen/dox/H5Acreate.dox b/doxygen/dox/H5Acreate.dox deleted file mode 100644 index 18d648f..0000000 --- a/doxygen/dox/H5Acreate.dox +++ /dev/null @@ -1,9 +0,0 @@ -/** - * \ingroup H5A - * \def H5Acreate() - * H5Acreate() is a macro that is mapped to either H5Acreate1() or - * H5Acreate2(). - * - * - * \todo Standardize the way we describe these macros! - */ diff --git a/doxygen/dox/H5Aiterate.dox b/doxygen/dox/H5Aiterate.dox deleted file mode 100644 index 46b9bb4..0000000 --- a/doxygen/dox/H5Aiterate.dox +++ /dev/null @@ -1,9 +0,0 @@ -/** - * \ingroup H5A - * \def H5Aiterate() - * H5Aiterate() is a macro that is mapped to either H5Aiterate1() or - * H5Aiterate2(). - * - * - * \todo Standardize the way we describe these macros! - */ diff --git a/doxygen/dox/H5Fget_info.dox b/doxygen/dox/H5Fget_info.dox deleted file mode 100644 index 9b02752..0000000 --- a/doxygen/dox/H5Fget_info.dox +++ /dev/null @@ -1,44 +0,0 @@ -/** - * \ingroup H5F - * \def H5Fget_info() - * H5Fget_info() is a macro that is mapped to either H5Fget_info1() - * or H5Fget_info2(), depending on the needs of the application. - * Similarly, the macro for the \ref H5F_info_t struct is mapped to either - * H5F_info1_t or H5F_info2_t. - * - * Such macros are provided to facilitate application compatibility. - * Their use and mappings are fully described in \ref api-compat-macros. - * - * When both the HDF5 library and the application are built and installed with - * no specific compatibility flags, H5Fget_info() is mapped to the most recent - * version of the function, currently H5Fget_info2(). If the library and/or - * application is compiled for Release 1.8 emulation, H5Fget_info() will be - * mapped to H5Fget_info1(). Since there was no H5Fget_info() function in - * Release 1.6, if the library and/or application is compiled for Release 1.6 - * emulation, H5Fget_info() will be mapped to the most recent version of the - * function, currently H5Fget_info2(). Function-specific flags are available to - * override these settings on a function-by-function basis when the application - * is compiled. - * - * Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * - * \Bold{Global settings}\n - * \li No compatibility flag: H5Fget_info2() and H5F_info2_t - * \li Enable deprecated symbols: H5Fget_info2() and H5F_info2_t - * \li Disable deprecated symbols: H5Fget_info2() and H5F_info2_t - * \li Emulate Release 1.6 interface: H5Fget_info2() and H5F_info2_t - * \li Emulate Release 1.8 interface: H5Fget_info1() and H5F_info1_t - * - * \Bold{Function- and struct-level macros}\n - * \li \Code{H5Fget_info_vers=2}: H5Fget_info2() - * \li \Code{H5Fget_info_vers=1}: H5Fget_info1() - * \li \Code{H5F_info_t_vers=2}: H5F_info2_t - * \li \Code{H5F_info_t_vers=1}: H5F_info1_t - * - * \version 1.10.0 The C function H5Fget_info() and H5F_info_t renamed to - * H5Fget_info1() and H5F_info1_t, respectively, and deprecated - * in this release. The C macro #H5Fget_info, the C function - * H5Fget_info2(), and the struct H5F_info2_t introduced in this - * release. - */ diff --git a/doxygen/dox/H5Lget_info.dox b/doxygen/dox/H5Lget_info.dox deleted file mode 100644 index 2c0971e..0000000 --- a/doxygen/dox/H5Lget_info.dox +++ /dev/null @@ -1,17 +0,0 @@ - /** - * \ingroup LMGT - * \def H5Lget_info() - * H5Lget_info() is a macro that is mapped to either H5Lget_info1() - * or H5Lget_info2() Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in \ref api-compat-macros. - * If the library and/or application is compiled for Release - * 1.12 emulation, H5Lget_info() will be mapped to H5Lget_info2() and - * H5Lget_info1() is deprecated. With earlier versions, H5Lget_info() is mapped to - * H5Lget_info1(). Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * \li No compatibility flag: H5Lget_info2() (using 1.12 source) H5Lget_info1() - * (using 1.10 or 1.8 source) - * \li Emulate Release 1.12: H5Lget_info2() - * \li Emulate Release 1.8 or 1.10 interface: H5Lget_info1() - * - */ diff --git a/doxygen/dox/H5Lget_info_by_idx.dox b/doxygen/dox/H5Lget_info_by_idx.dox deleted file mode 100644 index bf76822..0000000 --- a/doxygen/dox/H5Lget_info_by_idx.dox +++ /dev/null @@ -1,17 +0,0 @@ - /** - * \ingroup LMGT - * \def H5Lget_info_by_idx() - * H5Lget_info_by_idx() is a macro that is mapped to either H5Lget_info_by_idx1() - * or H5Lget_info_by_idx2() Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in \ref api-compat-macros. - * If the library and/or application is compiled for Release - * 1.12 emulation, H5Lget_info_by_idx() will be mapped to H5Lget_info_by_idx2() and - * H5Lget_info_by_idx1() is deprecated. With earlier versions, H5Lget_infoby_idx() is mapped to - * H5Lget_info_by_idx1(). Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * \li No compatibility flag: H5Lget_info_by_idx2() (using 1.12 source) H5Lget_info_by_idx1() - * (using 1.10 or 1.8 source) - * \li Emulate Release 1.12: H5Lget_info_by_idx2() - * \li Emulate Release 1.8 or 1.10 interface: H5Lget_info_by_idx1() - * - */ diff --git a/doxygen/dox/H5Literate.dox b/doxygen/dox/H5Literate.dox deleted file mode 100644 index eaaf2fe..0000000 --- a/doxygen/dox/H5Literate.dox +++ /dev/null @@ -1,20 +0,0 @@ -/** - * \ingroup TRAV - * \def H5Literate() - * H5Literate() is a macro that is mapped to either H5Literate1() or - * H5Literate2() Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * \ref api-compat-macros. If the library and/or application is - * compiled for Release 1.12 emulation, H5Literate() will be mapped to - * H5Literate2() and H5Literate1() is deprecated. With earlier versions, - * H5Literate() is mapped to H5Literate1(). Specific compile-time compatibility - * flags and the resulting mappings are as follows: - * \li No compatibility flag: H5Literate2() (using 1.12 source) H5Literate1() - * (using 1.10 or 1.8 source) - * \li Emulate Release 1.12: H5Literate2() - * \li Emulate Release 1.8 or 1.10 interface: H5Literate1() - * - * \version 1.12.0 The function H5Literate() was renamed to H5Literate1() and - * deprecated in this release. The macro H5Literate() and the - * function H5Literate2() were introduced in this release. - */ diff --git a/doxygen/dox/H5Literate_by_name.dox b/doxygen/dox/H5Literate_by_name.dox deleted file mode 100644 index 5ffd7c6..0000000 --- a/doxygen/dox/H5Literate_by_name.dox +++ /dev/null @@ -1,21 +0,0 @@ -/** - * \ingroup TRAV - * \def H5Literate_by_name() - * H5Literate_by_name() is a macro that is mapped to either - * H5Literate_by_name1() or H5Literate_by_name2() Such macros are provided to - * facilitate application compatibility. Their use and mappings are fully - * described in \ref api-compat-macros. If the library and/or application is - * compiled for Release 1.12 emulation, H5Literate_by_name() will be mapped to - * H5Literate_by_name2() and H5Literate_by_name1() is deprecated. With earlier - * versions, H5Literate_by_name() is mapped to H5Literate_by_name1(). - * Specific compile-time compatibility flags and the resulting mappings are as - * follows: - * \li No compatibility flag: H5Literate_by_name2() (using 1.12 source) - * H5Literate_by_name1() (using 1.10 or 1.8 source) - * \li Emulate Release 1.12: H5Literate_by_name2() - * \li Emulate Release 1.8 or 1.10 interface: H5Literate_by_name1() - * - * \version 1.12.0 The function H5Literate_by_name() was renamed to H5Literate_by_name1() and - * deprecated in this release. The macro H5Literate_by_name() and the - * function H5Literate_by_name2() were introduced in this release. - */ diff --git a/doxygen/dox/H5Lvisit.dox b/doxygen/dox/H5Lvisit.dox deleted file mode 100644 index 2dc547f..0000000 --- a/doxygen/dox/H5Lvisit.dox +++ /dev/null @@ -1,20 +0,0 @@ -/** - * \ingroup TRAV - * \def H5Lvisit() - * H5Lvisit() is a macro that is mapped to either H5Lvisit1() or - * H5Lvisit2() Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * \ref api-compat-macros. If the library and/or application is - * compiled for Release 1.12 emulation, H5Lvisit() will be mapped to - * H5Lvisit2() and H5Lvisit1() is deprecated. With earlier versions, - * H5Lvisit() is mapped to H5Lvisit1(). Specific compile-time compatibility - * flags and the resulting mappings are as follows: - * \li No compatibility flag: H5Lvisit2() (using 1.12 source) H5Lvisit1() - * (using 1.10 or 1.8 source) - * \li Emulate Release 1.12: H5Lvisit2() - * \li Emulate Release 1.8 or 1.10 interface: H5Lvisit1() - * - * \version 1.12.0 The function H5Lvisit() was renamed to H5Lvisit1() and - * deprecated in this release. The macro H5Lvisit() and the - * function H5Lvisit2() were introduced in this release. - */ diff --git a/doxygen/dox/H5Lvisit_by_name.dox b/doxygen/dox/H5Lvisit_by_name.dox deleted file mode 100644 index 691787f..0000000 --- a/doxygen/dox/H5Lvisit_by_name.dox +++ /dev/null @@ -1,20 +0,0 @@ -/** - * \ingroup TRAV - * \def H5Lvisit_by_name() - * H5Lvisit_by_name() is a macro that is mapped to either H5Lvisit_by_name1() or - * H5Lvisit_by_name2() Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * \ref api-compat-macros. If the library and/or application is - * compiled for Release 1.12 emulation, H5Lvisit_by_name() will be mapped to - * H5Lvisit_by_name2() and H5Lvisit_by_name1() is deprecated. With earlier versions, - * H5Lvisit_by_name() is mapped to H5Lvisit_by_name1(). Specific compile-time - * compatibility flags and the resulting mappings are as follows: - * \li No compatibility flag: H5Lvisit_by_name2() (using 1.12 source) H5Lvisit_by_name1() - * (using 1.10 or 1.8 source) - * \li Emulate Release 1.12: H5Lvisit_by_name2() - * \li Emulate Release 1.8 or 1.10 interface: H5Lvisit_by_name1() - * - * \version 1.12.0 The function H5Lvisit_by_name() was renamed to H5Lvisit_by_name1() and - * deprecated in this release. The macro H5Lvisit_by_name() and the - * function H5Lvisit_by_name2() were introduced in this release. - */ diff --git a/doxygen/dox/H5Oget_info.dox b/doxygen/dox/H5Oget_info.dox deleted file mode 100644 index ee4cd1c..0000000 --- a/doxygen/dox/H5Oget_info.dox +++ /dev/null @@ -1,72 +0,0 @@ -/** - * \ingroup H5O - * \def H5Oget_info - * - * #H5Oget_info is a macro that is mapped to: - * \li #H5Oget_info3 - * \li #H5Oget_info1 - * - * \details Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * API Compatibility Macros in HDF5; we urge you to read that - * document closely. - * - * In HDF5 versions 1.12 and after, #H5Oget_info is mapped to - * #H5Oget_info3 and #H5Oget_info1 is deprecated. - * In version 1.10 #H5Oget_info is identical to #H5Oget_info1. - * - * Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * \par - * <table> - * <tr> - * <th>Compatibility setting</th> - * <th>H5Oget_info</th> - * </tr> - * <tr> - * <td>No compatibility flag \n </td> - * <td>#H5Oget_info3 (in release 1.12) \n - * #H5Oget_info1 (in 1.8 or 1.10)</td> - * </tr> - * <tr> - * <td>Emulate Release 1.12</td> - * <td>#H5Oget_info3</td> - * </tr> - * <tr> - * <td>Emulate Release 1.10/1.8 interface</td> - * <td>#H5Oget_info1</td> - * </tr> - * </table> - * - * \note If you are iterating through a lot of different objects to - * retrieve information via the #H5Oget_info family of routines, - * you may see memory building up. This can be due to memory - * allocation for metadata such as object headers and messages - * when the iterated objects are put into the metadata cache. - * \note - * If the memory buildup is not desirable, you can configure a - * smaller cache via #H5Fset_mdc_config or set the file access - * property list via #H5Pset_mdc_config. A smaller sized cache - * will force metadata entries to be evicted from the cache, - * thus freeing the memory associated with the entries. - * - * \version 1.12.0 The macro #H5Oget_info and the function #H5Oget_info3 - * were added, and #H5Oget_info1 was deprecated. - * \version 1.10.5 The macro #H5Oget_info was removed. The functions - * #H5Oget_info1 and #H5Oget_info are identical - * in this release. This change was added to restore the - * broken API compatibility introduced in HDF5-1.10.3. - * \version 1.10.3 The function #H5Oget_info was renamed - * #H5Oget_info1. The macro #H5Oget_info and the function - * #H5Oget_info2 were introduced in this release. - * \version 1.8.15 Added a note about the valid values for the \c version field - * in the H5O_hdr_info_t structure. - * \version 1.8.11 Fortran subroutine introduced in this release. - * \version 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. - * - * \since 1.8.0 - * - */ diff --git a/doxygen/dox/H5Oget_info_by_idx.dox b/doxygen/dox/H5Oget_info_by_idx.dox deleted file mode 100644 index 49b8031..0000000 --- a/doxygen/dox/H5Oget_info_by_idx.dox +++ /dev/null @@ -1,55 +0,0 @@ -/** - * \ingroup H5O - * \def H5Oget_info_by_idx - * - * #H5Oget_info_by_idx is a macro that is mapped to: - * \li #H5Oget_info_by_idx3 - * \li #H5Oget_info_by_idx1 - * - * \details Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * API Compatibility Macros in HDF5; we urge you to read that - * document closely. - * - * In HDF5 versions 1.12 and after, #H5Oget_info_by_idx is mapped to - * #H5Oget_info_by_idx3 and #H5Oget_info_by_idx1 is deprecated. - * In version 1.10 #H5Oget_info_by_idx is identical to #H5Oget_info_by_idx1. - * - * Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * - * \par - * <table> - * <tr> - * <th>Compatibility setting</th> - * <th>H5Oget_info_by_idx</th> - * </tr> - * <tr> - * <td>No compatibility flag \n </td> - * <td>#H5Oget_info_by_idx3 for 1.12 \n - * #H5Oget_info_by_idx1 for 1.8/1.10</td> - * </tr> - * <tr> - * <td>Emulate Release 1.12</td> - * <td>#H5Oget_info_by_idx3</td> - * </tr> - * <tr> - * <td>Emulate Release 1.10/1.8 interface</td> - * <td>#H5Oget_info_by_idx1</td> - * </tr> - * </table> - * - * \version 1.12.0 The macro #H5Oget_info_by_idx and function #H5Oget_info_by_idx3 were added, - * and #H5Oget_info_by_idx1 was deprecated. - * \version 1.10.5 The macro #H5Oget_info_by_idx was removed. The functions - * #H5Oget_info_by_idx and #H5Oget_info_by_idx1 are - * identical in this release. This change was added to restore the - * broken API compatibility introduced in HDF5-1.10.3. - * \version 1.10.3 The function #H5Oget_info_by_idx was renamed #H5Oget_info_by_idx1. - * The macro #H5Oget_info_by_idx and the function #H5Oget_info_by_idx2 - * were introduced in this release. - * \version 1.8.11 Fortran subroutine introduced in this release. - * - * \since 1.8.0 - * - */ diff --git a/doxygen/dox/H5Oget_info_by_name.dox b/doxygen/dox/H5Oget_info_by_name.dox deleted file mode 100644 index 18f7d28..0000000 --- a/doxygen/dox/H5Oget_info_by_name.dox +++ /dev/null @@ -1,58 +0,0 @@ -/** - * \ingroup H5O - * \def H5Oget_info_by_name - * - * #H5Oget_info_by_name is a macro that is mapped to: - * \li #H5Oget_info_by_name3 - * \li #H5Oget_info_by_name1 - * - * \details Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * API Compatibility Macros in HDF5; we urge you to read that - * document closely. - * - * In HDF5 versions 1.12 and after, #H5Oget_info_by_name is mapped to - * #H5Oget_info_by_name3. In version 1.10 #H5Oget_info_by_name is - * identical to #H5Oget_info_by_name1. - * - * Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * - * \par - * <table> - * <tr> - * <th>Compatibility setting</th> - * <th>H5Oget_info_by_name</th> - * </tr> - * <tr> - * <td>No compatibility flag \n </td> - * <td>#H5Oget_info_by_name3 for 1.12 and above \n - * #H5Oget_info_by_name1 for 1.8 or 1.10</td> - * </tr> - * <tr> - * <td>Emulate Release 1.12</td> - * <td>#H5Oget_info_by_name3</td> - * </tr> - * <tr> - * <td>Emulate Release 1.10 or 1.8 interface</td> - * <td>#H5Oget_info_by_name1</td> - * </tr> - * </table> - * - * \version 1.12.0 The macro #H5Oget_info_by_name and function - * #H5Oget_info_by_name3 were added and - * #H5Oget_info_by_name1 was deprecated. - * \version 1.10.5 The macro #H5Oget_info_by_name was removed. The functions - * #H5Oget_info_by_name and #H5Oget_info_by_name1 are - * identical in this release. This change was added to restore - * the broken API compatibility introduced in HDF5-1.10.3. - * \version 1.10.3 The function #H5Oget_info_by_name was renamed - * to #H5Oget_info_by_name1. The macro #H5Oget_info_by_name - * and the function #H5Oget_info_by_name2 were introduced - * in this release. - * \version 1.8.8 Fortran 2003 subroutine and \c h5o_info_t derived - * type introduced in this release.</td> - * - * \since 1.8.0 - * - */ diff --git a/doxygen/dox/H5Ovisit.dox b/doxygen/dox/H5Ovisit.dox deleted file mode 100644 index 1e2a3ea..0000000 --- a/doxygen/dox/H5Ovisit.dox +++ /dev/null @@ -1,55 +0,0 @@ -/** - * \ingroup H5O - * \def H5Ovisit - * - * #H5Ovisit is a macro that is mapped to one of the following: - * \li #H5Ovisit3 - * \li #H5Ovisit1 - * - * \details Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * API Compatibility Macros in HDF5; we urge you to read that - * document closely. - * - * In HDF5 versions 1.12 and after, #H5Ovisit is mapped to - * #H5Ovisit3. In version 1.10, #H5Ovisit is identical - * to #H5Ovisit1. - * - * Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * - * \par - * <table> - * <tr> - * <th>Compatibility settings</th> - * <th>H5Ovisit</th> - * </tr> - * <tr> - * <td>No compatibility flag \n </td> - * <td>#H5Ovisit3 in 1.12 or after \n - * #H5Ovisit1 for 1.8 and 1.10</td> - * </tr> - * <tr> - * <td>Emulate Release 1.12</td> - * <td>#H5Ovisit3</td> - * </tr> - * <tr> - * <td>Emulate Release 1.10 or 1.8 interface</td> - * <td>#H5Ovisit1</td> - * </tr> - * </table> - * - * \version 1.12.0 The macro #H5Ovisit and function #H5Ovisit3 were added, - * and #H5Ovisit1 was deprecated. - * \version 1.10.5 The macro #H5Ovisit was removed. The functions - * #H5Ovisit and #H5Ovisit1 are identical in this release. - * This change was added to restore the broken API compatibility - * introduced in HDF5-1.10.3. - * \version 1.10.3 The function #H5Ovisit was renamed to #H5Ovisit1. - * The macro #H5Ovisit and the function #H5Ovisit2 were - * introduced in this release. - * \version 1.8.8 Fortran subroutine and data structure added. - * - * \since 1.8.0 - * - */ diff --git a/doxygen/dox/H5Ovisit_by_name.dox b/doxygen/dox/H5Ovisit_by_name.dox deleted file mode 100644 index 2ba4846..0000000 --- a/doxygen/dox/H5Ovisit_by_name.dox +++ /dev/null @@ -1,54 +0,0 @@ -/** - * \ingroup H5O - * \def H5Ovisit_by_name - * - * #H5Ovisit_by_name is a macro that is mapped to one of the following: - * \li #H5Ovisit_by_name3 - * \li #H5Ovisit_by_name1 - * - * \details Such macros are provided to facilitate application - * compatibility. Their use and mappings are fully described in - * API Compatibility Macros in HDF5; we urge you to read that - * document closely. - * - * In HDF5 versions 1.12 and after, #H5Ovisit_by_name is mapped to - * #H5Ovisit_by_name3. In version 1.10, #H5Ovisit_by_name - * is identical to #H5Ovisit_by_name1. - * - * Specific compile-time compatibility flags and the resulting - * mappings are as follows: - * - * \par - * <table> - * <tr> - * <th>Compatibility settings</th> - * <th>H5Ovisit_by_name</th> - * </tr> - * <tr> - * <td>No compatibility flag \n </td> - * <td>#H5Ovisit_by_name3 for 1.12 and above \n - * #H5Ovisit_by_name1 for 1.10 or 1.8</td> - * </tr> - * <tr> - * <td>Emulate Release 1.12 interface</td> - * <td>#H5Ovisit_by_name3</td> - * </tr> - * <tr> - * <td>Emulate Release 1.10 or 1.8 interface</td> - * <td>#H5Ovisit_by_name1</td> - * </tr> - * </table> - * - * \version 1.12.0 The macro #H5Ovisit_by_name and function #H5Ovisit_by_name3 were added. - * \version 1.10.5 The macro #H5Ovisit_by_name was removed. The functions - * #H5Ovisit_by_name and #H5Ovisit_by_name1 are identical - * in this release. This change was added to restore the - * broken API compatibility introduced in HDF5-1.10.3. - * \version 1.10.3 The function #H5Ovisit_by_name was renamed to #H5Ovisit_by_name1. - * The macro #H5Ovisit_by_name and the function #H5Ovisit_by_name2 - * were introduced in this release. - * \version 1.8.8 Fortran subroutine introduced in this release. - * - * \since 1.8.0 - * - */ diff --git a/doxygen/dox/H5Sencode.dox b/doxygen/dox/H5Sencode.dox deleted file mode 100644 index fe0995c..0000000 --- a/doxygen/dox/H5Sencode.dox +++ /dev/null @@ -1,5 +0,0 @@ -/** - * \ingroup H5S - * \def H5Sencode() - * H5Sencode() is a macro that is mapped to either H5Sencode1() or H5Sencode2(). -*/ diff --git a/doxygen/dox/MetadataCachingInHDF5.dox b/doxygen/dox/MetadataCachingInHDF5.dox index 9ba0fab..b84ddea 100644 --- a/doxygen/dox/MetadataCachingInHDF5.dox +++ b/doxygen/dox/MetadataCachingInHDF5.dox @@ -668,7 +668,7 @@ reduction. With the hit rate threshold cache size decrement algorithm, the remaining fields in the section are ignored. -\subsubsection acsr Ageout Cache Size Reduction +\subsubsection dacsr Ageout Cache Size Reduction If \ref H5AC_cache_config_t.decr_mode "decr_mode" is #H5C_decr__age_out the cache size is decreased by the ageout algorithm, and the remaining fields of the @@ -692,7 +692,7 @@ The \ref H5AC_cache_config_t.decrement "decrement" and \ref H5AC_cache_config_t.upper_hr_threshold "upper_hr_threshold" fields are ignored in this case. -\subsubsection awhrtcsr Ageout With Hit Rate Threshold Cache Size Reduction +\subsubsection dawhrtcsr Ageout With Hit Rate Threshold Cache Size Reduction If \ref H5AC_cache_config_t.decr_mode "decr_mode" is #H5C_decr__age_out_with_threshold, the cache size is decreased by the ageout diff --git a/doxygen/dox/RFC.dox b/doxygen/dox/RFC.dox new file mode 100644 index 0000000..c16dcea --- /dev/null +++ b/doxygen/dox/RFC.dox @@ -0,0 +1,91 @@ +/** \page RFC RFCs + +<table> +<tr><th>RFC ID</th><th>Title</th><th>Comments</th></tr> +<tr> <td>2021-05-28</td> <td>\ref_rfc20210528</td> <td></td></tr> +<tr> <td>2019-09-23</td> <td>\ref_rfc20190923</td> <td></td></tr> +<tr> <td>2019-04-10</td> <td>\ref_rfc20190410</td> <td></td> </tr> +<tr> <td>2018-12-31</td> <td>\ref_rfc20181231</td> <td></td> </tr> +<tr> <td>2018-12-20</td> <td>\ref_rfc20181220</td> <td></td> </tr> +<tr> <td>2018-06-20</td> <td>\ref_rfc20180620</td> <td></td> </tr> +<tr> <td>2018-06-10</td> <td>\ref_rfc20180610</td> <td></td> </tr> +<tr> <td>2018-03-21</td> <td>\ref_rfc20180321</td> <td></td> </tr> +<tr> <td>2018-01-25</td> <td>\ref_rfc20180125</td> <td></td> </tr> +<tr> <td>2017-07-07</td> <td>\ref_rfc20170707</td> <td></td> </tr> +<tr> <td>2016-01-05</td> <td>\ref_rfc20160105</td> <td></td> </tr> +<tr> <td>2015-09-15</td> <td>\ref_rfc20150915</td> <td></td> </tr> +<tr> <td>2015-07-09</td> <td>\ref_rfc20150709</td> <td></td> </tr> +<tr> <td>2015-06-15</td> <td>\ref_rfc20150615</td> <td></td> </tr> +<tr> <td>2015-04-29</td> <td>\ref_rfc20150429</td> <td></td> </tr> +<tr> <td>2015-04-24</td> <td>\ref_rfc20150424</td> <td></td> </tr> +<tr> <td>2015-04-23</td> <td>\ref_rfc20150423</td> <td></td> </tr> +<tr> <td>2015-03-01</td> <td>\ref_rfc20150301</td> <td></td> </tr> +<tr> <td>2015-02-12</td> <td>\ref_rfc20150212</td> <td></td> </tr> +<tr> <td>2015-02-05</td> <td>\ref_rfc20150205</td> <td></td> </tr> +<tr> <td>2015-02-02</td> <td>\ref_rfc20150202</td> <td></td> </tr> +<tr> <td>2014-12-10</td> <td>\ref_rfc20141210</td> <td></td> </tr> +<tr> <td>2014-12-01</td> <td>\ref_rfc20141201</td> <td></td> </tr> +<tr> <td>2014-09-16</td> <td>\ref_rfc20140916</td> <td></td> </tr> +<tr> <td>2014-08-27</td> <td>\ref_rfc20140827</td> <td></td> </tr> +<tr> <td>2014-07-29</td> <td>\ref_rfc20140729</td> <td></td> </tr> +<tr> <td>2014-07-22</td> <td>\ref_rfc20140722</td> <td></td> </tr> +<tr> <td>2014-07-17</td> <td>\ref_rfc20140717</td> <td></td> </tr> +<tr> <td>2014-07-07</td> <td>\ref_rfc20140707</td> <td></td> </tr> +<tr> <td>2014-05-24</td> <td>\ref_rfc20140524</td> <td></td> </tr> +<tr> <td>2014-03-18</td> <td>\ref_rfc20140318</td> <td></td> </tr> +<tr> <td>2014-03-13</td> <td>\ref_rfc20140313</td> <td></td> </tr> +<tr> <td>2014-02-24</td> <td>\ref_rfc20140224</td> <td></td> </tr> +<tr> <td>2013-12-11</td> <td>\ref_rfc20131211</td> <td></td> </tr> +<tr> <td>2013-09-30</td> <td>\ref_rfc20130930</td> <td></td> </tr> +<tr> <td>2013-09-19</td> <td>\ref_rfc20130919</td> <td></td> </tr> +<tr> <td>2013-06-30</td> <td>\ref_rfc20130630</td> <td></td> </tr> +<tr> <td>2013-03-16</td> <td>\ref_rfc20130316</td> <td></td> </tr> +<tr> <td>2012-11-14</td> <td>\ref_rfc20121114</td> <td></td> </tr> +<tr> <td>2012-10-24</td> <td>\ref_rfc20121024</td> <td></td> </tr> +<tr> <td>2012-08-28</td> <td>\ref_rfc20120828</td> <td></td> </tr> +<tr> <td>2012-05-23</td> <td>\ref_rfc20120523</td> <td></td> </tr> +<tr> <td>2012-05-01</td> <td>\ref_rfc20120501</td> <td></td> </tr> +<tr> <td>2012-03-05</td> <td>\ref_rfc20120305</td> <td></td> </tr> +<tr> <td>2012-02-20</td> <td>\ref_rfc20120220</td> <td></td> </tr> +<tr> <td>2012-01-20</td> <td>\ref_rfc20120120</td> <td></td> </tr> +<tr> <td>2012-01-04</td> <td>\ref_rfc20120104</td> <td></td> </tr> +<tr> <td>2011-11-19</td> <td>\ref_rfc20111119</td> <td></td> </tr> +<tr> <td>2011-08-25</td> <td>\ref_rfc20110825</td> <td></td> </tr> +<tr> <td>2011-08-11</td> <td>\ref_rfc20110811</td> <td></td> </tr> +<tr> <td>2011-07-26</td> <td>\ref_rfc20110726</td> <td></td> </tr> +<tr> <td>2011-06-14</td> <td>\ref_rfc20110614</td> <td></td> </tr> +<tr> <td>2011-03-29</td> <td>\ref_rfc20110329</td> <td></td> </tr> +<tr> <td>2011-01-18</td> <td>\ref_rfc20110118</td> <td></td> </tr> +<tr> <td>2010-11-22</td> <td>\ref_rfc20101122</td> <td></td> </tr> +<tr> <td>2010-11-04</td> <td>\ref_rfc20101104</td> <td></td> </tr> +<tr> <td>2010-10-18</td> <td>\ref_rfc20101018</td> <td></td> </tr> +<tr> <td>2010-09-02</td> <td>\ref_rfc20100902</td> <td></td> </tr> +<tr> <td>2010-07-27</td> <td>\ref_rfc20100727</td> <td></td> </tr> +<tr> <td>2010-07-26</td> <td>\ref_rfc20100726</td> <td></td> </tr> +<tr> <td>2010-05-11</td> <td>\ref_rfc20100511</td> <td></td> </tr> +<tr> <td>2010-04-22</td> <td>\ref_rfc20100422</td> <td></td> </tr> +<tr> <td>2010-03-12</td> <td>\ref_rfc20100312</td> <td></td> </tr> +<tr> <td>2009-12-18</td> <td>\ref_rfc20091218</td> <td></td> </tr> +<tr> <td>2009-09-07</td> <td>\ref_rfc20090907</td> <td></td> </tr> +<tr> <td>2009-06-12</td> <td>\ref_rfc20090612</td> <td></td> </tr> +<tr> <td>2008-12-18</td> <td>\ref_rfc20081218</td> <td></td> </tr> +<tr> <td>2008-09-15</td> <td>\ref_rfc20080915</td> <td></td> </tr> +<tr> <td>2008-09-04</td> <td>\ref_rfc20080904</td> <td></td> </tr> +<tr> <td>2008-03-01</td> <td>\ref_rfc20080301</td> <td></td> </tr> +<tr> <td>2008-02-09</td> <td>\ref_rfc20080209</td> <td></td> </tr> +<tr> <td>2008-02-06</td> <td>\ref_rfc20080206</td> <td></td> </tr> +<tr> <td>2007-11-11</td> <td>\ref_rfc20071111</td> <td></td> </tr> +<tr> <td>2007-10-18</td> <td>\ref_rfc20071018</td> <td></td> </tr> +<tr> <td>2007-08-01</td> <td>\ref_rfc20070801</td> <td></td> </tr> +<tr> <td>2007-04-13</td> <td>\ref_rfc20070413</td> <td></td> </tr> +<tr> <td>2007-01-15</td> <td>\ref_rfc20070115</td> <td></td> </tr> +<tr> <td>2006-06-23</td> <td>\ref_rfc20060623</td> <td></td> </tr> +<tr> <td>2006-06-04</td> <td>\ref_rfc20060604</td> <td></td> </tr> +<tr> <td>2006-05-05</td> <td>\ref_rfc20060505</td> <td></td> </tr> +<tr> <td>2006-04-10</td> <td>\ref_rfc20060410</td> <td></td> </tr> +<tr> <td>2006-03-17</td> <td>\ref_rfc20060317</td> <td></td> </tr> +<tr> <td>2006-01-24</td> <td>\ref_rfc20060124</td> <td></td> </tr> +<tr> <td>2004-08-11</td> <td>\ref_rfc20040811</td> <td></td> </tr> +</table> + +*/
\ No newline at end of file diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox index 596a224..cc0f99b 100644 --- a/doxygen/dox/ReferenceManual.dox +++ b/doxygen/dox/ReferenceManual.dox @@ -3,41 +3,87 @@ The functions provided by the HDF5 C-API are grouped into the following \Emph{modules}: -\li \ref H5A "Attributes" — Management of HDF5 attributes (\ref H5A) -\li \ref H5D "Datasets" — Management of HDF5 datasets (\ref H5D) -\li \ref H5S "Dataspaces" — Management of HDF5 dataspaces which describe the shape of datasets and attributes (\ref H5S) -\li \ref H5T "Datatypes" — Management of datatypes which describe elements of datasets and attributes (\ref H5T) -\li \ref H5E "Error Handling" — Functions for handling HDF5 errors (\ref H5E) -\li \ref H5ES "Event Sets" — Functions for handling HDF5 event sets (\ref H5ES) -\li \ref H5F "Files" — Management of HDF5 files (\ref H5F) -\li \ref H5Z "Filters" — Configuration of filters that process data during I/O operation (\ref H5Z) -\li \ref H5G "Groups" — Management of groups in HDF5 files (\ref H5G) -\li \ref H5I "Identifiers" — Management of object identifiers and object names (\ref H5I) -\li \ref H5 "Library" — General purpose library functions (\ref H5) -\li \ref H5L "Links" — Management of links in HDF5 groups (\ref H5L) -\li \ref H5M "Maps" — Management of HDF5 maps (\ref H5M) -\li \ref H5O "Objects" — Management of objects in HDF5 files (\ref H5O) -\li \ref H5PL "Plugins" — Programmatic control over dynamically loaded plugins (\ref H5PL) -\li \ref H5P "Property Lists" — Management of property lists to control HDF5 library behavior (\ref H5P) -\li \ref H5R "References" — Management of references to specific objects and data regions in an HDF5 file (\ref H5R) -\li \ref H5VL "Virtual Object Layer" — Management of the Virtual Object Layer (\ref H5VL) - -\par Asynchronous Functions - A subset of functions has \ref ASYNC "asynchronous variants". - -\par API Versioning - See \ref api-compat-macros - -\par Deprecated Functions and Types - A list of deprecated functions and types can be found - <a href="./deprecated.html">here</a>. - -\par Etiquette - Here are a few simple rules to follow: - \li \Bold{Handle discipline:} If you acquire a handle (by creation or copy), \Emph{you own it!} (..., i.e., you have to close it.) - \li \Bold{Dynamic memory allocation:} ... - \li \Bold{Use of locations:} Identifier + name combo +<table> +<tr><th>Modules</th></tr> +<tr valign="top"> +<td> + +<table> +<tr><td style="border: none;"> +\li \ref H5A "Attributes (H5A)" +\li \ref H5D "Datasets (H5D)" +\li \ref H5S "Dataspaces (H5S)" +\li \ref H5T "Datatypes (H5T)" +\li \ref H5E "Error Handling (H5E)" +\li \ref H5ES "Event Sets (H5ES)" +\li \ref H5F "Files (H5F)" +\li \ref H5Z "Filters (H5Z)" +\li \ref H5G "Groups (H5G)" +</td><td style="border: none;"> +\li \ref H5I "Identifiers (H5I)" +\li \ref H5 "Library General (H5)" +\li \ref H5L "Links (H5L)" +\li \ref H5M "Maps (H5M)" +\li \ref H5O "Objects (H5O)" +\li \ref H5P "Property Lists (H5P)" +\li \ref H5PL "Dynamically-loaded Plugins (H5PL)" +\li \ref H5R "References (H5R)" +\li \ref H5VL "Virtual Object Layer (H5VL)" +</td><td style="border: none;vertical-align: top;"> +\li Functions with \ref ASYNC "asynchronous variants" +\li \ref api-compat-macros +\li <a href="./deprecated.html">Deprecated functions</a> +\li High-level Extensions + <ul> + <li><a href="https://portal.hdfgroup.org/display/HDF5/Lite">\Bold{HDF5 Lite} (H5LT)</a></li> + <li><a href="https://portal.hdfgroup.org/display/HDF5/Images">\Bold{HDF5 Image} (H5IM)</a></li> + <li><a href="https://portal.hdfgroup.org/display/HDF5/Tables">\Bold{HDF5 Table} (H5TB)</a></li> + <li><a href="https://portal.hdfgroup.org/display/HDF5/Packet+Tables">\Bold{HDF5 Packet Table} (H5TB)</a></li> + <li><a href="https://portal.hdfgroup.org/display/HDF5/Dimension+Scales">\Bold{HDF5 Dimension Scale} (H5DS)</a></li> + </ul> +</td></tr> +<tr><td colspan="3" style="border: none;"> +\ref H5 \ref H5A \ref H5D \ref H5E \ref H5ES \ref H5F \ref H5G \ref H5I \ref H5L +\ref H5M \ref H5O \ref H5P \ref H5PL \ref H5R \ref H5S \ref H5T \ref H5VL \ref H5Z +</td></tr> +</table> + +</td></tr> +<tr><th>Mind the gap</th></tr> +<tr><td> +Follow these simple rules and stay out of trouble: + +\li \Bold{Handle discipline:} The HDF5 C-API is rife with handles or + identifiers, which you typically obtain by creating new HDF5 items, copying + items, or retrieving facets of items. \Emph{You acquire a handle, you own it!} + (Colin Powell) In other words, you are responsible for releasing the underlying + resources via the matching \Code{H5*close()} call, or deal with the consequences + of resource leakage. +\li \Bold{Closed means closed:} Do not pass identifiers that were previously + \Code{H5*close()}-d to other API functions! It will generate an error. +\li \Bold{Dynamic memory allocation:} The API contains a few functions in which the + HDF5 library dynamically allocates memory on the caller's behalf. The caller owns + this memory and eventually must free it by calling H5free_memory(). (\Bold{Not} + the `free` function \Emph{du jour}!) +\li \Bold{Be careful with that saw:} Do not modify the underlying collection when an + iteration is in progress! +\li \Bold{Use of locations:} Certain API functions, typically called \Code{H5***_by_name} + use a combination of identifiers and path names to refer to HDF5 objects. + If the identifier fully specifies the object in question, pass \Code{'.'} (a dot) + for the name! + +Break a leg! +</td> +</tr> +</table> \cpp_c_api_note +\par Don't like what you see? - You can help to improve this Reference Manual + Complete the survey linked near the top of this page!\n + We treat documentation like code: Fork the + <a href="https://github.com/HDFGroup/hdf5">HDF5 repo</a>, make changes, and create a + <a href="https://github.com/HDFGroup/hdf5/pulls">pull request</a> !\n + See the \ref RMT for general guidance. + */
\ No newline at end of file diff --git a/doxygen/dox/cookbook/Accessibility.c b/doxygen/dox/cookbook/Accessibility.c new file mode 100644 index 0000000..f4cc905 --- /dev/null +++ b/doxygen/dox/cookbook/Accessibility.c @@ -0,0 +1,48 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [set_libver_bounds] --> + { + __label__ fail_fapl, fail_file; + hid_t fapl, file, aspace, attr; + + if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fapl; + } +#if H5_VERSION_GE(1, 10, 0) + if (H5Pset_libver_bounds(fapl, H5F_LIBVER_V18, H5F_LIBVER_V18) < 0) { +#elif H5_VERSION_GE(1, 8, 0) + if (H5Pset_libver_bounds(fapl, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) < 0) { +#else +#error Only HDF5 1.8.x and later supported. +#endif + ret_val = EXIT_FAILURE; + goto fail_file; + } + if ((file = H5Fcreate("set_libver_bounds.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + H5Fclose(file); +fail_file: + H5Pclose(fapl); +fail_fapl:; + } + //! <!-- [set_libver_bounds] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/dox/cookbook/Accessibility.dox b/doxygen/dox/cookbook/Accessibility.dox new file mode 100644 index 0000000..f100283 --- /dev/null +++ b/doxygen/dox/cookbook/Accessibility.dox @@ -0,0 +1,39 @@ +/** \page Accessibility + +\section Accessibility + +\subsection CB_MaintainCompat Maintaining Compatibility with other HDF5 Library Versions + +\par Problem +You want to ensure that the HDF5 files you produce or modify are accessible by all +releavnt tools and applications + +\par Solution +For HDF5 items (objects, attributes, etc.) that you would like to +create in new or existing HDF5 files, ascertain the supported range of HDF5 +library versions as lower and upper bounds. When creating new or opening +existing HDF5 files, use a file access property list and configure the supported +range via the H5Pset_libver_bounds() function.\n +In the example below, we restrict HDF5 item creation to the HDF5 1.8.x family of +library versions. +\snippet{lineno} Accessibility.c set_libver_bounds + +\par Discussion +See RFC \ref_rfc20160105 for a detailed and comprehensive account of HDF5 +versioning (library, file format spec., etc.) and the H5Pset_libver_bounds() +function.\n +The default range #H5F_LIBVER_EARLIEST (low) - #H5F_LIBVER_LATEST (high) offers the +widest compatibility range, but may not be suitable for certain (feature-)use +cases.\n +The HDF5 library comes with a \Emph{forward-} and \Emph{backward-compatibility} +guarantee: This means that the latest version of the library can always read +HDF5 files created by a version realesed earlier (backward compatibility). +It also means that a given release of the library can read the contents of +HDF5 files created with later versions of the library as long as the files +do not contain features introduced in later versions (forward compatibility). + +\par See Also +See the recipe \ref CB_LargeAttributes for an example where we use HDF5 +compatibility settings to enable the creation of large HDF5 attributes. + +*/
\ No newline at end of file diff --git a/doxygen/dox/cookbook/Attributes.c b/doxygen/dox/cookbook/Attributes.c new file mode 100644 index 0000000..f4e894f --- /dev/null +++ b/doxygen/dox/cookbook/Attributes.c @@ -0,0 +1,61 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [large_attribute] --> + { + __label__ fail_attr, fail_aspace, fail_fapl, fail_file; + hid_t fapl, file, aspace, attr; + + if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fapl; + } +#if H5_VERSION_GE(1, 10, 0) + if (H5Pset_libver_bounds(fapl, H5F_LIBVER_V18, H5F_LIBVER_LATEST) < 0) { +#elif H5_VERSION_GE(1, 8, 0) + if (H5Pset_libver_bounds(fapl, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) < 0) { +#else +#error Only HDF5 1.8.x and later supported. +#endif + ret_val = EXIT_FAILURE; + goto fail_file; + } + if ((file = H5Fcreate("large_attribute.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + if ((aspace = H5Screate_simple(1, (hsize_t[]){1024 * 1024}, NULL)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_aspace; + } + if ((attr = H5Acreate(file, "4MiB", H5T_IEEE_F32LE, aspace, H5P_DEFAULT, H5P_DEFAULT)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_attr; + } + + H5Aclose(attr); +fail_attr: + H5Sclose(aspace); +fail_aspace: + H5Fclose(file); +fail_file: + H5Pclose(fapl); +fail_fapl:; + } + //! <!-- [large_attribute] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/dox/cookbook/Attributes.dox b/doxygen/dox/cookbook/Attributes.dox new file mode 100644 index 0000000..68fd159 --- /dev/null +++ b/doxygen/dox/cookbook/Attributes.dox @@ -0,0 +1,38 @@ +/** \page Attributes + +\section Attributes + +\subsection CB_LargeAttributes Creating "Large" HDF5 Attributes + +\par Problem +You would like to use HDF5 attributes the size of whose values +exceeds a few dozen kilobytes + +\par Solution +A file format change in the HDF5 1.8.x family of library releases made it +possible to have attributes larger than about 64 KiB. Ensure that the lower +library version bound for new HDF5 item creation is at least 1.8.x, and create +larger attributes as usual.\n +In the example below, we create an attribute whose value occupies 4 MiB. + +\note This feature is only supported in HDF5 1.8.x+ + +\snippet{lineno} Attributes.c large_attribute + +\par Discussion +Large attributes are supported only in HDF5 versions 1.8.x and higher. +This has implications for the accessibility of your HDF5 files and +is your call.\n +Since there are no size limitations for large attributes, it might +seem tempting to mistake them for dataset stand-ins. This is not the +case, for at least two reasons: +1. Attributes decorate HDF5 objects, have their own local namespace, + and can't be link targets. +2. Attribute I/O treats the attribute value as atomic, i.e., there + is no support for partial I/O. A large attribute will always be + read or written in its entirety. + +\par See Also +See \ref CB_MaintainCompat for HDF5 compatibility implications. + + */
\ No newline at end of file diff --git a/doxygen/dox/cookbook/Files.c b/doxygen/dox/cookbook/Files.c new file mode 100644 index 0000000..b824933 --- /dev/null +++ b/doxygen/dox/cookbook/Files.c @@ -0,0 +1,87 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [free_space] --> + { + __label__ fail_fcpl, fail_fapl, fail_file; + hid_t fcpl, fapl, file; + + if ((fcpl = H5Pcreate(H5P_FILE_CREATE)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fcpl; + } +#if H5_VERSION_GE(1, 10, 1) + if (H5Pset_file_space_strategy(fcpl, H5F_FSPACE_STRATEGY_FSM_AGGR, 1, 4096) < 0) { +#else +#error HDF5 1.10.1+ required +#endif + ret_val = EXIT_FAILURE; + goto fail_fapl; + } + + if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fapl; + } +#if H5_VERSION_GE(1, 10, 1) + if (H5Pset_libver_bounds(fapl, H5F_LIBVER_V110, H5F_LIBVER_LATEST) < 0) { +#else +#error HDF5 1.10.x+ required +#endif + ret_val = EXIT_FAILURE; + goto fail_file; + } + + if ((file = H5Fcreate("free_space.h5", H5F_ACC_TRUNC, fcpl, fapl)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + H5Fclose(file); + +fail_file: + H5Pclose(fapl); +fail_fapl: + H5Pclose(fcpl); +fail_fcpl:; + } + //! <!-- [free_space] --> + + //! <!-- [user_block] --> + { + __label__ fail_fcpl, fail_file; + hid_t fcpl, file; + + if ((fcpl = H5Pcreate(H5P_FILE_CREATE)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_fcpl; + } + if (H5Pset_userblock(fcpl, 8192 * 1024) < 0) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + if ((file = H5Fcreate("userblock.h5", H5F_ACC_TRUNC, fcpl, H5P_DEFAULT)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + H5Fclose(file); + +fail_file: + H5Pclose(fcpl); +fail_fcpl:; + } + //! <!-- [user_block] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/dox/cookbook/Files.dox b/doxygen/dox/cookbook/Files.dox new file mode 100644 index 0000000..169d638 --- /dev/null +++ b/doxygen/dox/cookbook/Files.dox @@ -0,0 +1,71 @@ +/** \page Files + +\section Files + +\subsection CB_FreeSpace Tracking Free Space in HDF5 Files + +\par Problem +You sometimes delete objects in HDF5 files and don't have new content to use the +free space, but would like to reuse it in the future. + +\par Solution +At file creation time, set the file space management strategy and persistence of +free space tracking information via H5Pset_file_space_strategy(). + +\note This feature is only supported in HDF5 1.10.1+. + +\snippet{lineno} Files.c free_space + +\par Discussion +Free space tracking is supported only in HDF5 versions 1.10.x and higher. +This has implications for the accessibility of your HDF5 files and +should be considered carefully. If compatibility with previous versions of +HDF5 must be maintained, space reclamation via \Code{h5repack} might be an option.\n +The file space strategy #H5F_FSPACE_STRATEGY_FSM_AGGR is not the only option +that supports free-space tracking. #H5F_FSPACE_STRATEGY_PAGE is another option, +which adds paged allocation and is used most effectively with page buffering.\n +For an in-depth account of HDF5 file space management, paged-allocation, and +page buffering, see the following documents: +\li \ref_rfc20121024 +\li \ref_rfc20120523 +\li \ref_rfc20150709 + +\par See Also +See \ref CB_MaintainCompat for HDF5 compatibility implications. + + +\subsection CB_RemoveUnusedSpace Removing Unused Space from HDF5 Files + +\par Problem +Based on estimates or \Code{h5stat} output you know that a large portion +of an HDF5 file consists of free or unaccounted space, and you would like +to remove it. + + +\subsection CB_UserBlock Creating an HDF5 File User Block + +\par Problem +You would like to include certain ancillary, non-HDF5 content in an +HDF5 file such that it can be accessed without the HDF5 library. + +\par Solution +Use a file creation property list in which the user block size is set via +H5Pset_userblock(). In the example below, we create an 8 MiB user block. +\snippet{lineno} Files.c user_block + +\par Discussion +The user block begins at offset 0 and must be at least 512 bytes and a power +of 2. The HDF5 library ignores any content between the beginning of the +file and the end of the user block.\n +You can add or strip a user block to/from an existing HDF5 file with the +\Code{h5jam}/\Code{h5unjam} tool, respectively. +\warning +If you try to embed content into the user block for use by other applications, +pay close attention to how they handle space beyond the last used byte in the +user block or the user block in general. In the worst case, applications might +try to truncate the rest of the file and destroy the HDF5 portion of the file. + +\par See Also +References to related recipes + + */
\ No newline at end of file diff --git a/doxygen/dox/cookbook/Performance.dox b/doxygen/dox/cookbook/Performance.dox new file mode 100644 index 0000000..7ac3a18 --- /dev/null +++ b/doxygen/dox/cookbook/Performance.dox @@ -0,0 +1,21 @@ +/** \page Performance + +\section Performance + +\subsection CB_MDCPerf Assessing HDF5 Metadata Cache Performance + +\par Problem +You are trying to diagnose and improve the I/O performance of an application +and would like to understand if a simple metadata cache adjustment might +yield substantial performance gains + +\par Solution +The to-the-point solution, i.e., the solution w/o any background or explanation + +\par Discussion +A discussion of the fine points and variants of the solution + +\par See Also +References to related recipes + + */
\ No newline at end of file diff --git a/doxygen/dox/maybe_metadata_reads.dox b/doxygen/dox/maybe_metadata_reads.dox index 25c905f..1bb53e0 100644 --- a/doxygen/dox/maybe_metadata_reads.dox +++ b/doxygen/dox/maybe_metadata_reads.dox @@ -13,62 +13,30 @@ * The following is a list of those functions in the HDF5 library. This list is * integral to the discussion in the H5Pset_all_coll_metadata_ops() entry: * - * <pre> - * - * H5Awrite() - * H5Aread() - * H5Arename() - * H5Aiterate2() - * H5Adelete() - * H5Aexists() - * - * H5Dget_space_status() - * H5Dget_storage_size() - * H5Dset_extent() - * H5Ddebug() - * H5Dclose() - * H5Dget_create_plist() - * H5Dget_space() (when dataset is a virtual dataset) - * - * H5Gget_create_plist() - * H5Gget_info() - * H5Gclose() - * - * H5Literate() - * H5Lvisit() - * - * H5Rcreate() - * H5Rdereference2() (when reference is an object reference) - * H5Rget_region() - * H5Rget_obj_type2() - * H5Rget_name() - * - * H5Ocopy() - * H5Oopen_by_addr() - * H5Oincr_refcount() - * H5Odecr_refcount() - * H5Oget_info() - * H5Oset_comment() - * H5Ovisit() - * - * H5Fis_hdf5() - * H5Fflush() - * H5Fclose() - * H5Fget_file_image() - * H5Freopen() - * H5Fget_freespace() - * H5Fget_info2() - * H5Fget_free_sections() - * H5Fmount() + * H5Awrite(), H5Aread(), H5Arename(), H5Aiterate2(), H5Adelete(), H5Aexists() + * + * H5Dget_space_status(), H5Dget_storage_size(), H5Dset_extent(), H5Ddebug(), + * H5Dclose(), H5Dget_create_plist(), H5Dget_space() (for virtual datasets) + * + * H5Gget_create_plist(), H5Gget_info(), H5Gclose() + * + * H5Literate(), H5Lvisit() + * + * H5Rcreate(), H5Rdereference2() (for object references), + * H5Rget_region(), H5Rget_obj_type2(), H5Rget_name() + * + * H5Ocopy(), H5Oopen_by_addr(), H5Oincr_refcount(), H5Odecr_refcount(), + * H5Oget_info(), H5Oset_comment(), H5Ovisit() + * + * H5Fis_hdf5(), H5Fflush(), H5Fclose(), H5Fget_file_image(), H5Freopen(), + * H5Fget_freespace(), H5Fget_info2(), H5Fget_free_sections(), H5Fmount(), * H5Funmount() * * H5Iget_name() * - * H5Tget_create_plist() - * H5Tclose() + * H5Tget_create_plist(), H5Tclose() * * H5Zunregister() - * </pre> * * In addition, \b most deprecated functions fall into this category. * diff --git a/doxygen/dox/rm-template.dox b/doxygen/dox/rm-template.dox index 64e4770..ebf8aed 100644 --- a/doxygen/dox/rm-template.dox +++ b/doxygen/dox/rm-template.dox @@ -1,72 +1,99 @@ -/**\ingroup H5XYZ - * - * \brief A synopsis of what H5XYZgreat_function does - * - * \param[in] name1 Description of IN parameter \p name1 - * \param[out] name2 Description of OUT parameter \p name2 - * \param[in,out] name3 Description of INOUT parameter \p name3 - * - * \return Returns what you always wanted - * - * \pre Describe preconditions for an entity. Can be repreated. - * - * \invariant Describe invariants for an entity. Can be repeated. - * - * \post Describe postconditions for an entity. Can be repreated. - * - * \deprecated This was my favorite function while it lasted. - * - * \details Describe the normal behavior flow of the function here. Try to be - * helpful! - * - * Make reference to other functions like this: H5Fopen(). - * - * Make reference to formal parameters like this: \p name1 - * - * Make reference to macros like this: #H5P_DEFAULT. - * - * Make reference to enumeration constants like this: #H5F_CLOSE_WEAK. - * - * Include code snippets like this: - * \snippet H5Zpublic.h H5Z_class2_t_snip - * - * Lists are supported: - * - mouse events - * -# mouse move event - * -# mouse click event\n - * More info about the click event. - * -# mouse double click event - * - keyboard events - * 1. key down event - * 2. key up event - * - * The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is - * \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$.\n - * For tables, see - * <a href="https://www.doxygen.nl/manual/tables.html">this example</a>. - * - * This is an example of how to use the H5XYZgreat_function().\n - * The contents of the file hello_hdf5.c will be included. - * \include hello_hdf5.c - * - * \note Dear reader, ... - * - * \attention Colorless green ideas sleep furiously. - * - * \warning Don't do this at home! - * - * \author This function was written by an esteemed author. Repeat this - * command for multiple authors. - * - * \date Record the function's birthdate! - * - * \since 1.MAJOR.MINOR The 'since' command can also be used to record a - * function's introduction (via its initial release - * version). - * - * \version 1.MAJOR.MINOR An important event in the version history of this - * function. There can be multiple such events. - * - * \see H5XYZanother_great_function(), H5XYZnot_so_great_a_function() - * - */ +/** \page RMT Reference Manual (RM) Page Template + +We treat documentation like code and use +<a href="https://www.doxygen.nl/index.html">Doxygen</a> to +<a href="https://github.com/HDFGroup/hdf5/blob/develop/src/H5Fpublic.h">markup +comments in the code</a> or create +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/dox/Overview.dox">stand-alone pages</a>. + +Every RM entry consists of a subset of the elements listed below. Not every RM +entry warrants the full set. More is better, and we can, perhaps, distinguish +minimal, typical, and great RM entries. + +A minimal RM entry must include elements 1-3, 8, 11, and 7 if applicable. + +A \Emph{typical} RM entry is a minimal RM entry that in addition has elements +9, 10, and 12. + +A \Bold{great} RM entry is a typical RM entry plus everything else. + +The current RM is a mixed bag. Take what's there with a pinch of salt and apply +the <a href="https://www.oreilly.com/library/view/97-things-every/9780596809515/ch08.html">Scout Rule</a>! + +\par RM entry elements + +1. Module indication + - Indicate the HDF5 module in which the function will appear. + \verbatim + * \ingroup H5XYZ + \endverbatim +2. Synopsis + - A phrase or sentence that summarizes the function's purpose + \verbatim + * \brief Simplifies your life + \endverbatim +3. Prototype (parameters and return value) + - A description of the function parameters and return value + \verbatim + * \param[in] name1 Description of IN parameter \p name1 + * \param[out] name2 Description of OUT parameter \p name2 + * \param[in,out] name3 Description of INOUT parameter \p name3 + * \return Returns what you always wanted + \endverbatim + - Clearly indicate the parameter direction as \c in, \c out, or + \Code{in,out} + - Make reference to other parameters using \Code{\\p} +4. Preconditions + - A set of preconditions that must be met. + \verbatim + * \pre The argmument supplied in parameter \p name2 must be even. + \endverbatim +5. Invariants + - A set of invariants. + \verbatim + * \invariant The mouse pointer will always be visible. + \endverbatim +6. Postconditions + - What will be true when the function returns. + \verbatim + * \post On error, the output parameters will be unmodified. + \endverbatim +7. Deprecation note + - If a function was deprecated, list the version in which the function was + deprecated (below), why it was deprecated, and which function(s) succeed it. + \verbatim + * \deprecated Deprecated in favor of another great function. + \endverbatim +8. Details + - A detailed description of the function's behavior + \verbatim + * \details This is the heart of the matter. Try to be helpful! + \endverbatim +9. Example + - The function in context and action, usually a (Doxygen) snippet. + \verbatim + * \par Example + * \snippet H5F_examples.c minimal + \endverbatim +10. Instruction (attention, note, warning) + - Behaviors, features, side-effects, etc. the user should be aware of + \verbatim + * \note Dear reader, ... + * + * \attention Colorless green ideas sleep furiously. + * + * \warning Don't do this at home! + \endverbatim +11. Since + - The HDF5 library version in which the function was introduced + \verbatim + * \since 1.MAJOR.MINOR + \endverbatim +12. Version + - Use this element to record a deprecation version, a change in parameter + types, changes in behavior, etc. + \verbatim + * \version 1.MAJOR.MINOR Function was deprecated in this release + \endverbatim + +*/
\ No newline at end of file diff --git a/doxygen/examples/H5D_examples.c b/doxygen/examples/H5D_examples.c index aad057d..4e54c1d 100644 --- a/doxygen/examples/H5D_examples.c +++ b/doxygen/examples/H5D_examples.c @@ -5,6 +5,86 @@ #include <stdio.h> #include <stdlib.h> +//! <!-- [H5Dchunk_iter_cb] --> +int +chunk_cb(const hsize_t *offset, uint32_t filter_mask, haddr_t addr, uint32_t nbytes, void *op_data) +{ + // only print the allocated chunk size only + printf("%d\n", nbytes); + return EXIT_SUCCESS; +} +//! <!-- [H5Dchunk_iter_cb] --> + +//! <!-- [H5Ovisit_cb] --> +herr_t +H5Ovisit_cb(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data) +{ + herr_t retval = 0; + char * base_path = (char *)op_data; + + if (info->type == H5O_TYPE_DATASET) // current object is a dataset + { + hid_t dset, dcpl; + if ((dset = H5Dopen(obj, name, H5P_DEFAULT)) == H5I_INVALID_HID) { + retval = -1; + goto func_leave; + } + if ((dcpl = H5Dget_create_plist(dset)) == H5I_INVALID_HID) { + retval = -1; + goto fail_dcpl; + } + if (H5Pget_layout(dcpl) == H5D_CHUNKED) // dataset is chunked + { + __label__ fail_dtype, fail_dspace, fail_shape; + hid_t dspace, dtype; + size_t size, i; + int rank; + hsize_t cdims[H5S_MAX_RANK]; + + // get resources + if ((dtype = H5Dget_type(dset)) < 0) { + retval = -1; + goto fail_dtype; + } + if ((dspace = H5Dget_space(dset)) < 0) { + retval = -1; + goto fail_dspace; + } + // get the shape + if ((size = H5Tget_size(dtype)) == 0 || (rank = H5Sget_simple_extent_ndims(dspace)) < 0 || + H5Pget_chunk(dcpl, H5S_MAX_RANK, cdims) < 0) { + retval = -1; + goto fail_shape; + } + // calculate the nominal chunk size + size = 1; + for (i = 0; i < (size_t)rank; ++i) + size *= cdims[i]; + // print dataset info + printf("%s%s : nominal chunk size %lu [B] \n", base_path, name, size); + // get the allocated chunk sizes + if (H5Dchunk_iter(dset, H5P_DEFAULT, &chunk_cb, NULL) < 0) { + retval = -1; + goto fail_fig; + } + +fail_shape: + H5Sclose(dspace); +fail_dspace: + H5Tclose(dtype); +fail_dtype:; + } + + H5Pclose(dcpl); +fail_dcpl: + H5Dclose(dset); + } + +func_leave: + return retval; +} +//! <!-- [H5Ovisit_cb] --> + int main(void) { @@ -166,7 +246,6 @@ fail_delete: H5Fclose(file); fail_file:; } - //! <!-- [delete] --> return ret_val; diff --git a/doxygen/examples/H5E_examples.c b/doxygen/examples/H5E_examples.c new file mode 100644 index 0000000..deea838 --- /dev/null +++ b/doxygen/examples/H5E_examples.c @@ -0,0 +1,97 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_push, fail_minor, fail_major, fail_class; + hid_t cls, major, minor; + + // register a new error class for this "application" + if ((cls = H5Eregister_class("Custom error class", "H5E_examples", "0.1")) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_class; + } + + // create custom major and minor error codes + if ((major = H5Ecreate_msg(cls, H5E_MAJOR, "Okay, Houston, we've had a problem here")) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_major; + } + if ((minor = H5Ecreate_msg(cls, H5E_MINOR, "Oops!")) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_minor; + } + + // push a custom error message onto the default stack + if (H5Epush2(H5E_DEFAULT, __FILE__, __FUNCTION__, __LINE__, cls, major, minor, "Hello, Error!\n") < + 0) { + ret_val = EXIT_FAILURE; + goto fail_push; + } + + // print the default error stack + if (H5Eprint(H5E_DEFAULT, stderr) < 0) { + ret_val = EXIT_FAILURE; + } + +fail_push: + H5Eclose_msg(minor); +fail_minor: + H5Eclose_msg(major); +fail_major: + H5Eunregister_class(cls); +fail_class:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_count; + + // check the number of error messages on the default stack + // and print what's there + ssize_t count = H5Eget_num(H5E_DEFAULT); + if (count < 0) { + ret_val = EXIT_FAILURE; + goto fail_count; + } + else if (H5Eprint(H5E_DEFAULT, stderr) < 0) { + ret_val = EXIT_FAILURE; + } + +fail_count:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + // pop 10 error messages off the default error stack + // popping off non-existent messages is OK, but might be confusing + if (H5Epop(H5E_DEFAULT, 10) < 0) + ret_val = EXIT_FAILURE; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + // clear the default error stack (for the current thread) + if (H5Eclear2(H5E_DEFAULT) < 0) + ret_val = EXIT_FAILURE; + } + //! <!-- [delete] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/examples/H5F_examples.c b/doxygen/examples/H5F_examples.c index a7ce6fb..4e89fde 100644 --- a/doxygen/examples/H5F_examples.c +++ b/doxygen/examples/H5F_examples.c @@ -10,7 +10,7 @@ main(void) { int ret_val = EXIT_SUCCESS; - //! <!-- [life_cycle] --> + //! <!-- [create] --> { __label__ fail_fapl, fail_fcpl, fail_file; hid_t fcpl, fapl, file; @@ -48,12 +48,13 @@ fail_fapl: H5Pclose(fcpl); fail_fcpl:; } - //! <!-- [life_cycle] --> + //! <!-- [create] --> - //! <!-- [life_cycle_w_open] --> + //! <!-- [read] --> { __label__ fail_fapl, fail_file; - hid_t fapl, file; + hid_t fapl, file; + hsize_t size; if ((fapl = H5Pcreate(H5P_FILE_ACCESS)) == H5I_INVALID_HID) { ret_val = EXIT_FAILURE; @@ -63,7 +64,7 @@ fail_fcpl:; // adjust the file access properties } - unsigned mode = H5F_ACC_RDWR; + unsigned mode = H5F_ACC_RDONLY; char name[] = "f1.h5"; if ((file = H5Fopen(name, mode, fapl)) == H5I_INVALID_HID) { @@ -71,14 +72,41 @@ fail_fcpl:; goto fail_file; } - // do something useful with FILE + if (H5Fget_filesize(file, &size) < 0) { + ret_val = EXIT_FAILURE; + } + + printf("File size: %llu bytes\n", size); H5Fclose(file); fail_file: H5Pclose(fapl); fail_fapl:; } - //! <!-- [life_cycle_w_open] --> + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_file; + hid_t file; + + unsigned mode = H5F_ACC_RDWR; + char name[] = "f1.h5"; + + if ((file = H5Fopen(name, mode, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // create a cycle by hard linking the root group in the root group + if (H5Lcreate_hard(file, ".", file, "loopback", H5P_DEFAULT, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + + H5Fclose(file); +fail_file:; + } + //! <!-- [update] --> //! <!-- [minimal] --> { @@ -183,5 +211,18 @@ fail_fapl:; } //! <!-- [mount] --> + //! <!-- [delete] --> + { +#if H5_VERSION_GE(1, 12, 0) + + // this function is only available in HDF5 1.12.x + if (H5Fdelete("f1.h5", H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + +#endif + } + //! <!-- [delete] --> + return ret_val; } diff --git a/doxygen/examples/H5G_examples.c b/doxygen/examples/H5G_examples.c new file mode 100644 index 0000000..3109efb --- /dev/null +++ b/doxygen/examples/H5G_examples.c @@ -0,0 +1,186 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_group, fail_prop, fail_lcpl, fail_file; + hid_t file, lcpl, group; + char fname[] = "g1.h5"; + char path[] = "/αυτή/είναι/μια/νέα/ομάδα"; + + if ((file = H5Fcreate(fname, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_lcpl; + } + // ensure that intermediate groups are created automatically + if (H5Pset_create_intermediate_group(lcpl, 1) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // use UTF-8 encoding for link names + if (H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // create five groups + if ((group = H5Gcreate(file, path, lcpl, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_group; + } + + H5Gclose(group); +fail_group: +fail_prop: + H5Pclose(lcpl); +fail_lcpl: + H5Fclose(file); +fail_file:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_file; + char fname[] = "g1.h5"; + char path[] = "/αυτή/είναι"; + hid_t file; + H5G_info_t info; + + if ((file = H5Fopen(fname, H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // open one of the intermediate groups + if (H5Gget_info_by_name(file, path, &info, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_info; + } + + printf("Link count: %llu\n", info.nlinks); + switch (info.storage_type) { + case H5G_STORAGE_TYPE_COMPACT: + printf("Compact storage\n"); + break; + case H5G_STORAGE_TYPE_DENSE: + printf("Compact storage\n"); + break; + case H5G_STORAGE_TYPE_SYMBOL_TABLE: + printf("Symbol table\n"); + break; + default: + printf("UFO\n"); + break; + } + +fail_info: + H5Fclose(file); +fail_file:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_group, fail_prop, fail_lcpl, fail_file; + hid_t file, lcpl, group; + char fname[] = "g1.h5"; + char path[] = "/αυτή/είναι/μια/άλλη/νέα/ομάδα"; + + if ((file = H5Fopen(fname, H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_lcpl; + } + // ensure that intermediate groups are created automatically + if (H5Pset_create_intermediate_group(lcpl, 1) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // use UTF-8 encoding for link names + if (H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // create an anonymous group + if ((group = H5Gcreate_anon(file, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_group; + } + // link the new group to existing the group at "/αυτή/είναι/μια" + if (H5Lcreate_hard(group, ".", file, path, lcpl, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + + H5Gclose(group); +fail_group: +fail_prop: + H5Pclose(lcpl); +fail_lcpl: + H5Fclose(file); +fail_file:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_info, fail_object, fail_file; + hid_t file, obj; + char fname[] = "g1.h5"; + char path[] = "/αυτή/είναι/μια/άλλη/νέα/ομάδα"; + char delete_path[] = "/αυτή/είναι/μια"; + H5O_info_t info; + + if ((file = H5Fopen(fname, H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // open a "leaf" group as object + if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_object; + } + // delete the link to an intermediate group on the path to the leaf + if (H5Ldelete(file, delete_path, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + // link deletion will propagate along hard links along all paths + // reachable from the intermediate group and cause reference counts to + // be decremented, freeing the objects if the count reaches 0 + if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) { + ret_val = EXIT_FAILURE; + goto fail_info; + } + + printf("Leaf reference count: %d\n", info.rc); + +fail_info: + H5Oclose(obj); +fail_object: + H5Fclose(file); +fail_file:; + } + //! <!-- [delete] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/examples/H5I_examples.c b/doxygen/examples/H5I_examples.c new file mode 100644 index 0000000..4aa4783 --- /dev/null +++ b/doxygen/examples/H5I_examples.c @@ -0,0 +1,242 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_dcpl; + hid_t dcpl; + + // create an ID of a pre-defined ID type + if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // we can reliably predict the ID type + assert(H5Iget_type(dcpl) == H5I_GENPROP_LST); + printf("%d\n", H5Iget_type(dcpl)); + + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_dcpl; + hid_t dcpl; + + // create an ID of a pre-defined ID type + if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // this better be valid + assert(H5Iis_valid(dcpl) > 0); + + // this ID is NOT associated with any HDF5 file; + // see the error message + assert(H5Iget_file_id(dcpl) == H5I_INVALID_HID); + + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_rc, fail_dcpl; + hid_t dcpl; + int rc; + + // create an ID of a pre-defined ID type + if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // retrieve the IDs reference count + if ((rc = H5Iget_ref(dcpl)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_rc; + } + printf("Reference count: %d\n", rc); + + // bump its reference count (by 1) + if ((rc = H5Iinc_ref(dcpl)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_rc; + } + printf("Reference count: %d\n", rc); + +fail_rc: + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_rc, fail_dcpl; + hid_t dcpl; + int rc; + + // create an ID of a pre-defined ID type + if ((dcpl = H5Pcreate(H5P_DATASET_XFER)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // decrease its reference count (from 1) to 0 + if ((rc = H5Idec_ref(dcpl)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_rc; + } + printf("Reference count: %d\n", rc); + + // at this point, the ID is no longer valid + assert(H5Iis_valid(dcpl) == 0); + + // dropping the ref. count to 0 has the side-effect of closing + // the associated item, and calling H5Pclose would create an error + goto fail_dcpl; + +fail_rc: + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [delete] --> + + //! <!-- [create_ud] --> + herr_t free_func(void *obj) + { + printf("Calling free_func...\n"); + H5free_memory(obj); + return 0; + } + + { + __label__ fail_id, fail_obj, fail_register; + H5I_type_t type; + int * obj; + hid_t obj_id; + + // register a new ID type + if ((type = H5Iregister_type(128, 1024, &free_func)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_register; + } + printf("New identifier type ID: %d\n", type); + + // create a new object + if ((obj = H5allocate_memory(10 * sizeof(int), 0)) == NULL) { + ret_val = EXIT_FAILURE; + goto fail_obj; + } + + // obtain an ID for the new object + if ((obj_id = H5Iregister(type, obj)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_id; + } + printf("New object identifier: %ld\n", obj_id); + +fail_id: + H5Iclear_type(type, 1); +fail_obj: + H5Idestroy_type(type); +fail_register:; + } + //! <!-- [create_ud] --> + + //! <!-- [read_ud] --> + { + __label__ fail_query, fail_register; + H5I_type_t type; + hsize_t count; + + // register a new ID type + if ((type = H5Iregister_type(128, 1024, NULL)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_register; + } + printf("New FOO identifier type ID: %d\n", type); + + // return the number of identifiers of TYPE currently in use + if (H5Inmembers(type, &count) < 0) { + ret_val = EXIT_FAILURE; + goto fail_query; + } + printf("%llu FOO identifiers in use\n", count); + +fail_query: + H5Idestroy_type(type); +fail_register:; + } + //! <!-- [read_ud] --> + + //! <!-- [update_ud] --> + { + __label__ fail_id, fail_register; + H5I_type_t type; + int obj = 42; + hid_t obj_id; + + // register a new ID type + if ((type = H5Iregister_type(128, 1024, NULL)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_register; + } + printf("New identifier type ID: %d\n", type); + + // obtain an ID for the new object + if ((obj_id = H5Iregister(type, &obj)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_id; + } + printf("New object identifier: %ld\n", obj_id); + + // bump the reference count + assert(H5Iinc_ref(obj_id) == 2); + + // force the deletion of all IDs regardless of reference count + H5Iclear_type(type, 1); +fail_id: + H5Idestroy_type(type); +fail_register:; + } + //! <!-- [update_ud] --> + + //! <!-- [delete_ud] --> + { + __label__ fail_register; + H5I_type_t type; + + // register a new ID type + if ((type = H5Iregister_type(128, 1024, NULL)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_register; + } + printf("New identifier type ID: %d\n", type); + + // decrementing the identifier type's ref. count to 0 triggers + // the type to be destroyed + assert(H5Idec_type_ref(type) == 0); + +fail_register:; + } + //! <!-- [delete_ud] --> + + return ret_val; +} diff --git a/doxygen/examples/H5L_examples.c b/doxygen/examples/H5L_examples.c new file mode 100644 index 0000000..63f54fe --- /dev/null +++ b/doxygen/examples/H5L_examples.c @@ -0,0 +1,156 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +//! <!-- [iter_cb] --> +herr_t +iter_cb(hid_t group, const char *name, const H5L_info_t *info, void *op_data) +{ + printf("Link \"%s\" is a", name); + switch (info->type) { + case H5L_TYPE_HARD: + printf(" hard link.\n"); + break; + case H5L_TYPE_SOFT: + printf(" soft link.\n"); + break; + case H5L_TYPE_EXTERNAL: + printf("n external link.\n"); + break; + default: + printf(" UFO link.\n"); + break; + } + + return 0; +} +//! <!-- [iter_cb] --> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_link, fail_prop, fail_lcpl, fail_create; + + hid_t file, lcpl; + + if ((file = H5Fcreate("l1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_create; + } + + // make link creation easier by auto-creating intermediate + // groups and UTF-8 encoding of link names + if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_lcpl; + } + if (H5Pset_create_intermediate_group(lcpl, 1) < 0 || H5Pset_char_encoding(lcpl, H5T_CSET_UTF8) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + + // create a loop by hard linking the root group + if (H5Lcreate_hard(file, ".", file, "√", lcpl, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_link; + } + // create a soft link to nowhere + if (H5Lcreate_soft("e1 62 80 87 04 09 43 ba 02 d3", file, "/path/to/nowhere", lcpl, H5P_DEFAULT) < + 0) { + ret_val = EXIT_FAILURE; + goto fail_link; + } + // create an external link to nowhere in a non-existent file + if (H5Lcreate_external("non-existent-file.h5", "???", file, "external", lcpl, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_link; + } + +fail_link: +fail_prop: + H5Pclose(lcpl); +fail_lcpl: + H5Fclose(file); +fail_create:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_iterate, fail_read; + hid_t file; + hsize_t idx = 0; + + if ((file = H5Fopen("l1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_read; + } + + if (H5Literate(file, H5_INDEX_NAME, H5_ITER_NATIVE, &idx, iter_cb, NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_iterate; + } + +fail_iterate: + H5Fclose(file); +fail_read:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_move, fail_update; + hid_t file; + + if ((file = H5Fopen("l1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_update; + } + + // move the "√" link to the group at "/path/to" + // the cycle remains! + if (H5Lmove(file, "√", file, "path/to/√", H5P_DEFAULT, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_move; + } + +fail_move: + H5Fclose(file); +fail_update:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_delete, fail_file; + hid_t file; + + if ((file = H5Fopen("l1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // delete the "external" link + if (H5Ldelete(file, "external", H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_delete; + } + +fail_delete: + H5Fclose(file); +fail_file:; + } + //! <!-- [delete] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/examples/H5O_examples.c b/doxygen/examples/H5O_examples.c new file mode 100644 index 0000000..296acd1 --- /dev/null +++ b/doxygen/examples/H5O_examples.c @@ -0,0 +1,193 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <stdio.h> +#include <stdlib.h> + +#define H5P_DEFAULTx2 H5P_DEFAULT, H5P_DEFAULT + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_file; + hid_t file, group; + char src_path[] = "/a/few/groups"; + + if ((file = H5Fcreate("o1.h5", H5F_ACC_TRUNC, H5P_DEFAULTx2)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // create a few groups + { + __label__ fail_group, fail_lcpl; + hid_t lcpl; + if ((lcpl = H5Pcreate(H5P_LINK_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_lcpl; + } + if (H5Pset_create_intermediate_group(lcpl, 1) < 0) { + ret_val = EXIT_FAILURE; + goto fail_group; + } + if ((group = H5Gcreate(file, src_path, lcpl, H5P_DEFAULTx2)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_group; + } + + H5Gclose(group); +fail_group: + H5Pclose(lcpl); +fail_lcpl:; + } + + // create a copy + if (H5Ocopy(file, ".", file, "copy of", H5P_DEFAULTx2) < 0) { + ret_val = EXIT_FAILURE; + } + + H5Fclose(file); +fail_file:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_info, fail_file; + hid_t file; + char path[] = "/a/few/groups"; + H5O_info2_t info; + + if ((file = H5Fopen("o1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // retrieve information about the object + if (H5Oget_info_by_name(file, path, &info, H5O_INFO_BASIC | H5O_INFO_NUM_ATTRS, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_info; + } + + // determine the object type + switch (info.type) { + case H5O_TYPE_GROUP: + printf("HDF5 group\n"); + break; + case H5O_TYPE_DATASET: + printf("HDF5 dataset\n"); + break; + case H5O_TYPE_NAMED_DATATYPE: + printf("HDF5 datatype\n"); + break; + default: + printf("UFO?\n"); + break; + } + // print basic information + printf("Reference count: %u\n", info.rc); + printf("Attribute count: %lld\n", info.num_attrs); + +fail_info: + H5Fclose(file); +fail_file:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_obj, fail_incr, fail_file; + hid_t file, obj; + char path[] = "/a/few/groups"; + H5O_info2_t info; + + if ((file = H5Fopen("o1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // open an object by path name + if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_obj; + } + + // bump its reference count (by 1) + if (H5Oincr_refcount(obj) < 0) { + ret_val = EXIT_FAILURE; + goto fail_incr; + } + + // confirm the new reference count + if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) { + ret_val = EXIT_FAILURE; + goto fail_incr; + } + printf("Reference count: %u\n", info.rc); + +fail_incr: + H5Oclose(obj); +fail_obj: + H5Fclose(file); +fail_file:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_obj, fail_delete, fail_file; + hid_t file, obj; + char path[] = "/a/few/groups"; + H5O_info2_t info; + + if ((file = H5Fopen("o1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // open an object by path name + if ((obj = H5Oopen(file, path, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_obj; + } + + // render it inaccessible from the root group by deleting the one and + // only link to it; this drops the reference count by 1 + if (H5Ldelete(file, path, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + goto fail_delete; + } + + // confirm the new reference count + if (H5Oget_info(obj, &info, H5O_INFO_BASIC) < 0) { + ret_val = EXIT_FAILURE; + goto fail_delete; + } + printf("Reference count: %u\n", info.rc); + + // if we close the file at this point, we'd be creating a tombstone, + // an object that cannot be reached and that cannot be reclaimed by the + // freespace manager; decrement the reference count to zero to prevent that + if (H5Idec_ref(obj) < 0) { + ret_val = EXIT_FAILURE; + goto fail_delete; + } + else + // attempting to close the object would be like a double H5Oclose and fail + goto fail_obj; + +fail_delete: + H5Oclose(obj); +fail_obj: + H5Fclose(file); +fail_file:; + } + //! <!-- [delete] --> + + return ret_val; +} diff --git a/doxygen/examples/H5PL_examples.c b/doxygen/examples/H5PL_examples.c new file mode 100644 index 0000000..d012d1b --- /dev/null +++ b/doxygen/examples/H5PL_examples.c @@ -0,0 +1,97 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_set; + // enable ONLY filter plugins + if (H5PLset_loading_state(H5PL_FILTER_PLUGIN) < 0) { + ret_val = EXIT_FAILURE; + goto fail_set; + } + + // ensure that "/tmp" is at the front of the search path list + if (H5PLprepend("/tmp") < 0) { + ret_val = EXIT_FAILURE; + } + +fail_set:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_read; + unsigned size, mask; + char buf[255]; + + // retrieve the number of entries in the plugin path list + if (H5PLsize(&size) < 0) { + ret_val = EXIT_FAILURE; + goto fail_read; + } + printf("Number of stored plugin paths: %d\n", size); + + // check the plugin state mask + if (H5PLget_loading_state(&mask) < 0) { + ret_val = EXIT_FAILURE; + goto fail_read; + } + printf("Filter plugins %s be loaded.\n", (mask & H5PL_FILTER_PLUGIN) == 1 ? "can" : "can't"); + printf("VOL plugins %s be loaded.\n", (mask & H5PL_VOL_PLUGIN) == 2 ? "can" : "can't"); + + // print the paths in the plugin path list + for (unsigned i = 0; i < size; ++i) { + if (H5PLget(i, buf, 255) < 0) { + ret_val = EXIT_FAILURE; + break; + } + printf("%s\n", buf); + } + +fail_read:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + // replace "/tmp" with something more sensible + if (H5PLreplace("/foo/bar", 0) < 0) { + ret_val = EXIT_FAILURE; + } + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_delete; + unsigned size; + + if (H5PLsize(&size) < 0) { + ret_val = EXIT_FAILURE; + goto fail_delete; + } + + // clean out the list of plugin paths + for (int i = size - 1; i >= 0; --i) { + if (H5PLremove(i) < 0) { + ret_val = EXIT_FAILURE; + break; + } + } + +fail_delete:; + } + //! <!-- [delete] --> + + return ret_val; +} diff --git a/doxygen/examples/H5P_examples.c b/doxygen/examples/H5P_examples.c new file mode 100644 index 0000000..cdfc03b --- /dev/null +++ b/doxygen/examples/H5P_examples.c @@ -0,0 +1,227 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_dcpl; + hid_t dcpl; + + // every property list is created as an instance of a suitable + // property list class + if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // ... + + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_dcpl, fail_plist_cls_id; + hid_t dcpl, plist_cls_id; + + if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + // to perform introspection on any kind of property list, + // we need to determine its property list class by obtaining a handle + if ((plist_cls_id = H5Pget_class(dcpl)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_plist_cls_id; + } + // Compare the handle to the handles of built-in or user-defined + // property list classes + assert(H5Pequal(plist_cls_id, H5P_DATASET_CREATE) > 0); + +fail_plist_cls_id: + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_dcpl, fail_prop; + hid_t dcpl; + + if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // a property list is updated by adding (or removing) properties + if (H5Pset_fill_time(dcpl, H5D_FILL_TIME_NEVER) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + +fail_prop: + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_dcpl; + hid_t dcpl; + + if ((dcpl = H5Pcreate(H5P_DATASET_CREATE)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dcpl; + } + + // a property list is "deleted" by closing it + H5Pclose(dcpl); +fail_dcpl:; + } + //! <!-- [delete] --> + + //! <!-- [create_class] --> + { + __label__ fail_cls, fail_prop; + hid_t plist_cls, plist; + int izero = 0; + double dzero = 0.0; + + // create a new property list class + if ((plist_cls = H5Pcreate_class(H5P_ROOT, "int & double", NULL, NULL, NULL, NULL, NULL, NULL)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_cls; + } + // add a permanent integer property + if (H5Pregister2(plist_cls, "int", sizeof(int), &izero, NULL, NULL, NULL, NULL, NULL, NULL, NULL) < + 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // add a permanent double property + if (H5Pregister2(plist_cls, "double", sizeof(double), &dzero, NULL, NULL, NULL, NULL, NULL, NULL, + NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // create an instance of this user-defined property list class + if ((plist = H5Pcreate(plist_cls)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + + // ... + + H5Pclose(plist); +fail_prop: + H5Pclose_class(plist_cls); +fail_cls:; + } + //! <!-- [create_class] --> + + //! <!-- [read_class] --> + { + __label__ fail_cls, fail_prop, fail_plist; + hid_t plist_cls, plist; + size_t nprops; + + if ((plist_cls = H5Pcreate_class(H5P_ROOT, "ud_plist", NULL, NULL, NULL, NULL, NULL, NULL)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_cls; + } + if ((plist = H5Pcreate(plist_cls)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + if (H5Pinsert2(plist, "temp", 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_plist; + } + // count the registered properties of this class + if (H5Pget_nprops(plist_cls, &nprops) < 0) { + ret_val = EXIT_FAILURE; + goto fail_plist; + } + // this will be 0 as there are no registered properties + printf("Property list class has %lu registered properties.\n", nprops); + + // count the properties in this property list + if (H5Pget_nprops(plist, &nprops) < 0) { + ret_val = EXIT_FAILURE; + goto fail_plist; + } + // will be 1 as there is one temporary property + printf("Property list has %lu property.\n", nprops); + +fail_plist: + H5Pclose(plist); +fail_prop: + H5Pclose_class(plist_cls); +fail_cls:; + } + //! <!-- [read_class] --> + + //! <!-- [update_class] --> + { + __label__ fail_cls, fail_prop, fail_plist; + hid_t plist_cls, plist; + + if ((plist_cls = H5Pcreate_class(H5P_ROOT, "ud_plist", NULL, NULL, NULL, NULL, NULL, NULL)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_cls; + } + // create an instance of this user-defined property list class + if ((plist = H5Pcreate(plist_cls)) < 0) { + ret_val = EXIT_FAILURE; + goto fail_prop; + } + // insert a temporary property + if (H5Pinsert2(plist, "temp", 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_plist; + } + +fail_plist: + H5Pclose(plist); +fail_prop: + H5Pclose_class(plist_cls); +fail_cls:; + } + //! <!-- [update_class] --> + + //! <!-- [delete_class] --> + { + __label__ fail_cls; + hid_t plist_cls; + + if ((plist_cls = H5Pcreate_class(H5P_ROOT, "int & double", NULL, NULL, NULL, NULL, NULL, NULL)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_cls; + } + // ... + + // a user defined property list class is destroyed by closing the handle + H5Pclose_class(plist_cls); +fail_cls:; + } + //! <!-- [delete_class] --> + + return ret_val; +} diff --git a/doxygen/examples/H5R_examples.c b/doxygen/examples/H5R_examples.c new file mode 100644 index 0000000..b40b992 --- /dev/null +++ b/doxygen/examples/H5R_examples.c @@ -0,0 +1,171 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_file, fail_fspace, fail_dset, fail_sel, fail_aspace, fail_attr, fail_awrite; + hid_t file, fspace, dset, aspace, attr; + H5R_ref_t ref; + + if ((file = H5Fcreate("reference.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // create a region reference which selects all elements of the dataset at "/data" + if ((fspace = H5Screate_simple(2, (hsize_t[]){10, 20}, NULL)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_fspace; + } + if ((dset = H5Dcreate(file, "data", H5T_STD_I32LE, fspace, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dset; + } + if (H5Sselect_all(fspace) < 0 || H5Rcreate_region(file, "data", fspace, H5P_DEFAULT, &ref) < 0) { + ret_val = EXIT_FAILURE; + goto fail_sel; + } + // store the region reference in a scalar attribute of the root group called "region" + if ((aspace = H5Screate(H5S_SCALAR)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_aspace; + } + if ((attr = H5Acreate(file, "region", H5T_STD_REF, aspace, H5P_DEFAULT, H5P_DEFAULT)) == + H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_attr; + } + if (H5Awrite(attr, H5T_STD_REF, &ref) < 0) { + ret_val = EXIT_FAILURE; + goto fail_awrite; + } + +fail_awrite: + H5Aclose(attr); +fail_attr: + H5Sclose(aspace); +fail_aspace: + H5Rdestroy(&ref); +fail_sel: + H5Dclose(dset); +fail_dset: + H5Sclose(fspace); +fail_fspace: + H5Fclose(file); +fail_file:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_file, fail_attr, fail_aread; + hid_t file, attr; + H5R_ref_t ref; + + if ((file = H5Fopen("reference.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // read the dataset region reference from the attribute + if ((attr = H5Aopen(file, "region", H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_attr; + } + if (H5Aread(attr, H5T_STD_REF, &ref) < 0) { + ret_val = EXIT_FAILURE; + goto fail_aread; + } + assert(H5Rget_type(&ref) == H5R_DATASET_REGION2); + + // get an HDF5 path name for the dataset of the region reference + { + char buf[255]; + if (H5Rget_obj_name(&ref, H5P_DEFAULT, buf, 255) < 0) { + ret_val = EXIT_FAILURE; + } + printf("Object name: \"%s\"\n", buf); + } + + H5Rdestroy(&ref); +fail_aread: + H5Aclose(attr); +fail_attr: + H5Fclose(file); +fail_file:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_file, fail_attr, fail_ref; + hid_t file, attr; + H5R_ref_t ref; + + if ((file = H5Fopen("reference.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + + // H5T_STD_REF is a generic reference type + // we can "update" the attribute value to refer to the attribute itself + if ((attr = H5Aopen(file, "region", H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_attr; + } + if (H5Rcreate_attr(file, "data", "region", H5P_DEFAULT, &ref) < 0) { + ret_val = EXIT_FAILURE; + goto fail_ref; + } + + assert(H5Rget_type(&ref) == H5R_ATTR); + + if (H5Awrite(attr, H5T_STD_REF, &ref) < 0) { + ret_val = EXIT_FAILURE; + } + + H5Rdestroy(&ref); +fail_ref: + H5Aclose(attr); +fail_attr: + H5Fclose(file); +fail_file:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_file, fail_ref; + hid_t file; + H5R_ref_t ref; + + // create an HDF5 object reference to the root group + if ((file = H5Fopen("reference.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + if (H5Rcreate_object(file, ".", H5P_DEFAULT, &ref) < 0) { + ret_val = EXIT_FAILURE; + goto fail_ref; + } + + // H5Rdestroy() releases all resources associated with an HDF5 reference + H5Rdestroy(&ref); +fail_ref: + H5Fclose(file); +fail_file:; + } + //! <!-- [delete] --> + + return ret_val; +} diff --git a/doxygen/examples/H5S_examples.c b/doxygen/examples/H5S_examples.c new file mode 100644 index 0000000..c542ec0 --- /dev/null +++ b/doxygen/examples/H5S_examples.c @@ -0,0 +1,132 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_dspace; + hid_t dspace; + + // create a 2D chess board shape (8x8) + if ((dspace = H5Screate_simple(2, (hsize_t[]){8, 8}, NULL)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dspace; + } + + H5Sclose(dspace); +fail_dspace:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_dspace; + hid_t dspace; + + if ((dspace = H5Screate(H5S_NULL)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dspace; + } + + // make changes to the selection on DSPACE + // ... + // parse the resulting selection + + switch (H5Sget_select_type(dspace)) { + case H5S_SEL_HYPERSLABS: + // we are dealing with a hyperslab selection + // determine the regularity and block structure + break; + case H5S_SEL_POINTS: + // we are dealing with a point selection + // for example, retrieve the point list + break; + case H5S_SEL_ALL: + // all dataset elements are selected + break; + case H5S_SEL_NONE: + // the selection is empty + break; + default: + ret_val = EXIT_FAILURE; + break; + } + + if (dspace != H5S_ALL) + H5Sclose(dspace); + +fail_dspace:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_select, fail_dspace; + hid_t dspace; + + // create a 2D chess board shape (8x8) + if ((dspace = H5Screate_simple(2, (hsize_t[]){8, 8}, NULL)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dspace; + } + // select all black fields: do this w/ a hyperslab union in two steps + + // select the black fields on even rows + if (H5Sselect_hyperslab(dspace, H5S_SELECT_SET, (hsize_t[]){0, 0}, (hsize_t[]){2, 2}, + (hsize_t[]){4, 4}, NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_select; + } + // select the black fields on odd rows + // notice the H5S_SELECT_OR operator + if (H5Sselect_hyperslab(dspace, H5S_SELECT_OR, (hsize_t[]){1, 1}, (hsize_t[]){2, 2}, + (hsize_t[]){4, 4}, NULL) < 0) { + ret_val = EXIT_FAILURE; + goto fail_select; + } + + // should be 32 + printf("%lld elements selected.\n", H5Sget_select_npoints(dspace)); + +fail_select: + H5Sclose(dspace); +fail_dspace:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_select, fail_dspace; + hid_t dspace; + + if ((dspace = H5Screate(H5S_NULL)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dspace; + } + + // make changes to and work with the selection on DSPACE + // ... + // finally, clear the selection + + if (H5Sselect_none(dspace) < 0) { + ret_val = EXIT_FAILURE; + goto fail_select; + } + +fail_select: + if (dspace != H5S_ALL) + H5Sclose(dspace); +fail_dspace:; + } + //! <!-- [delete] --> + + return ret_val; +} diff --git a/doxygen/examples/H5T_examples.c b/doxygen/examples/H5T_examples.c new file mode 100644 index 0000000..7cfa7d4 --- /dev/null +++ b/doxygen/examples/H5T_examples.c @@ -0,0 +1,136 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <stdio.h> +#include <stdlib.h> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_insert, fail_dtype, fail_file; + hid_t file, dtype; + + if ((file = H5Fcreate("t1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // create a compound datatype with room for real and imaginary parts + if ((dtype = H5Tcreate(H5T_COMPOUND, 2 * sizeof(double))) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dtype; + } + // add the real part now and the imaginary part later + if (H5Tinsert(dtype, "re", 0, H5T_IEEE_F64LE) < 0) { + ret_val = EXIT_FAILURE; + goto fail_insert; + } + // commit the datatype definition to the file + if (H5Tcommit(file, "pre-complex", dtype, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + +fail_insert: + H5Tclose(dtype); +fail_dtype: + H5Fclose(file); +fail_file:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_dtype, fail_file; + hid_t file, dtype; + + if ((file = H5Fopen("t1.h5", H5F_ACC_RDONLY, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // open the datatype object stored in the file + if ((dtype = H5Topen(file, "pre-complex", H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dtype; + } + + switch (H5Tget_class(dtype)) { // this time we are only interested in compounds + case H5T_COMPOUND: + printf("Record size: %lu bytes\n", H5Tget_size(dtype)); + printf("Record has %d field(s).\n", H5Tget_nmembers(dtype)); + break; + default: + break; + } + + H5Tclose(dtype); +fail_dtype: + H5Fclose(file); +fail_file:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + __label__ fail_insert, fail_clone, fail_dtype, fail_file; + hid_t file, dtype, clone; + + if ((file = H5Fopen("t1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // open the datatype object stored in the file + if ((dtype = H5Topen(file, "pre-complex", H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_dtype; + } + // the original datatype object is immutable and we need to clone it + if ((clone = H5Tcopy(dtype)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_clone; + } + // remember that the original has enough room for real and imaginary parts + // add the imaginary part + if (H5Tinsert(clone, "im", sizeof(double), H5T_IEEE_F64LE) < 0) { + ret_val = EXIT_FAILURE; + goto fail_insert; + } + // commit the "updated" datatype definition to the file + if (H5Tcommit(file, "complex", clone, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + +fail_insert: + H5Tclose(clone); +fail_clone: + H5Tclose(dtype); +fail_dtype: + H5Fclose(file); +fail_file:; + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { + __label__ fail_file; + hid_t file; + + if ((file = H5Fopen("t1.h5", H5F_ACC_RDWR, H5P_DEFAULT)) == H5I_INVALID_HID) { + ret_val = EXIT_FAILURE; + goto fail_file; + } + // delete the "pre-complex" datatype by unlinking + if (H5Ldelete(file, "pre-complex", H5P_DEFAULT) < 0) { + ret_val = EXIT_FAILURE; + } + + H5Fclose(file); +fail_file:; + } + //! <!-- [delete] --> + + return ret_val; +} diff --git a/doxygen/examples/H5Z_examples.c b/doxygen/examples/H5Z_examples.c new file mode 100644 index 0000000..28a1ea2 --- /dev/null +++ b/doxygen/examples/H5Z_examples.c @@ -0,0 +1,108 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +//! <!-- [filter] --> +size_t +filter(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[], size_t nbytes, size_t *buf_size, + void **buf) +{ + buf_size = 0; + + if (flags & H5Z_FLAG_REVERSE) { + // read data, e.g., decompress data + // ... + } + else { + // write data, e.g., compress data + // ... + } + + return nbytes; +} +//! <!-- [filter] --> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + __label__ fail_register; + H5Z_class_t cls; + cls.version = H5Z_CLASS_T_VERS; + cls.id = 256; + cls.encoder_present = 1; + cls.decoder_present = 1; + cls.name = "Identity filter"; + cls.can_apply = NULL; + cls.set_local = NULL; + cls.filter = &filter; + + // register the filter + if (H5Zregister(&cls) < 0) { + ret_val = EXIT_FAILURE; + goto fail_register; + } + + // do something with filter + // ... + + // unregister the filter if no longer required + // ... + +fail_register:; + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_avail; + + H5Z_filter_t flt = H5Z_FILTER_DEFLATE; + unsigned flags = 0; + + // check if the deflate filter is available + if (H5Zfilter_avail(flt) < 0) { + ret_val = EXIT_FAILURE; + goto fail_avail; + } + // retrieve the deflate filter info + if (H5Zget_filter_info(flt, &flags) < 0) { + ret_val = EXIT_FAILURE; + goto fail_avail; + } + + // check if the deflate encoder or decoder is enabled + if (H5Z_FILTER_CONFIG_ENCODE_ENABLED & flags) + printf("Deflate encoder enabled.\n"); + if (H5Z_FILTER_CONFIG_DECODE_ENABLED & flags) + printf("Deflate decoder enabled.\n"); + +fail_avail:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + // N/A + } //! <!-- [update] --> + + //! <!-- [delete] --> + { + // unregister the identity filter + if (H5Zunregister(256) < 0) { + ret_val = EXIT_FAILURE; + } + } + //! <!-- [delete] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/examples/H5_examples.c b/doxygen/examples/H5_examples.c new file mode 100644 index 0000000..ef52ed0 --- /dev/null +++ b/doxygen/examples/H5_examples.c @@ -0,0 +1,85 @@ +/* -*- c-file-style: "stroustrup" -*- */ + +#include "hdf5.h" + +#include <assert.h> +#include <stdio.h> +#include <stdlib.h> + +//! <!-- [closing_shop] --> +void +closing_shop(void *ctx) +{ + printf("GoodBye, Cruel World!\n"); +} +//! <!-- [closing_shop] --> + +int +main(void) +{ + int ret_val = EXIT_SUCCESS; + + //! <!-- [create] --> + { + // an HDF5 library instance is automatically initialized as + // part of the first HDF5 API call, but there's no harm in + // calling H5open(). + if (H5open() < 0) { + ret_val = EXIT_FAILURE; + } + } + //! <!-- [create] --> + + //! <!-- [read] --> + { + __label__ fail_read; + unsigned majnum, minnum, relnum; + hbool_t flag; + + // retrieve the library version + if (H5get_libversion(&majnum, &minnum, &relnum) < 0) { + ret_val = EXIT_FAILURE; + goto fail_read; + } + // is this a thread-safe library build? + if (H5is_library_threadsafe(&flag) < 0) { + ret_val = EXIT_FAILURE; + goto fail_read; + } + + printf("Welcome to HDF5 %d.%d.%d\n", majnum, minnum, relnum); + printf("Thread-safety %s\n", (flag > 0) ? "enabled" : "disabled"); + +fail_read:; + } + //! <!-- [read] --> + + //! <!-- [update] --> + { + // update the library instance free list limits + if (H5set_free_list_limits(512 * 1024, 32 * 1024, 2048 * 1024, 128 * 1024, 8192 * 1024, 512 * 1024) < + 0) { + ret_val = EXIT_FAILURE; + } + } + //! <!-- [update] --> + + //! <!-- [delete] --> + { +#if H5_VERSION_GE(1, 13, 0) + // install a finalization routine + if (H5atclose(&closing_shop, NULL) < 0) { + ret_val = EXIT_FAILURE; + } +#endif + // close shop + if (H5close() < 0) { + ret_val = EXIT_FAILURE; + } + } + //! <!-- [delete] --> + + assert(ret_val == EXIT_SUCCESS); + + return ret_val; +} diff --git a/doxygen/hdf5_header.html b/doxygen/hdf5_header.html index 4a575d6..23f41f9 100644 --- a/doxygen/hdf5_header.html +++ b/doxygen/hdf5_header.html @@ -21,7 +21,7 @@ $mathjax </head> <body> -<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better know about our user community by answering the following short survey: <a href="https://www.hdfgroup.org/">https://www.hdfgroup.org/</a></div> +<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better know about our user community by answering the following short survey: <a href="https://www.hdfgroup.org/website-survey/">https://www.hdfgroup.org/website-survey/</a></div> <div id="top"><!-- do not remove this div, it is closed by doxygen! --> diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml index 7f71c24..fc20aa1 100644 --- a/doxygen/hdf5doxy_layout.xml +++ b/doxygen/hdf5doxy_layout.xml @@ -11,6 +11,7 @@ <tab type="user" url="@ref RM" title="Reference Manual" /> <tab type="user" url="@ref TN" title="Technical Notes" /> <tab type="user" url="@ref SPEC" title="Specifications" /> + <tab type="user" url="@ref RFC" title="RFCs" /> <tab type="user" url="@ref About" title="About" /> </navindex> diff --git a/hl/CMakeLists.txt b/hl/CMakeLists.txt index 083c60e..5061c6c 100644 --- a/hl/CMakeLists.txt +++ b/hl/CMakeLists.txt @@ -7,9 +7,17 @@ project (HDF5_HL C) add_subdirectory (src) -#-- Build the High level Tools +# Build HDF5 Tools if (HDF5_BUILD_TOOLS) - add_subdirectory (tools) + #----------------------------------------------------------------------------- + #-- Option to build the High level Tools + #----------------------------------------------------------------------------- + if (EXISTS "${HDF5_HL_SOURCE_DIR}/tools" AND IS_DIRECTORY "${HDF5_HL_SOURCE_DIR}/tools") + option (HDF5_BUILD_HL_TOOLS "Build HDF5 HL Tools" ON) + if (HDF5_BUILD_HL_TOOLS) + add_subdirectory (tools) + endif () + endif () endif () #-- Add High Level Examples diff --git a/hl/Makefile.am b/hl/Makefile.am index 9bf209e..8c427d3 100644 --- a/hl/Makefile.am +++ b/hl/Makefile.am @@ -37,16 +37,19 @@ else TEST_DIR = endif if BUILD_TOOLS_CONDITIONAL +if BUILD_TOOLS_HL_CONDITIONAL TOOLS_DIR = tools else TOOLS_DIR = endif +else + TOOLS_DIR = +endif ## Don't recurse into any subdirectories if HDF5 is not configured to ## use the HL library if BUILD_HDF5_HL_CONDITIONAL SUBDIRS=src $(TEST_DIR) $(TOOLS_DIR) $(CXX_DIR) $(FORTRAN_DIR) - endif DIST_SUBDIRS=src test tools c++ fortran examples diff --git a/hl/src/CMakeLists.txt b/hl/src/CMakeLists.txt index 7678de8..a97d6fa 100644 --- a/hl/src/CMakeLists.txt +++ b/hl/src/CMakeLists.txt @@ -169,3 +169,32 @@ if (NOT WIN32 AND NOT MINGW) COMPONENT hllibraries ) endif () + +#----------------------------------------------------------------------------- +# Option to build documentation +#----------------------------------------------------------------------------- +if (DOXYGEN_FOUND) +# This cmake function requires that the non-default doxyfile settings are provided with set (DOXYGEN_xxx) commands +# In addition the doxyfile aliases @INCLUDE option is not supported and would need to be provided in a set (DOXYGEN_ALIASES) command. +# doxygen_add_docs (hdf5lib_doc +## ${HL_SOURCES} ${HL_HEADERS} ${HDF5_DOXYGEN_DIR}/dox +# ${DOXYGEN_INPUT_DIRECTORY} +# ALL +# WORKING_DIRECTORY ${HDF5_HL_SRC_DIR} +# COMMENT "Generating HDF5 HL library Source Documentation" +# ) + +# This custom target and doxygen/configure work together + # Replace variables inside @@ with the current values + add_custom_target (hdf5hllib_doc ALL + COMMAND ${DOXYGEN_EXECUTABLE} ${HDF5_BINARY_DIR}/Doxyfile + WORKING_DIRECTORY ${HDF5_HL_SRC_DIR} + COMMENT "Generating HDF5 HL library Source API documentation with Doxygen" + VERBATIM ) + + if (NOT TARGET doxygen) + add_custom_target (doxygen) + endif () + + add_dependencies (doxygen hdf5hllib_doc) +endif () diff --git a/hl/src/H5LT.c b/hl/src/H5LT.c index 1ef0f9d..8f2b33f 100644 --- a/hl/src/H5LT.c +++ b/hl/src/H5LT.c @@ -1352,13 +1352,13 @@ find_dataset(H5_ATTR_UNUSED hid_t loc_id, const char *name, H5_ATTR_UNUSED const * modify the op_data buffer (i.e.: dset_name) during the traversal, and the * library never modifies that buffer. */ -H5_GCC_DIAG_OFF("cast-qual") +H5_GCC_CLANG_DIAG_OFF("cast-qual") herr_t H5LTfind_dataset(hid_t loc_id, const char *dset_name) { return H5Literate2(loc_id, H5_INDEX_NAME, H5_ITER_INC, 0, find_dataset, (void *)dset_name); } -H5_GCC_DIAG_ON("cast-qual") +H5_GCC_CLANG_DIAG_ON("cast-qual") /*------------------------------------------------------------------------- * @@ -1776,6 +1776,32 @@ H5LTset_attribute_ulong(hid_t loc_id, const char *obj_name, const char *attr_nam } /*------------------------------------------------------------------------- + * Function: H5LTset_attribute_ullong + * + * Purpose: Create and write an attribute. + * + * Return: Success: 0, Failure: -1 + * + * Programmer: Alessandro Felder + * + * Date: August 27, 2021 + * + * Comments: + * + *------------------------------------------------------------------------- + */ +herr_t +H5LTset_attribute_ullong(hid_t loc_id, const char *obj_name, const char *attr_name, + const unsigned long long *data, size_t size) +{ + + if (H5LT_set_attribute_numerical(loc_id, obj_name, attr_name, size, H5T_NATIVE_ULLONG, data) < 0) + return -1; + + return 0; +} + +/*------------------------------------------------------------------------- * Function: H5LTset_attribute_float * * Purpose: Create and write an attribute. @@ -1919,13 +1945,13 @@ H5LTfind_attribute(hid_t loc_id, const char *attr_name) * modify the op_data buffer (i.e.: attr_name) during the traversal, and the * library never modifies that buffer. */ -H5_GCC_DIAG_OFF("cast-qual") +H5_GCC_CLANG_DIAG_OFF("cast-qual") herr_t H5LT_find_attribute(hid_t loc_id, const char *attr_name) { return H5Aiterate2(loc_id, H5_INDEX_NAME, H5_ITER_INC, NULL, find_attr, (void *)attr_name); } -H5_GCC_DIAG_ON("cast-qual") +H5_GCC_CLANG_DIAG_ON("cast-qual") /*------------------------------------------------------------------------- * Function: H5LTget_attribute_ndims @@ -2180,7 +2206,7 @@ realloc_and_append(hbool_t _no_user_buf, size_t *len, char *buf, const char *str */ if (size_str < *len - 1) { if (size_str + size_str_to_add < *len - 1) { - HDstrncat(buf, str_to_add, size_str_to_add); + HDstrcat(buf, str_to_add); } else { HDstrncat(buf, str_to_add, (*len - 1) - size_str); @@ -3317,6 +3343,33 @@ H5LTget_attribute_ulong(hid_t loc_id, const char *obj_name, const char *attr_nam } /*------------------------------------------------------------------------- + * Function: H5LTget_attribute_ullong + * + * Purpose: Reads an attribute named attr_name + * + * Return: Success: 0, Failure: -1 + * + * Programmer: Alessandro Felder + * + * Date: August 27, 2021 + * + * Comments: + * + * Modifications: + * + *------------------------------------------------------------------------- + */ +herr_t +H5LTget_attribute_ullong(hid_t loc_id, const char *obj_name, const char *attr_name, unsigned long long *data) +{ + /* Get the attribute */ + if (H5LT_get_attribute_mem(loc_id, obj_name, attr_name, H5T_NATIVE_ULLONG, data) < 0) + return -1; + + return 0; +} + +/*------------------------------------------------------------------------- * Function: H5LTget_attribute_float * * Purpose: Reads an attribute named attr_name diff --git a/hl/src/H5LTpublic.h b/hl/src/H5LTpublic.h index 2af9b07..f19d353 100644 --- a/hl/src/H5LTpublic.h +++ b/hl/src/H5LTpublic.h @@ -139,6 +139,9 @@ H5_HLDLL herr_t H5LTset_attribute_long_long(hid_t loc_id, const char *obj_name, H5_HLDLL herr_t H5LTset_attribute_ulong(hid_t loc_id, const char *obj_name, const char *attr_name, const unsigned long *buffer, size_t size); +H5_HLDLL herr_t H5LTset_attribute_ullong(hid_t loc_id, const char *obj_name, const char *attr_name, + const unsigned long long *buffer, size_t size); + H5_HLDLL herr_t H5LTset_attribute_float(hid_t loc_id, const char *obj_name, const char *attr_name, const float *buffer, size_t size); @@ -182,6 +185,9 @@ H5_HLDLL herr_t H5LTget_attribute_long_long(hid_t loc_id, const char *obj_name, H5_HLDLL herr_t H5LTget_attribute_ulong(hid_t loc_id, const char *obj_name, const char *attr_name, unsigned long *data); +H5_HLDLL herr_t H5LTget_attribute_ullong(hid_t loc_id, const char *obj_name, const char *attr_name, + unsigned long long *data); + H5_HLDLL herr_t H5LTget_attribute_float(hid_t loc_id, const char *obj_name, const char *attr_name, float *data); diff --git a/hl/test/test_lite.c b/hl/test/test_lite.c index aa5f5ab..2276b8f 100644 --- a/hl/test/test_lite.c +++ b/hl/test/test_lite.c @@ -43,8 +43,9 @@ #define ATTR7_NAME "attr ushort" #define ATTR8_NAME "attr uint" #define ATTR9_NAME "attr ulong" -#define ATTR10_NAME "attr float" -#define ATTR11_NAME "attr double" +#define ATTR10_NAME "attr ullong" +#define ATTR11_NAME "attr float" +#define ATTR12_NAME "attr double" static herr_t make_attributes(hid_t loc_id, const char *obj_name); @@ -472,28 +473,30 @@ make_attributes(hid_t loc_id, const char *obj_name) size_t type_size; int i; - char attr_str_in[] = {"My attribute"}; - char attr_str_out[20]; - char attr_char_in[5] = {1, 2, 3, 4, 5}; - char attr_char_out[5]; - short attr_short_in[5] = {1, 2, 3, 4, 5}; - short attr_short_out[5]; - int attr_int_in[5] = {1, 2, 3, 4, 5}; - int attr_int_out[5]; - long attr_long_in[5] = {1, 2, 3, 4, 5}; - long attr_long_out[5]; - float attr_float_in[5] = {1, 2, 3, 4, 5}; - float attr_float_out[5]; - double attr_double_in[5] = {1, 2, 3, 4, 5}; - double attr_double_out[5]; - unsigned char attr_uchar_in[5] = {1, 2, 3, 4, 5}; - unsigned char attr_uchar_out[5]; - unsigned short attr_ushort_in[5] = {1, 2, 3, 4, 5}; - unsigned short attr_ushort_out[5]; - unsigned int attr_uint_in[5] = {1, 2, 3, 4, 5}; - unsigned int attr_uint_out[5]; - unsigned long attr_ulong_in[5] = {1, 2, 3, 4, 5}; - unsigned long attr_ulong_out[5]; + char attr_str_in[] = {"My attribute"}; + char attr_str_out[20]; + char attr_char_in[5] = {1, 2, 3, 4, 5}; + char attr_char_out[5]; + short attr_short_in[5] = {1, 2, 3, 4, 5}; + short attr_short_out[5]; + int attr_int_in[5] = {1, 2, 3, 4, 5}; + int attr_int_out[5]; + long attr_long_in[5] = {1, 2, 3, 4, 5}; + long attr_long_out[5]; + float attr_float_in[5] = {1, 2, 3, 4, 5}; + float attr_float_out[5]; + double attr_double_in[5] = {1, 2, 3, 4, 5}; + double attr_double_out[5]; + unsigned char attr_uchar_in[5] = {1, 2, 3, 4, 5}; + unsigned char attr_uchar_out[5]; + unsigned short attr_ushort_in[5] = {1, 2, 3, 4, 5}; + unsigned short attr_ushort_out[5]; + unsigned int attr_uint_in[5] = {1, 2, 3, 4, 5}; + unsigned int attr_uint_out[5]; + unsigned long attr_ulong_in[5] = {1, 2, 3, 4, 5}; + unsigned long attr_ulong_out[5]; + unsigned long long attr_ullong_in[5] = {1, 2, 3, 4, 5}; + unsigned long long attr_ullong_out[5]; /*------------------------------------------------------------------------- * H5LTset_attribute_string test @@ -509,7 +512,7 @@ make_attributes(hid_t loc_id, const char *obj_name) PASSED(); /*------------------------------------------------------------------------- - * H5LTset_attribute_string test + * H5LTget_attribute_string test *------------------------------------------------------------------------- */ @@ -859,7 +862,7 @@ make_attributes(hid_t loc_id, const char *obj_name) PASSED(); /*------------------------------------------------------------------------- - * H5LTget_attribute_long test + * H5LTget_attribute_ulong test *------------------------------------------------------------------------- */ @@ -888,6 +891,48 @@ make_attributes(hid_t loc_id, const char *obj_name) PASSED(); /*------------------------------------------------------------------------- + * H5LTset_attribute_ullong test + *------------------------------------------------------------------------- + */ + + HL_TESTING2("H5LTset_attribute_ullong"); + + /* Set the attribute */ + if (H5LTset_attribute_ullong(loc_id, obj_name, ATTR10_NAME, attr_ullong_in, (size_t)5) < 0) + return -1; + + PASSED(); + + /*------------------------------------------------------------------------- + * H5LTget_attribute_ullong test + *------------------------------------------------------------------------- + */ + + HL_TESTING2("H5LTget_attribute_ullong"); + + /* Get the attribute */ + if (H5LTget_attribute_ullong(loc_id, obj_name, ATTR10_NAME, attr_ullong_out) < 0) + return -1; + + for (i = 0; i < 5; i++) { + if (attr_ullong_in[i] != attr_ullong_out[i]) { + return -1; + } + } + + /* Get the attribute */ + if (H5LTget_attribute(loc_id, obj_name, ATTR10_NAME, H5T_NATIVE_ULLONG, attr_ullong_out) < 0) + return -1; + + for (i = 0; i < 5; i++) { + if (attr_ullong_in[i] != attr_ullong_out[i]) { + return -1; + } + } + + PASSED(); + + /*------------------------------------------------------------------------- * H5LTset_attribute_float test *------------------------------------------------------------------------- */ @@ -895,7 +940,7 @@ make_attributes(hid_t loc_id, const char *obj_name) HL_TESTING2("H5LTset_attribute_float"); /* Set the attribute */ - if (H5LTset_attribute_float(loc_id, obj_name, ATTR10_NAME, attr_float_in, (size_t)5) < 0) + if (H5LTset_attribute_float(loc_id, obj_name, ATTR11_NAME, attr_float_in, (size_t)5) < 0) return -1; PASSED(); @@ -908,7 +953,7 @@ make_attributes(hid_t loc_id, const char *obj_name) HL_TESTING2("H5LTget_attribute_float"); /* Get the attribute */ - if (H5LTget_attribute_float(loc_id, obj_name, ATTR10_NAME, attr_float_out) < 0) + if (H5LTget_attribute_float(loc_id, obj_name, ATTR11_NAME, attr_float_out) < 0) return -1; for (i = 0; i < 5; i++) { @@ -918,7 +963,7 @@ make_attributes(hid_t loc_id, const char *obj_name) } /* Get the attribute */ - if (H5LTget_attribute(loc_id, obj_name, ATTR10_NAME, H5T_NATIVE_FLOAT, attr_float_out) < 0) + if (H5LTget_attribute(loc_id, obj_name, ATTR11_NAME, H5T_NATIVE_FLOAT, attr_float_out) < 0) return -1; for (i = 0; i < 5; i++) { @@ -937,7 +982,7 @@ make_attributes(hid_t loc_id, const char *obj_name) HL_TESTING2("H5LTset_attribute_double"); /* Set the attribute */ - if (H5LTset_attribute_double(loc_id, obj_name, ATTR11_NAME, attr_double_in, (size_t)5) < 0) + if (H5LTset_attribute_double(loc_id, obj_name, ATTR12_NAME, attr_double_in, (size_t)5) < 0) return -1; PASSED(); @@ -950,7 +995,7 @@ make_attributes(hid_t loc_id, const char *obj_name) HL_TESTING2("H5LTget_attribute_double"); /* Get the attribute */ - if (H5LTget_attribute_double(loc_id, obj_name, ATTR11_NAME, attr_double_out) < 0) + if (H5LTget_attribute_double(loc_id, obj_name, ATTR12_NAME, attr_double_out) < 0) return -1; for (i = 0; i < 5; i++) { @@ -960,7 +1005,7 @@ make_attributes(hid_t loc_id, const char *obj_name) } /* Get the attribute */ - if (H5LTget_attribute(loc_id, obj_name, ATTR11_NAME, H5T_NATIVE_DOUBLE, attr_double_out) < 0) + if (H5LTget_attribute(loc_id, obj_name, ATTR12_NAME, H5T_NATIVE_DOUBLE, attr_double_out) < 0) return -1; for (i = 0; i < 5; i++) { diff --git a/java/src/hdf/hdf5lib/HDFArray.java b/java/src/hdf/hdf5lib/HDFArray.java index bb9357e..21e2b02 100644 --- a/java/src/hdf/hdf5lib/HDFArray.java +++ b/java/src/hdf/hdf5lib/HDFArray.java @@ -46,10 +46,10 @@ public class HDFArray { * * @param anArray * The array object. - * @exception hdf.hdf5lib.exceptions.HDF5Exception - * object is not an array. + * @exception hdf.hdf5lib.exceptions.HDF5JavaException + * object is not an array. */ - public HDFArray(Object anArray) throws HDF5Exception + public HDFArray(Object anArray) throws HDF5JavaException { if (anArray == null) { HDF5JavaException ex = new HDF5JavaException("HDFArray: array is null?: "); @@ -76,16 +76,14 @@ public class HDFArray { * @return A one-D array of bytes, filled with zeroes. The bytes are sufficient to hold the data of the Array passed * to the constructor. * @exception hdf.hdf5lib.exceptions.HDF5JavaException - * Allocation failed. + * Allocation failed. */ - public byte[] emptyBytes() - throws HDF5JavaException + public byte[] emptyBytes() throws HDF5JavaException { byte[] b = null; - if ((ArrayDescriptor.dims == 1) - && (ArrayDescriptor.NT == 'B')) { + if ((ArrayDescriptor.dims == 1) && (ArrayDescriptor.NT == 'B')) { b = (byte[]) _theArray; } else { @@ -103,10 +101,9 @@ public class HDFArray { * * @return A one-D array of bytes, constructed from the Array passed to the constructor. * @exception hdf.hdf5lib.exceptions.HDF5JavaException - * the object not an array or other internal error. + * the object not an array or other internal error. */ - public byte[] byteify() - throws HDF5JavaException + public byte[] byteify() throws HDF5JavaException { if (_barray != null) { return _barray; @@ -224,8 +221,6 @@ public class HDFArray { if (ArrayDescriptor.NT == 'J') { arow = HDFNativeData.longToByte(0, ArrayDescriptor.dimlen[ArrayDescriptor.dims], (long[]) ArrayDescriptor.objs[ArrayDescriptor.dims - 1]); - arow = HDFNativeData.longToByte(0, ArrayDescriptor.dimlen[ArrayDescriptor.dims], - (long[]) ArrayDescriptor.objs[ArrayDescriptor.dims - 1]); } else if (ArrayDescriptor.NT == 'I') { arow = HDFNativeData.intToByte(0, ArrayDescriptor.dimlen[ArrayDescriptor.dims], @@ -552,8 +547,7 @@ public class HDFArray { + "?")); } } - if (ArrayDescriptor.currentindex[ArrayDescriptor.dims - 1] != ArrayDescriptor.dimlen[ArrayDescriptor.dims - - 1]) { + if (ArrayDescriptor.currentindex[ArrayDescriptor.dims - 1] != ArrayDescriptor.dimlen[ArrayDescriptor.dims - 1]) { throw new java.lang.InternalError( new String("HDFArray::arrayify Panic didn't complete all data: currentindex[" + i + "] = " + ArrayDescriptor.currentindex[i] + " (should be " + (ArrayDescriptor.dimlen[i]) + "?")); @@ -580,7 +574,7 @@ public class HDFArray { Integer[] out = new Integer[nelems]; for (int i = 0; i < nelems; i++) { - out[i] = new Integer(in[i]); + out[i] = Integer.valueOf(in[i]); } return out; } @@ -592,7 +586,7 @@ public class HDFArray { Integer[] out = new Integer[nelems]; for (int i = 0; i < nelems; i++) { - out[i] = new Integer(in[i]); + out[i] = Integer.valueOf(in[i]); } return out; } @@ -615,7 +609,7 @@ public class HDFArray { Short[] out = new Short[nelems]; for (int i = 0; i < nelems; i++) { - out[i] = new Short(in[i]); + out[i] = Short.valueOf(in[i]); } return out; } @@ -627,7 +621,7 @@ public class HDFArray { Short[] out = new Short[nelems]; for (int i = 0; i < nelems; i++) { - out[i] = new Short(in[i]); + out[i] = Short.valueOf(in[i]); } return out; } @@ -649,7 +643,7 @@ public class HDFArray { Byte[] out = new Byte[nelems]; for (int i = 0; i < nelems; i++) { - out[i] = new Byte(bin[i]); + out[i] = Byte.valueOf(bin[i]); } return out; } @@ -659,7 +653,7 @@ public class HDFArray { Byte[] out = new Byte[len]; for (int i = 0; i < len; i++) { - out[i] = new Byte(bin[i]); + out[i] = Byte.valueOf(bin[i]); } return out; } @@ -682,7 +676,7 @@ public class HDFArray { Float[] out = new Float[nelems]; for (int i = 0; i < nelems; i++) { - out[i] = new Float(in[i]); + out[i] = Float.valueOf(in[i]); } return out; } @@ -694,7 +688,7 @@ public class HDFArray { Float[] out = new Float[nelems]; for (int i = 0; i < nelems; i++) { - out[i] = new Float(in[i]); + out[i] = Float.valueOf(in[i]); } return out; } @@ -717,7 +711,7 @@ public class HDFArray { Double[] out = new Double[nelems]; for (int i = 0; i < nelems; i++) { - out[i] = new Double(in[i]); + out[i] = Double.valueOf(in[i]); } return out; } @@ -729,7 +723,7 @@ public class HDFArray { Double[] out = new Double[nelems]; for (int i = 0; i < nelems; i++) { - out[i] = new Double(in[i]); + out[i] = Double.valueOf(in[i]); } return out; } @@ -752,7 +746,7 @@ public class HDFArray { Long[] out = new Long[nelems]; for (int i = 0; i < nelems; i++) { - out[i] = new Long(in[i]); + out[i] = Long.valueOf(in[i]); } return out; } @@ -764,7 +758,7 @@ public class HDFArray { Long[] out = new Long[nelems]; for (int i = 0; i < nelems; i++) { - out[i] = new Long(in[i]); + out[i] = Long.valueOf(in[i]); } return out; } @@ -790,12 +784,12 @@ class ArrayDescriptor { static int dims = 0; static String className; - public ArrayDescriptor(Object anArray) throws HDF5Exception + public ArrayDescriptor(Object anArray) throws HDF5JavaException { Class tc = anArray.getClass(); if (tc.isArray() == false) { /* exception: not an array */ - HDF5Exception ex = new HDF5JavaException("ArrayDescriptor: not an array?: "); + HDF5JavaException ex = new HDF5JavaException("ArrayDescriptor: not an array?: "); throw (ex); } diff --git a/java/src/hdf/hdf5lib/HDFNativeData.java b/java/src/hdf/hdf5lib/HDFNativeData.java index 5b29050..85378db 100644 --- a/java/src/hdf/hdf5lib/HDFNativeData.java +++ b/java/src/hdf/hdf5lib/HDFNativeData.java @@ -153,8 +153,7 @@ public class HDFNativeData { * The input array of bytes * @return an array of 'len' float */ - public synchronized static native float[] byteToFloat(int start, int len, - byte[] data); + public synchronized static native float[] byteToFloat(int start, int len, byte[] data); /** * Convert 4 bytes from an array of bytes into a single float @@ -437,41 +436,38 @@ public class HDFNativeData { * - Error unsupported type. */ public synchronized static Object byteToNumber(byte[] barray, Object obj) - throws HDF5Exception { + throws HDF5Exception + { Class theClass = obj.getClass(); String type = theClass.getName(); Object retobj = null; if (type.equals("java.lang.Integer")) { int[] i = hdf.hdf5lib.HDFNativeData.byteToInt(0, 1, barray); - retobj = new Integer(i[0]); + retobj = Integer.valueOf(i[0]); } else if (type.equals("java.lang.Byte")) { - retobj = new Byte(barray[0]); + retobj = Byte.valueOf(barray[0]); } else if (type.equals("java.lang.Short")) { - short[] f = hdf.hdf5lib.HDFNativeData - .byteToShort(0, 1, barray); - retobj = new Short(f[0]); + short[] f = hdf.hdf5lib.HDFNativeData.byteToShort(0, 1, barray); + retobj = Short.valueOf(f[0]); } else if (type.equals("java.lang.Float")) { - float[] f = hdf.hdf5lib.HDFNativeData - .byteToFloat(0, 1, barray); - retobj = new Float(f[0]); + float[] f = hdf.hdf5lib.HDFNativeData.byteToFloat(0, 1, barray); + retobj = Float.valueOf(f[0]); } else if (type.equals("java.lang.Long")) { long[] f = hdf.hdf5lib.HDFNativeData.byteToLong(0, 1, barray); - retobj = new Long(f[0]); + retobj = Long.valueOf(f[0]); } else if (type.equals("java.lang.Double")) { - double[] f = hdf.hdf5lib.HDFNativeData.byteToDouble(0, 1, - barray); - retobj = new Double(f[0]); + double[] f = hdf.hdf5lib.HDFNativeData.byteToDouble(0, 1, barray); + retobj = Double.valueOf(f[0]); } else { /* exception: unsupported type */ - HDF5Exception ex = new HDF5JavaException( - "byteToNumber: setfield bad type: " + obj + " " + type); + HDF5Exception ex = new HDF5JavaException("byteToNumber: setfield bad type: " + obj + " " + type); throw (ex); } return (retobj); diff --git a/java/src/hdf/hdf5lib/structs/H5FD_hdfs_fapl_t.java b/java/src/hdf/hdf5lib/structs/H5FD_hdfs_fapl_t.java index 5da4abd..95a9254 100644 --- a/java/src/hdf/hdf5lib/structs/H5FD_hdfs_fapl_t.java +++ b/java/src/hdf/hdf5lib/structs/H5FD_hdfs_fapl_t.java @@ -1,15 +1,14 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * Read-Only HDFS Virtual File Driver (VFD) * - * Copyright (c) 2018, The HDF Group. * + * Copyright by The HDF Group. * * * * All rights reserved. * * * - * NOTICE: * - * All information contained herein is, and remains, the property of The HDF * - * Group. The intellectual and technical concepts contained herein are * - * proprietary to The HDF Group. Dissemination of this information or * - * reproduction of this material is strictly forbidden unless prior written * - * permission is obtained from The HDF Group. * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ package hdf.hdf5lib.structs; diff --git a/java/src/hdf/hdf5lib/structs/H5FD_ros3_fapl_t.java b/java/src/hdf/hdf5lib/structs/H5FD_ros3_fapl_t.java index 39f5424..ad02979 100644 --- a/java/src/hdf/hdf5lib/structs/H5FD_ros3_fapl_t.java +++ b/java/src/hdf/hdf5lib/structs/H5FD_ros3_fapl_t.java @@ -1,15 +1,14 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * Read-Only S3 Virtual File Driver (VFD) * - * Copyright (c) 2017-2018, The HDF Group. * + * Copyright by The HDF Group. * * * * All rights reserved. * * * - * NOTICE: * - * All information contained herein is, and remains, the property of The HDF * - * Group. The intellectual and technical concepts contained herein are * - * proprietary to The HDF Group. Dissemination of this information or * - * reproduction of this material is strictly forbidden unless prior written * - * permission is obtained from The HDF Group. * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ package hdf.hdf5lib.structs; diff --git a/java/src/jni/h5Constants.c b/java/src/jni/h5Constants.c index 7354e95..bdffdbd 100644 --- a/java/src/jni/h5Constants.c +++ b/java/src/jni/h5Constants.c @@ -26,8 +26,8 @@ extern "C" { #include <stdlib.h> #include "h5jni.h" -H5_GCC_DIAG_OFF("missing-prototypes") -H5_GCC_DIAG_OFF("unused-parameter") +H5_GCC_CLANG_DIAG_OFF("missing-prototypes") +H5_GCC_CLANG_DIAG_OFF("unused-parameter") JNIEXPORT jlong JNICALL Java_hdf_hdf5lib_HDF5Constants_H5_1QUARTER_1HADDR_1MAX(JNIEnv *env, jclass cls) @@ -1212,7 +1212,7 @@ Java_hdf_hdf5lib_HDF5Constants_H5ES_1STATUS_1FAIL(JNIEnv *env, jclass cls) } /* Java does not have unsigned native types */ -H5_GCC_DIAG_OFF("sign-conversion") +H5_GCC_CLANG_DIAG_OFF("sign-conversion") JNIEXPORT jint JNICALL Java_hdf_hdf5lib_HDF5Constants_H5F_1ACC_1CREAT(JNIEnv *env, jclass cls) { @@ -1253,7 +1253,7 @@ Java_hdf_hdf5lib_HDF5Constants_H5F_1ACC_1SWMR_1WRITE(JNIEnv *env, jclass cls) { return H5F_ACC_SWMR_WRITE; } -H5_GCC_DIAG_ON("sign-conversion") +H5_GCC_CLANG_DIAG_ON("sign-conversion") JNIEXPORT jint JNICALL Java_hdf_hdf5lib_HDF5Constants_H5F_1CLOSE_1DEFAULT(JNIEnv *env, jclass cls) @@ -3724,8 +3724,8 @@ Java_hdf_hdf5lib_HDF5Constants_H5Z_1FILTER_1ALL(JNIEnv *env, jclass cls) return H5Z_FILTER_ALL; } -H5_GCC_DIAG_ON("missing-prototypes") -H5_GCC_DIAG_ON("unused-parameter") +H5_GCC_CLANG_DIAG_ON("missing-prototypes") +H5_GCC_CLANG_DIAG_ON("unused-parameter") #ifdef __cplusplus } /* end extern "C" */ diff --git a/java/src/jni/h5util.c b/java/src/jni/h5util.c index 8021438..4272205 100644 --- a/java/src/jni/h5util.c +++ b/java/src/jni/h5util.c @@ -870,11 +870,8 @@ h5str_sprintf(JNIEnv *env, h5str_t *out_str, hid_t container, hid_t tid, void *i } else { if (typeSize > 0) { - if (NULL == (this_str = (char *)HDmalloc(typeSize + 1))) + if (NULL == (this_str = HDstrdup(tmp_str))) H5_OUT_OF_MEMORY_ERROR(ENVONLY, "h5str_sprintf: failed to allocate string buffer"); - - HDstrncpy(this_str, tmp_str, typeSize); - this_str[typeSize] = '\0'; } } @@ -3664,19 +3661,14 @@ obj_info_all(hid_t loc_id, const char *name, const H5L_info2_t *info, void *op_d info_all_t *datainfo = (info_all_t *)op_data; H5O_info2_t object_info; htri_t object_exists; - size_t str_len; datainfo->otype[datainfo->count] = -1; datainfo->ltype[datainfo->count] = -1; datainfo->obj_token[datainfo->count] = H5O_TOKEN_UNDEF; - str_len = HDstrlen(name); - if (NULL == (datainfo->objname[datainfo->count] = (char *)HDmalloc(str_len + 1))) + if (NULL == (datainfo->objname[datainfo->count] = HDstrdup(name))) goto done; - HDstrncpy(datainfo->objname[datainfo->count], name, str_len); - (datainfo->objname[datainfo->count])[str_len] = '\0'; - if ((object_exists = H5Oexists_by_name(loc_id, name, H5P_DEFAULT)) < 0) goto done; @@ -3702,7 +3694,6 @@ obj_info_max(hid_t loc_id, const char *name, const H5L_info2_t *info, void *op_d { info_all_t *datainfo = (info_all_t *)op_data; H5O_info2_t object_info; - size_t str_len; datainfo->otype[datainfo->count] = -1; datainfo->ltype[datainfo->count] = -1; @@ -3710,13 +3701,9 @@ obj_info_max(hid_t loc_id, const char *name, const H5L_info2_t *info, void *op_d datainfo->obj_token[datainfo->count] = H5O_TOKEN_UNDEF; /* This will be freed by h5str_array_free(oName, n) */ - str_len = HDstrlen(name); - if (NULL == (datainfo->objname[datainfo->count] = (char *)HDmalloc(str_len + 1))) + if (NULL == (datainfo->objname[datainfo->count] = HDstrdup(name))) goto done; - HDstrncpy(datainfo->objname[datainfo->count], name, str_len); - (datainfo->objname[datainfo->count])[str_len] = '\0'; - if (H5Oget_info3(loc_id, &object_info, H5O_INFO_ALL) < 0) goto done; diff --git a/java/test/TestH5Pfapl.java b/java/test/TestH5Pfapl.java index 06eb191..7d96aec 100644 --- a/java/test/TestH5Pfapl.java +++ b/java/test/TestH5Pfapl.java @@ -104,7 +104,7 @@ public class TestH5Pfapl { for(int indx = 0; ;indx++) { java.text.DecimalFormat myFormat = new java.text.DecimalFormat("00000"); try { - file = new File("test"+myFormat.format(new Integer(indx))+".h5"); + file = new File("test"+myFormat.format(Integer.valueOf(indx))+".h5"); } catch (Throwable err) {} diff --git a/release_docs/INSTALL_CMake.txt b/release_docs/INSTALL_CMake.txt index 5d11957..91eb593 100644 --- a/release_docs/INSTALL_CMake.txt +++ b/release_docs/INSTALL_CMake.txt @@ -740,6 +740,7 @@ HDF5_BUILD_FORTRAN "Build FORTRAN support" OFF HDF5_BUILD_JAVA "Build JAVA support" OFF HDF5_BUILD_HL_LIB "Build HIGH Level HDF5 Library" ON HDF5_BUILD_TOOLS "Build HDF5 Tools" ON +HDF5_BUILD_HL_TOOLS "Build HIGH Level HDF5 Tools" ON ---------------- HDF5 Advanced Options --------------------- ONLY_SHARED_LIBS "Only Build Shared Libraries" OFF diff --git a/release_docs/README_HDF5_CMake b/release_docs/README_HDF5_CMake index c63eaca..c575320 100644 --- a/release_docs/README_HDF5_CMake +++ b/release_docs/README_HDF5_CMake @@ -10,7 +10,7 @@ This tar file contains LIBAEC.tar.gz source for building SZIP replacement ZLib.tar.gz source for building ZLIB hdf5_plugins.tar.gz source for building compression plugins - HDF5Examples-1.14.3-Source.tar.gz source for building examples + HDF5Examples-1.14.4-Source.tar.gz source for building examples For more information about building HDF5 with CMake, see USING_HDF5_CMake.txt in hdf5-1.13.0/release_docs, or diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt index 86074d0..6043145 100644 --- a/release_docs/RELEASE.txt +++ b/release_docs/RELEASE.txt @@ -49,6 +49,14 @@ New Features Configuration: ------------- + - Added new option to control the build of High-Level tools + that default ON/enabled. + + Add configure options (autotools - CMake): + enable-hltools HDF5_BUILD_HL_TOOLS + + (ADB - 2021/09/16, HDFFV-11266) + - Adds C++ Autotools configuration file for Intel * Checks for icpc as the compiler @@ -463,6 +471,31 @@ New Features Library: -------- + - Adds new "ctl" callback to VFD H5FD_class_t structure + with the following prototype: + + herr_t (*ctl)(H5FD_t *file, uint64_t op_code, + uint64_t flags, const void *input, + void **output); + + This newly-added "ctl" callback allows Virtual File + Drivers to intercept and handle arbitary operations + identified by an operation code. Its parameters are + as follows: + + `file` [in] - A pointer to the file to be operated on + `op_code` [in] - The operation code identifying the + operation to be performed + `flags` [in] - Flags governing the behavior of the + operation performed (see H5FDpublic.h + for a list of valid flags) + `input` [in] - A pointer to arguments passed to the + VFD performing the operation + `output` [out] - A pointer for the receiving VFD to + use for output from the operation + + (JRM - 2021/08/16) + - Change how the release part of version, in major.minor.release is checked for compatibility @@ -745,7 +778,6 @@ New Features Fortran Library: ---------------- - - H5Fget_name_f fixed to handle correctly trailing whitespaces and newly allocated buffers. @@ -908,7 +940,13 @@ New Features High-Level APIs: ---------------- - - + - added set/get for unsigned long long attributes + + the attribute writing high-level API has been expanded to include + public set/get functions for ULL attributes, analogously to the + existing set/get for other types. + + (AF - 2021/09/08) C Packet Table API: ------------------- @@ -930,6 +968,17 @@ Bug Fixes since HDF5-1.12.0 release =================================== Library ------- + - Detection of simple data transform function "x" + + In the case of the simple data transform function "x" the (parallel) + library recognizes this is the same as not applying this data transform + function. This improves the I/O performance. In the case of the parallel + library, it also avoids breaking to independent I/O, which makes it + possible to apply a filter when writing or reading data to or from + teh HDF5 file. + + (JWSB - 2021/09/13) + - Fixed an invalid read and memory leak when parsing corrupt file space info messages @@ -1123,6 +1172,14 @@ Bug Fixes since HDF5-1.12.0 release Configuration ------------- + - Corrected pkg-config compile script + + It was discovered that the position of the "$@" argument for the command + in the compile script may fail on some platforms and configurations. The + position of the "$@"command argument was moved before the pkg-config sub command. + + (ADB - 2021/08/30) + - Fixed CMake C++ compiler flags A recent refactoring of the C++ configure files accidently removed the diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index dbd2c62..f326c4c 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -1400,36 +1400,6 @@ endif () # Option to build documentation #----------------------------------------------------------------------------- if (DOXYGEN_FOUND) - set (DOXYGEN_PACKAGE ${HDF5_PACKAGE_NAME}) - set (DOXYGEN_VERSION_STRING ${HDF5_PACKAGE_VERSION_STRING}) - set (DOXYGEN_INCLUDE_ALIASES_PATH ${HDF5_DOXYGEN_DIR}) - set (DOXYGEN_INCLUDE_ALIASES aliases) - set (DOXYGEN_VERBATIM_VARS DOXYGEN_INCLUDE_ALIASES) - set (DOXYGEN_PROJECT_LOGO ${HDF5_DOXYGEN_DIR}/img/HDFG-logo.png) - set (DOXYGEN_PROJECT_BRIEF "C-API Reference") - set (DOXYGEN_INPUT_DIRECTORY "${HDF5_SRC_DIR} ${HDF5_DOXYGEN_DIR}/dox ${HDF5_GENERATED_SOURCE_DIR}") - set (DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) - set (DOXYGEN_MACRO_EXPANSION YES) - set (DOXYGEN_OUTPUT_DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs) - set (DOXYGEN_EXAMPLES_DIRECTORY "${HDF5_DOXYGEN_DIR}/examples ${HDF5_SRC_DIR} ${HDF5_SOURCE_DIR}/examples ${HDF5_TEST_SRC_DIR}") - set (DOXYGEN_LAYOUT_FILE ${HDF5_DOXYGEN_DIR}/hdf5doxy_layout.xml) - set (DOXYGEN_HTML_HEADER ${HDF5_DOXYGEN_DIR}/hdf5_header.html) - set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html) - set (DOXYGEN_HTML_EXTRA_STYLESHEET ${HDF5_DOXYGEN_DIR}/hdf5doxy.css) - set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png") - set (DOXYGEN_SERVER_BASED_SEARCH NO) - set (DOXYGEN_EXTERNAL_SEARCH NO) - set (DOXYGEN_SEARCHENGINE_URL) - -# This configure and custom target work together - # Replace variables inside @@ with the current values - configure_file (${HDF5_DOXYGEN_DIR}/Doxyfile.in ${HDF5_BINARY_DIR}/Doxyfile @ONLY) - add_custom_target (hdf5lib_doc ALL - COMMAND ${DOXYGEN_EXECUTABLE} ${HDF5_BINARY_DIR}/Doxyfile - DEPENDS ${HDF5_GENERATED_SOURCE_DIR}/H5Tinit.c ${HDF5_SRC_BINARY_DIR}/H5lib_settings.c - WORKING_DIRECTORY ${HDF5_SRC_DIR} - COMMENT "Generating HDF5 library Source API documentation with Doxygen" - VERBATIM ) # This cmake function requires that the non-default doxyfile settings are provided with set (DOXYGEN_xxx) commands # In addition the doxyfile aliases @INCLUDE option is not supported and would need to be provided in a set (DOXYGEN_ALIASES) command. # doxygen_add_docs (hdf5lib_doc @@ -1439,11 +1409,15 @@ if (DOXYGEN_FOUND) # WORKING_DIRECTORY ${HDF5_SRC_DIR} # COMMENT "Generating HDF5 library Source Documentation" # ) - install ( - DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs/html - DESTINATION ${HDF5_INSTALL_DATA_DIR} - COMPONENT Documents - ) + +# This custom target and doxygen/configure work together + # Replace variables inside @@ with the current values + add_custom_target (hdf5lib_doc ALL + COMMAND ${DOXYGEN_EXECUTABLE} ${HDF5_BINARY_DIR}/Doxyfile + DEPENDS ${HDF5_GENERATED_SOURCE_DIR}/H5Tinit.c ${HDF5_SRC_BINARY_DIR}/H5lib_settings.c + WORKING_DIRECTORY ${HDF5_SRC_DIR} + COMMENT "Generating HDF5 library Source API documentation with Doxygen" + VERBATIM ) if (NOT TARGET doxygen) add_custom_target (doxygen) diff --git a/src/H5Amodule.h b/src/H5Amodule.h index c89c93f..9f86ddd 100644 --- a/src/H5Amodule.h +++ b/src/H5Amodule.h @@ -33,33 +33,29 @@ * * Use the functions in this module to manage HDF5 attributes. * - * The Attribute Interface, H5A, provides a mechanism for attaching additional - * information to a dataset, group, or named datatype. - * - * Attributes are accessed by opening the object that they are attached to and - * are not independent objects. Typically an attribute is small in size and - * contains user metadata about the object that it is attached to. - * - * Attributes look similar to HDF5 datasets in that they have a datatype and - * dataspace. However, they do not support partial I/O operations and cannot be - * compressed or extended. + * Like HDF5 datasets, HDF5 attributes are array variables which have an element + * datatype and a shape (dataspace). However, they perform a different function: + * Attributes decorate other HDF5 objects, and are typically used to + * represent application metadata. Unlike datasets, the HDF5 library does not + * support partial I/O operations for attributes and they cannot be compressed + * or extended. * * <table> * <tr><th>Create</th><th>Read</th></tr> * <tr valign="top"> * <td> - * \snippet H5A_examples.c create + * \snippet{lineno} H5A_examples.c create * </td> * <td> - * \snippet H5A_examples.c read + * \snippet{lineno} H5A_examples.c read * </td> * <tr><th>Update</th><th>Delete</th></tr> * <tr valign="top"> * <td> - * \snippet H5A_examples.c update + * \snippet{lineno} H5A_examples.c update * </td> * <td> - * \snippet H5A_examples.c delete + * \snippet{lineno} H5A_examples.c delete * </td> * </tr> * </table> diff --git a/src/H5Apublic.h b/src/H5Apublic.h index b3da77f..b78ae05 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -78,11 +78,11 @@ extern "C" { * * \return \herr_t * - * \details H5Aclose() terminates access to the attribute specified by - * \p attr_id by releasing the identifier. + * \details H5Aclose() terminates access to the attribute through + * \p attr_id and releases the identifier. * - * \attention Further use of a released attribute identifier is illegal; a - * function using such an identifier will generate an error. + * \par Example + * \snippet H5A_examples.c create * * \since 1.0.0 * @@ -117,27 +117,19 @@ H5_DLL herr_t H5Aclose_async(const char *app_file, const char *app_func, unsigne * The attribute name, \p attr_name, must be unique for the object. * * The attribute is created with the specified datatype and dataspace, - * \p type_id and \p space_id, which are created with the H5T and - * H5S interfaces, respectively. + * \p type_id and \p space_id. * - * If \p type_id is either a fixed-length or variable-length string, - * it is important to set the string length when defining the - * datatype. String datatypes are derived from #H5T_C_S1 (or - * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in - * size. See H5Tset_size() and Creating variable-length string - * datatypes. - * - * The access property list is currently unused, but will be used in - * the future. This property list should currently be #H5P_DEFAULT. + * \plist_unused{acpl} * * The attribute identifier returned by this function must be released * with H5Aclose() resource leaks will develop. * - * \note The \p aapl parameter is currently not used; specify #H5P_DEFAULT. - * * \note If \p loc_id is a file identifier, the attribute will be attached * that file’s root group. * + * \par Example + * \snippet H5A_examples.c create + * * \since 1.8.0 * * \see H5Aclose() @@ -175,28 +167,19 @@ H5_DLL hid_t H5Acreate_async(const char *app_file, const char *app_func, unsigne * attached to the object specified by \p loc_id and \p obj_name. * * \p loc_id is a location identifier; \p obj_name is the object - * name relative to \p loc_id. If \p loc_id fully specifies the - * object to which the attribute is to be attached, \p obj_name - * should be '.' (a dot). + * name relative to \p loc_id. * * The attribute name, \p attr_name, must be unique for the object. * * The attribute is created with the specified datatype and - * dataspace, \p type_id and \p space_id, which are created with - * the H5T and H5S interfaces respectively. + * dataspace, \p type_id and \p space_id. * - * The attribute creation and access property lists are currently - * unused, but will be used in the future for optional attribute - * creation and access properties. These property lists should - * currently be #H5P_DEFAULT. + * \plist_unused{aapl} * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access * the object, \p obj_name. * - * The attribute identifier returned by this function must be - * released with H5close() or resource leaks will develop. - * * \since 1.8.0 * */ @@ -224,10 +207,14 @@ H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func, * * \details H5Adelete() removes the attribute specified by its name, * \p attr_name, from a file, dataset, group, or named datatype. - * This function should not be used when attribute identifiers - * are open on \p loc_id as it may cause the internal indexes of - * the attributes to change and future writes to the open - * attributes to produce incorrect results. + * + * \attention This function should not be used when other attribute identifiers + * are open on \p loc_id. This may cause the internal indexes of + * the attributes to change and future writes to the open + * attributes to produce incorrect results. + * + * \par Example + * \snippet H5A_examples.c delete * * \since 1.0.0 * @@ -254,27 +241,16 @@ H5_DLL herr_t H5Adelete(hid_t loc_id, const char *attr_name); * * The object from which the attribute is to be removed is * specified by a location identifier and name, \p loc_id and - * \p obj_name, respectively. If \p loc_id fully specifies the - * object from which the attribute is to be removed, \p obj_name - * should be '.' (a dot). + * \p obj_name, respectively. * * The attribute to be removed is specified by a position in an - * index, \p n. The type of index is specified by \p idx_type and - * may be #H5_INDEX_NAME, for an alpha-numeric index by name, or - * #H5_INDEX_CRT_ORDER, for an index by creation order. The order - * in which the index is to be traversed is specified by \p order - * and may be #H5_ITER_INC (increment) for top-down iteration, - * #H5_ITER_DEC (decrement) for bottom-up iteration, or - * #H5_ITER_NATIVE, in which case HDF5 will iterate in the - * fastest-available order. For example, if \p idx_type, \p order, + * index, \p n. The type of index is specified by \p idx_type. + * The order in which the index is to be traversed is specified by + * \p order. For example, if \p idx_type, \p order, * and \p n are set to #H5_INDEX_NAME, #H5_ITER_INC, and 5, - * respectively, the fifth attribute by alpha-numeric order of + * respectively, the fifth attribute in lexicographic order of * attribute names will be removed. * - * For a discussion of \p idx_type and \p order, the valid values - * of those parameters, and the use of \p n, see the description - * of H5Aiterate2(). - * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access * the object, \p obj_name. @@ -302,9 +278,6 @@ H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t id * from an object specified by location and name, \p loc_id and * \p obj_name, respectively. * - * If \p loc_id fully specifies the object from which the - * attribute is to be removed, \p obj_name should be '.' (a dot). - * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to * access the object, \p obj_name. @@ -360,9 +333,7 @@ H5_DLL herr_t H5Aexists_async(const char *app_file, const char *app_func, unsign * \p loc_id specifies a location in the file containing the object. * \p obj_name is the name of the object to which the attribute is * attached and can be a relative name, relative to \p loc_id, - * or an absolute name, based in the root group of the file. If - * \p loc_id fully specifies the object, \p obj_name should be '.' - * (a dot). + * or an absolute name, based in the root group of the file. * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -394,9 +365,6 @@ H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func * creation property list associated with the attribute specified * by \p attr_id. * - * The creation property list identifier should be released with - * H5Pclose(). - * * \since 1.8.0 * */ @@ -413,32 +381,9 @@ H5_DLL hid_t H5Aget_create_plist(hid_t attr_id); * \return \herr_t * * \details H5Aget_info() retrieves attribute information, locating the - * attribute with an attribute identifier, \p attr_id, which is - * the identifier returned by H5Aopen() or H5Aopen_by_idx(). The + * attribute with an attribute identifier, \p attr_id. The * attribute information is returned in the \p ainfo struct. * - * The \p ainfo struct is defined as follows: - * \snippet this H5A_info_t_snip - * - * \p corder_valid indicates whether the creation order data is - * valid for this attribute. Note that if creation order is not - * being tracked, no creation order data will be valid. Valid - * values are \c TRUE and \c FALSE. - * - * \p corder is a positive integer containing the creation - * order of the attribute. This value is 0-based, so, for - * example, the third attribute created will have a \p corder - * value of 2. - * - * \p cset indicates the character set used for the attribute’s - * name; valid values are defined in H5Tpublic.h and include - * the following: - * \csets - * This value is set with H5Pset_char_encoding(). - * - * \p data_size indicates the size, in the number of characters, - * of the attribute. - * * \since 1.8.0 * */ @@ -466,16 +411,9 @@ H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/); * The attribute is located by its index position and the attribute * information is returned in the \p ainfo struct. * - * If \p loc_id fully specifies the object to which the attribute - * is attached, \p obj_name should be '.' (a dot). - * * The attribute is located by means of an index type, an index * traversal order, and a position in the index, \p idx_type, - * \p order and \p n, respectively. These parameters and their - * valid values are discussed in the description of H5Aiterate2(). - * - * The \p ainfo struct, which will contain the returned attribute - * information, is described in H5Aget_info(). + * \p order and \p n, respectively. * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -493,8 +431,7 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t * \brief Retrieves attribute information, by attribute name * * \fgdt_loc_id - * - * \param[in] obj_name Name of object to which attribute is attached, + * \param[in] obj_name Name of the object to which an attribute is attached, * relative to location * \param[in] attr_name Attribute name * \param[out] ainfo Struct containing returned attribute information @@ -507,11 +444,6 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t * location and name, \p loc_id and \p obj_name, respectively. * The attribute information is returned in the \p ainfo struct. * - * If \p loc_id fully specifies the object to which the attribute - * is attached, \p obj_name should be '.' (a dot). - * - * The \p ainfo struct is described in H5Aget_info(). - * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to * access the object, \p obj_name. @@ -542,8 +474,8 @@ H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char * string terminator is stored in the last position of the buffer * to properly terminate the string. * - * If the user only wants to find out the size of this name, the - * values 0 and NULL can be passed in for the parameters + * If the user only wants to retrieve the name length, the + * values 0 and NULL should be passed for the parameters * \p bufsize and \p buf. * * \since 1.0.0 @@ -554,7 +486,7 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf); /** * \ingroup H5A * - * \brief Gets an attribute name, by attribute index position + * \brief Gets an attribute name by attribute index position * * \fgdt_loc_id * \param[in] obj_name Name of object to which attribute is attached, @@ -575,13 +507,9 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf); * located by its index position, the size of the name is specified * in \p size, and the attribute name is returned in \p name. * - * If \p loc_id fully specifies the object to which the attribute - * is attached, \p obj_name should be '.' (a dot). - * * The attribute is located by means of an index type, an index * traversal order, and a position in the index, \p idx_type, - * \p order and \p n, respectively. These parameters and their - * valid values are discussed in the description of H5Aiterate2(). + * \p order and \p n, respectively. * * If the attribute name’s size is unknown, the values 0 and NULL * can be passed in for the parameters \p size and \p name. The @@ -621,7 +549,7 @@ H5_DLL hid_t H5Aget_space(hid_t attr_id); /** * \ingroup H5A * - * \brief Returns the amount of storage required for an attribute + * \brief Returns the amount of storage used to store an attribute * * \attr_id * @@ -639,17 +567,16 @@ H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id); /** * \ingroup H5A * - * \brief Gets an attribute datatype + * \brief Gets an attribute's datatype * * \attr_id * * \return \hid_t{datatype} * - * \details H5Aget_type() retrieves a copy of the datatype for an attribute. + * \details H5Aget_type() retrieves a copy of the attribute's datatype. * The datatype is reopened if it is a named type before returning * it to the application. The datatypes returned by this function - * are always read-only. If an error occurs when atomizing the - * return datatype, then the datatype is closed. + * are always read-only. * * The datatype identifier returned from this function must be * released with H5Tclose() or resource leaks will develop. @@ -662,7 +589,7 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); /** * \ingroup H5A * - * \brief Calls user-defined function for each attribute on an object + * \brief Calls a user-defined function for each attribute on an object * * \fgdt_loc_id * \param[in] idx_type Type of index @@ -689,17 +616,6 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); * are specified by three parameters: the index type, * \p idx_type; the order in which the index is to be traversed, * \p order; and the attribute’s position in the index, \p idx. - * - * The type of index specified by \p idx_type can be one of the - * following: - * - * \indexes - * - * The order in which the index is to be traversed, as specified - * by \p order, can be one of the following: - * - * \orders - * * The next attribute to be operated on is specified by \p idx, * a position in the index. * @@ -716,11 +632,6 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); * the value returned identifies the parameter to be operated on * in the next step of the iteration. * - * \p op is a user-defined function whose prototype is defined - * as follows: - * \snippet this H5A_operator2_t_snip - * \click4more - * * \note This function is also available through the H5Aiterate() macro. * * \since 1.8.0 @@ -756,24 +667,10 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord * additional information as defined below, is passed to a * user-defined function, \p op, which operates on that attribute. * - * If \p loc_id fully specifies the object to which these - * attributes are attached, \p obj_name should be '.' (a dot). - * * The order of the iteration and the attributes iterated over * are specified by three parameters: the index type, \p idx_type; * the order in which the index is to be traversed, \p order; * and the attribute’s position in the index, \p idx. - * - * The type of index specified by \p idx_type can be one of the - * following: - * - * \indexes - * - * The order in which the index is to be traversed, as specified - * by \p order, can be one of the following: - * - * \orders - * * The next attribute to be operated on is specified by \p idx, * a position in the index. * @@ -790,25 +687,6 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord * the value returned identifies the parameter to be operated on in * the next step of the iteration. * - * \p op is a user-defined function whose prototype is defined - * as follows: - * \snippet this H5A_operator2_t_snip - * \click4more - * - * Valid return values from an operator and the resulting - * H5Aiterate_by_name() and \p op behavior are as follows: - * - * \li Zero causes the iterator to continue, returning zero when - * all attributes have been processed. - * \li A positive value causes the iterator to immediately return - * that positive value, indicating short-circuit success. - * The iterator can be restarted at the next attribute, as - * indicated by the return value of \p idx. - * \li A negative value causes the iterator to immediately return - * that value, indicating failure. The iterator can be - * restarted at the next attribute, as indicated by the return - * value of \p idx. - * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access * the object, \p obj_name. @@ -835,8 +713,7 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t * \details H5Aopen() opens an existing attribute, \p attr_name, that is * attached to object specified by an object identifier, \p obj_id. * - * The attribute access property list, \p aapl_id, is currently unused - * and should be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called * before the attribute can be accessed for any further purpose, @@ -845,6 +722,9 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t * The attribute identifier returned by this function must be released * with H5Aclose() or resource leaks will develop. * + * \par Example + * \snippet H5A_examples.c read + * * \since 1.8.0 * * \see H5Aclose(), H5Acreate() @@ -876,17 +756,13 @@ H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned * * \details H5Aopen_by_idx() opens an existing attribute that is attached * to an object specified by location and name, \p loc_id and - * \p obj_name, respectively. If \p loc_id fully specifies the - * object to which the attribute is attached, \p obj_name, should - * be '.' (a dot). + * \p obj_name, respectively. * * The attribute is identified by an index type, an index traversal * order, and a position in the index, \p idx_type, \p order and - * \p n, respectively. These parameters and their valid values are - * discussed in the description of H5Aiterate2(). + * \p n, respectively. * - * The attribute access property list, \p aapl_id, is currently - * unused and should currently be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -933,11 +809,9 @@ H5_DLL hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, un * * \p loc_id specifies a location from which the target object can * be located and \p obj_name is an object name relative to - * \p loc_id. If \p loc_id fully specifies the object to which the - * attribute is attached, \p obj_name should be '.' (a dot). + * \p loc_id. * - * The attribute access property list, \p aapl_id, is currently - * unused and should currently be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -982,6 +856,9 @@ H5_DLL hid_t H5Aopen_by_name_async(const char *app_file, const char *app_func, u * Datatype conversion takes place at the time of a read or write and * is automatic. * + * \par Example + * \snippet H5A_examples.c read + * * \version 1.8.8 Fortran updated to Fortran2003. * \version 1.4.2 The \p dims parameter was added to the Fortran API in this * release. @@ -1051,15 +928,12 @@ H5_DLL herr_t H5Arename_by_name_async(const char *app_file, const char *app_func * attribute's in-memory datatype is specified with \p type_id. * The entire attribute is written from \p buf to the file. * - * If \p type_id is either a fixed-length or variable-length string, - * it is important to set the string length when defining the datatype. - * String datatypes are derived from #H5T_C_S1 (or #H5T_FORTRAN_S1 for - * Fortran codes), which defaults to 1 character in size. - * See H5Tset_size() and Creating variable-length string datatypes. - * * Datatype conversion takes place at the time of a read or write and * is automatic. * + * \par Example + * \snippet H5A_examples.c update + * * \version 1.8.8 Fortran updated to Fortran2003. * \version 1.4.2 Fortran \p dims parameter added in this release * \since 1.0.0 @@ -1100,6 +974,7 @@ H5_DLL herr_t H5Awrite_async(const char *app_file, const char *app_func, unsigne H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char *old_attr_name, const char *new_attr_name, hid_t lapl_id); +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -1133,6 +1008,7 @@ H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char * #define H5Aexists_by_name_async_wrap H5_NO_EXPAND(H5Aexists_by_name_async) #define H5Aclose_async_wrap H5_NO_EXPAND(H5Aclose_async) #endif /* H5A_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * @@ -1182,9 +1058,9 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam * * \return \hid_tv{attribute} * - * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT. + * \deprecation_note{H5Acreate2()} * - * \deprecated Deprecated in favor of H5Acreate2() + * \plist_unused{acpl} * * \details H5Acreate1() creates an attribute, \p name, which is attached * to the object specified by the identifier \p loc_id. @@ -1192,18 +1068,7 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam * The attribute name, \p name, must be unique for the object. * * The attribute is created with the specified datatype and dataspace, - * \p type_id and \p space_id, which are created with the H5T and - * H5S interfaces, respectively. - * - * If \p type_id is either a fixed-length or variable-length string, - * it is important to set the string length when defining the - * datatype. String datatypes are derived from #H5T_C_S1 (or - * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in - * size. See H5Tset_size() and Creating variable-length string - * datatypes. - * - * The attribute identifier returned by this function must be released - * with H5Aclose() resource leaks will develop. + * \p type_id and \p space_id. * * \since 1.8.0 * @@ -1225,8 +1090,7 @@ H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa * \return Returns the number of attributes if successful; otherwise returns * a negative value. * - * \deprecated This function is deprecated in favor of the functions - * H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx(). + * \deprecation_note{H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx()} * * \details H5Aget_num_attrs() returns the number of attributes attached to * the object specified by its identifier, \p loc_id. @@ -1249,8 +1113,7 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id); * * \return \herr_t * - * \deprecated This function is deprecated in favor of the function - * H5Aiterate2(). + * \deprecation_note{H5Aiterate2()} * * \details H5Aiterate1() iterates over the attributes of the object * specified by its identifier, \p loc_id. The object can be a @@ -1262,10 +1125,6 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id); * \p op, is returned in \p idx. If \p idx is the null pointer, * then all attributes are processed. * - * \p op is a user-defined function whose prototype is defined as follows: - * \snippet this H5A_operator1_t_snip - * \click4more - * * \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1() * and deprecated in this release. * \since 1.0.0 @@ -1283,8 +1142,7 @@ H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *idx, H5A_operator1_t op, void * * \return \hid_tv{attribute} * - * \deprecated This function is deprecated in favor of the function - * H5Aopen_by_idx(). + * \deprecation_note{H5Aopen_by_idx()} * * \details H5Aopen_idx() opens an attribute which is attached to the * object specified with \p loc_id . The location object may be @@ -1310,8 +1168,7 @@ H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx); * * \return \hid_tv{attribute} * - * \deprecated This function is deprecated in favor of the function - * H5Aopen_by_name(). + * \deprecation_note{H5Aopen_by_name()} * * \details H5Aopen_name() opens an attribute specified by its name, * \p name, which is attached to the object specified with diff --git a/src/H5Dio.c b/src/H5Dio.c index d1861c4..6bd4666 100644 --- a/src/H5Dio.c +++ b/src/H5Dio.c @@ -856,28 +856,40 @@ H5D__ioinfo_adjust(H5D_io_info_t *io_info, const H5D_t *dset, const H5S_t *file_ for (cause = 1, idx = 0; (cause < H5D_MPIO_NO_COLLECTIVE_MAX_CAUSE) && (idx < cause_strings_len); cause <<= 1, idx++) { - size_t cause_strlen = HDstrlen(cause_strings[idx]); - if (cause & local_no_collective_cause) { + size_t local_buffer_space = sizeof(local_no_collective_cause_string) - + HDstrlen(local_no_collective_cause_string) - 1; + /* Check if there were any previous error messages included. If so, prepend a * semicolon to separate the messages. */ - if (local_error_message_previously_written) - HDstrncat(local_no_collective_cause_string, "; ", 2); + if (local_buffer_space && local_error_message_previously_written) { + HDstrncat(local_no_collective_cause_string, "; ", local_buffer_space); + local_buffer_space -= MIN(local_buffer_space, 2); + } - HDstrncat(local_no_collective_cause_string, cause_strings[idx], cause_strlen); + if (local_buffer_space) + HDstrncat(local_no_collective_cause_string, cause_strings[idx], + local_buffer_space); local_error_message_previously_written = TRUE; } /* end if */ if (cause & global_no_collective_cause) { + size_t global_buffer_space = sizeof(global_no_collective_cause_string) - + HDstrlen(global_no_collective_cause_string) - 1; + /* Check if there were any previous error messages included. If so, prepend a * semicolon to separate the messages. */ - if (global_error_message_previously_written) - HDstrncat(global_no_collective_cause_string, "; ", 2); - - HDstrncat(global_no_collective_cause_string, cause_strings[idx], cause_strlen); + if (global_buffer_space && global_error_message_previously_written) { + HDstrncat(global_no_collective_cause_string, "; ", global_buffer_space); + global_buffer_space -= MIN(global_buffer_space, 2); + } + + if (global_buffer_space) + HDstrncat(global_no_collective_cause_string, cause_strings[idx], + global_buffer_space); global_error_message_previously_written = TRUE; } /* end if */ diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h index 595c714..596fd48 100644 --- a/src/H5Dmodule.h +++ b/src/H5Dmodule.h @@ -44,18 +44,18 @@ * <tr><th>Create</th><th>Read</th></tr> * <tr valign="top"> * <td> - * \snippet H5D_examples.c create + * \snippet{lineno} H5D_examples.c create * </td> * <td> - * \snippet H5D_examples.c read + * \snippet{lineno} H5D_examples.c read * </td> * <tr><th>Update</th><th>Delete</th></tr> * <tr valign="top"> * <td> - * \snippet H5D_examples.c update + * \snippet{lineno} H5D_examples.c update * </td> * <td> - * \snippet H5D_examples.c delete + * \snippet{lineno} H5D_examples.c delete * </td> * </tr> * </table> diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index 63cc61c..c496414 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -32,7 +32,9 @@ #define H5D_CHUNK_CACHE_NBYTES_DEFAULT SIZE_MAX #define H5D_CHUNK_CACHE_W0_DEFAULT (-1.0) -/* Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts() */ +/** + * Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts() + */ #define H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS (0x0002u) /*******************/ @@ -44,13 +46,12 @@ * Values for the H5D_LAYOUT property */ typedef enum H5D_layout_t { - H5D_LAYOUT_ERROR = -1, - - H5D_COMPACT = 0, /**< raw data is very small */ - H5D_CONTIGUOUS = 1, /**< the default */ - H5D_CHUNKED = 2, /**< slow and fancy */ - H5D_VIRTUAL = 3, /**< actual data is stored in other datasets */ - H5D_NLAYOUTS = 4 /**< this one must be last! */ + H5D_LAYOUT_ERROR = -1, /**< error */ + H5D_COMPACT = 0, /**< raw data is small (< 64KB) */ + H5D_CONTIGUOUS = 1, /**< contiguous layout */ + H5D_CHUNKED = 2, /**< chunked or tiled layout */ + H5D_VIRTUAL = 3, /**< actual data is stored in other datasets */ + H5D_NLAYOUTS = 4 /**< this one must be last! */ } H5D_layout_t; //! <!-- [H5D_layout_t_snip] --> @@ -75,11 +76,11 @@ typedef enum H5D_chunk_index_t { * Values for the space allocation time property */ typedef enum H5D_alloc_time_t { - H5D_ALLOC_TIME_ERROR = -1, - H5D_ALLOC_TIME_DEFAULT = 0, - H5D_ALLOC_TIME_EARLY = 1, - H5D_ALLOC_TIME_LATE = 2, - H5D_ALLOC_TIME_INCR = 3 + H5D_ALLOC_TIME_ERROR = -1, /**< Error */ + H5D_ALLOC_TIME_DEFAULT = 0, /**< \todo Define this! */ + H5D_ALLOC_TIME_EARLY = 1, /**< Allocate on creation */ + H5D_ALLOC_TIME_LATE = 2, /**< Allocate on first write */ + H5D_ALLOC_TIME_INCR = 3 /**< Allocate incrementally (by chunk) */ } H5D_alloc_time_t; //! <!-- [H5D_alloc_time_t_snip] --> @@ -88,10 +89,11 @@ typedef enum H5D_alloc_time_t { * Values for the status of space allocation */ typedef enum H5D_space_status_t { - H5D_SPACE_STATUS_ERROR = -1, - H5D_SPACE_STATUS_NOT_ALLOCATED = 0, - H5D_SPACE_STATUS_PART_ALLOCATED = 1, - H5D_SPACE_STATUS_ALLOCATED = 2 + H5D_SPACE_STATUS_ERROR = -1, /**< Error */ + H5D_SPACE_STATUS_NOT_ALLOCATED = 0, /**< Space has not been allocated for this dataset. */ + H5D_SPACE_STATUS_PART_ALLOCATED = 1, /**< Space has been allocated for this dataset. */ + H5D_SPACE_STATUS_ALLOCATED = 2 /**< Space has been partially allocated for this dataset. (Used only for + datasets with chunked storage.) */ } H5D_space_status_t; //! <!-- [H5D_space_status_t_snip] --> @@ -100,10 +102,10 @@ typedef enum H5D_space_status_t { * Values for time of writing fill value property */ typedef enum H5D_fill_time_t { - H5D_FILL_TIME_ERROR = -1, - H5D_FILL_TIME_ALLOC = 0, - H5D_FILL_TIME_NEVER = 1, - H5D_FILL_TIME_IFSET = 2 + H5D_FILL_TIME_ERROR = -1, /**< Error */ + H5D_FILL_TIME_ALLOC = 0, /**< Fill on allocation */ + H5D_FILL_TIME_NEVER = 1, /**< Never write fill values */ + H5D_FILL_TIME_IFSET = 2 /**< Fill if fill-value was set */ } H5D_fill_time_t; //! <!-- [H5D_fill_time_t_snip] --> @@ -112,10 +114,10 @@ typedef enum H5D_fill_time_t { * Values for fill value status */ typedef enum H5D_fill_value_t { - H5D_FILL_VALUE_ERROR = -1, - H5D_FILL_VALUE_UNDEFINED = 0, - H5D_FILL_VALUE_DEFAULT = 1, - H5D_FILL_VALUE_USER_DEFINED = 2 + H5D_FILL_VALUE_ERROR = -1, /**< Error */ + H5D_FILL_VALUE_UNDEFINED = 0, /**< No fill value defined */ + H5D_FILL_VALUE_DEFAULT = 1, /**< Default fill-value */ + H5D_FILL_VALUE_USER_DEFINED = 2 /**< User-defined fill-value */ } H5D_fill_value_t; //! <!-- [H5D_fill_value_t_snip] --> @@ -124,22 +126,40 @@ typedef enum H5D_fill_value_t { * Values for VDS bounds option */ typedef enum H5D_vds_view_t { - H5D_VDS_ERROR = -1, - H5D_VDS_FIRST_MISSING = 0, - H5D_VDS_LAST_AVAILABLE = 1 + H5D_VDS_ERROR = -1, /**< Error */ + H5D_VDS_FIRST_MISSING = 0, /**< \todo Define this! */ + H5D_VDS_LAST_AVAILABLE = 1 /**< \todo Define this! */ } H5D_vds_view_t; //! <!-- [H5D_vds_view_t_snip] --> //! <!-- [H5D_append_cb_t_snip] --> /** - * Callback for H5Pset_append_flush() in a dataset access property list + * \brief Callback for H5Pset_append_flush() + * + * \dset_id{dataset_id} + * \param[in] cur_dims The current extent of the dataset's dimensions + * \param[in,out] op_data User context + * + * \return \herr_t + * */ typedef herr_t (*H5D_append_cb_t)(hid_t dataset_id, hsize_t *cur_dims, void *op_data); //! <!-- [H5D_append_cb_t_snip] --> //! <!-- [H5D_operator_t_snip] --> /** - * Define the operator function pointer for H5Diterate() + * \brief Callback for H5Diterate() + * + * \param[in,out] elem Pointer to the memory buffer containing the current dataset + * element + * \param[in] type_id Datatype identifier of the elements stored in \p elem + * \param[in] ndim Number of dimensions for the \p point array + * \param[in] point Array containing the location of the element within + * the original dataspace + * \param[in,out] operator_data Pointer to any user-defined data associated with + * the operation + * \return \herr_t_iter + * */ typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const hsize_t *point, void *operator_data); @@ -147,7 +167,29 @@ typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const //! <!-- [H5D_scatter_func_t_snip] --> /** - * Define the operator function pointer for H5Dscatter() + * \brief Callback for H5Dscatter() + * + * \param[out] src_buf Pointer to the buffer holding the next set of elements to + * scatter. On entry, the value of where \p src_buf points to + * is undefined. The callback function should set \p src_buf + * to point to the next set of elements. + * \param[out] src_buf_bytes_used Pointer to the number of valid bytes in \p src_buf. + * On entry, the value where \p src_buf_bytes_used points + * to is undefined. The callback function should set + * \p src_buf_bytes_used to the of valid bytes in \p src_buf. + * This number must be a multiple of the datatype size. + * \param[in,out] op_data User-defined pointer to data required by the callback + * function. A pass-through of the \p op_data pointer provided + * with the H5Dscatter() function call. + * \return herr_t + * + * \details The callback function should always return at least one + * element in \p src_buf, and must not return more elements + * than are remaining to be scattered. This function will be + * repeatedly called until all elements to be scattered have + * been returned. The callback function should return zero (0) + * to indicate success, and a negative value to indicate failure. + * */ typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_buf_bytes_used /*out*/, void *op_data); @@ -155,18 +197,51 @@ typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_b //! <!-- [H5D_gather_func_t_snip] --> /** - * Define the operator function pointer for H5Dgather() + * \brief Callback for H5Dgather() + * + * \param[in] dst_buf Pointer to the destination buffer which has been filled + * with the next set of elements gathered. This will always + * be identical to the \p dst_buf passed to H5Dgather() + * \param[in] dst_buf_bytes_used Pointer to the number of valid bytes in + * \p dst_buf. This number must be a multiple of + * the datatype size. + * \param[in,out] op_data User-defined pointer to data required by the callback + * function; a pass-through of the \p op_data pointer + * provided with the H5Dgather() function call. + * \returns \herr_t + * + * \details The callback function should process, store, or otherwise make use + * of the data returned in dst_buf before it returns, because the + * buffer will be overwritten unless it is the last call to the + * callback. This function will be repeatedly called until all gathered + * elements have been passed to the callback in dst_buf. The callback + * function should return zero (0) to indicate success, and a negative + * value to indicate failure. + * */ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_used, void *op_data); //! <!-- [H5D_gather_func_t_snip] --> //! <!-- [H5D_chunk_iter_op_t_snip] --> /** - * Define the operator function pointer for H5Dchunk_iter() + * \brief Callback for H5Dchunk_iter() + * + * \param[in] offset Array of starting logical coordinates of chunk. + * \param[in] filter_mask Filter mask of chunk. + * \param[in] addr Offset in file of chunk data. + * \param[in] nbytes Size in bytes of chunk data in file. + * \param[in,out] op_data Pointer to any user-defined data associated with + * the operation. + * \returns \li Zero (#H5_ITER_CONT) causes the iterator to continue, returning + * zero when all elements have been processed. + * \li A positive value (#H5_ITER_STOP) causes the iterator to + * immediately return that value, indicating short-circuit success. + * \li A negative (#H5_ITER_ERROR) causes the iterator to immediately + * return that value, indicating failure. */ -//! <!-- [H5D_chunk_iter_op_t_snip] --> typedef int (*H5D_chunk_iter_op_t)(const hsize_t *offset, uint32_t filter_mask, haddr_t addr, uint32_t nbytes, void *op_data); +//! <!-- [H5D_chunk_iter_op_t_snip] --> /********************/ /* Public Variables */ @@ -186,7 +261,7 @@ extern "C" { * \brief Creates a new dataset and links it into the file * * \fgdta_loc_id - * \param[in] name Name of the dataset to create + * \param[in] name Name of the dataset to create * \type_id * \space_id * \lcpl_id @@ -211,13 +286,6 @@ extern "C" { * \p name may be either an absolute path in the file or a relative * path from \p loc_id naming the dataset. * - * \p dtype_id specifies the datatype of each data element as stored - * in the file. If \p dtype_id is either a fixed-length or - * variable-length string, it is important to set the string length - * when defining the datatype. String datatypes are derived from - * #H5T_C_S1 (or #H5T_FORTRAN_S1 for Fortran codes), which defaults - * to 1 character in size. - * * If \p dtype_id is a committed datatype, and if the file location * associated with the committed datatype is different from the * file location where the dataset will be created, the datatype @@ -225,7 +293,7 @@ extern "C" { * * The link creation property list, \p lcpl_id, governs creation * of the link(s) by which the new dataset is accessed and the - * creation of any * intermediate groups that may be missing. + * creation of any intermediate groups that may be missing. * * The datatype and dataspace properties and the dataset creation * and access property lists are attached to the dataset, so the @@ -236,8 +304,8 @@ extern "C" { * not previously written, the HDF5 library will return default * or user-defined fill values. * - * To conserve and release resources, the dataset should be closed - * when access is no longer required. + * \par Example + * \snippet H5D_examples.c create * * \since 1.8.0 * @@ -285,34 +353,14 @@ H5_DLL hid_t H5Dcreate_async(const char *app_file, const char *app_func, unsigne * the file, which may differ from the datatype and dataspace * in application memory. * - * Dataset creation property list and dataset access creation - * property list are specified by \p dcpl_id and \p dapl_id. - * * H5Dcreate_anon() returns a new dataset identifier. Using * this identifier, the new dataset must be linked into the * HDF5 file structure with H5Olink() or it will be deleted - * from the file when the file is closed. - * - * See H5Dcreate2() for further details and considerations on - * the use of H5Dcreate2() and H5Dcreate_anon(). - * - * The differences between this function and H5Dcreate2() are - * as follows: - * \li H5Dcreate_anon() explicitly includes a dataset access property - * list. H5Dcreate() always uses default dataset access properties. - * - * \li H5Dcreate_anon() neither provides the new dataset’s name nor - * links it into the HDF5 file structure; those actions must be - * performed separately through a call to H5Olink(), which offers - * greater control over linking. - * - * A dataset created with this function should be closed with - * H5Dclose() when the dataset is no longer needed so that resource - * leaks will not develop. + * when the file is closed. * * \since 1.8.0 * - * \see H5Olink(), H5Dcreate(), Using Identifiers + * \see H5Olink(), H5Dcreate() * */ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id); @@ -338,12 +386,6 @@ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t d * specified then the dataset will be opened at the location * where the attribute, dataset, or named datatype is attached. * - * The dataset access property list, \p dapl_id, provides - * information regarding access to the dataset. - * - * To conserve and release resources, the dataset should be closed - * when access is no longer required. - * * \since 1.8.0 * * \see H5Dcreate2(), H5Dclose() @@ -377,6 +419,9 @@ H5_DLL hid_t H5Dopen_async(const char *app_file, const char *app_func, unsigned * be released with H5Sclose() when the identifier is no longer * needed so that resource leaks will not occur. * + * \par Example + * \snippet H5D_examples.c update + * * \see H5Sclose() * */ @@ -393,7 +438,19 @@ H5_DLL hid_t H5Dget_space_async(const char *app_file, const char *app_func, unsi /** * -------------------------------------------------------------------------- * \ingroup H5D - * \todo Document this function! + * + * \brief Determines whether space has been allocated for a dataset + * + * \dset_id + * \param[out] allocation Space allocation status + * + * \return \herr_t + * + * \details H5Dget_space_status() determines whether space has been allocated + * for the dataset \p dset_id. + * + * \since 1.6.0 + * */ H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation); @@ -412,27 +469,7 @@ H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation) * * If a dataset has a named datatype, then an identifier to the * opened datatype is returned. Otherwise, the returned datatype - * is read-only. If atomization of the datatype fails, then the - * datatype is closed. - * - * A datatype identifier returned from this function should be - * released with H5Tclose() when the identifier is no longer - * needed to prevent resource leaks. - * - * \note Datatype Identifiers - * - * Please note that the datatype identifier is actually an object - * identifier or a handle returned from opening the datatype. It - * is not persistent and its value can be different from one HDF5 - * session to the next. - * - * H5Tequal() can be used to compare datatypes. - * - * HDF5 High Level APIs that may also be of interest are: - * - * H5LTdtype_to_text() creates a text description of a - * datatype. H5LTtext_to_dtype() creates an HDF5 datatype - * given a text description. + * is read-only. * */ H5_DLL hid_t H5Dget_type(hid_t dset_id); @@ -452,9 +489,6 @@ H5_DLL hid_t H5Dget_type(hid_t dset_id); * a copy of the dataset creation property list associated with * the dataset specified by \p dset_id. * - * The creation property list identifier should be released - * with H5Pclose() to prevent resource leaks. - * */ H5_DLL hid_t H5Dget_create_plist(hid_t dset_id); @@ -488,10 +522,6 @@ H5_DLL hid_t H5Dget_create_plist(hid_t dset_id); * All link access properties in the returned list will be set * to the default values. * - * The access property list identifier should be released with - * H5Pclose() when the identifier is no longer needed so that - * resource leaks will not develop. - * * \since 1.8.3 * */ @@ -510,11 +540,8 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id); * \details H5Dget_storage_size() returns the amount of storage, * in bytes, that is allocated in the file for the raw data of * the dataset specified by \p dset_id. - * - * \note The amount of storage in this case is the storage - * allocated in the written file, which will typically differ - * from the space required to hold a dataset in working memory. - * + * H5Dget_storage_size() reports only the space required to store + * the dataset elements, excluding any metadata. * \li For contiguous datasets, the returned size equals the current * allocated size of the raw data. * \li For unfiltered chunked datasets, the returned size is the @@ -524,21 +551,19 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id); * compression filter is in use, H5Dget_storage_size() will return * the total space required to store the compressed chunks. * - * H5Dget_storage_size() reports only the space required to store - * the data, not including that of any metadata. + * \note Note that H5Dget_storage_size() is not generally an + * appropriate function to use when determining the amount + * of memory required to work with a dataset. In such + * circumstances, you must determine the number of data + * points in a dataset and the size of an individual dataset + * element. H5Sget_simple_extent_npoints() and H5Tget_size() + * can be used to calculate that amount. * - * \attention H5Dget_storage_size() does not differentiate between 0 (zero), + * \warning H5Dget_storage_size() does not differentiate between 0 (zero), * the value returned for the storage size of a dataset * with no stored values, and 0 (zero), the value returned to * indicate an error. * - * \note Note that H5Dget_storage_size() is not generally an - * appropriate function to use when determining the amount - * of memory required to work with a dataset. In such - * circumstances, you must determine the number of data - * points in a dataset and the size of an individual data - * element. H5Sget_simple_extent_npoints() and H5Tget_size() - * can be used to get that information. * */ H5_DLL hsize_t H5Dget_storage_size(hid_t dset_id); @@ -595,7 +620,7 @@ H5_DLL herr_t H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hs * effect. Also, the implementation does not handle the #H5S_ALL * macro correctly. As a workaround, application can get * the dataspace for the dataset using H5Dget_space() and pass that - * in for \p fspace_id. This will be fixed in coming releases. + * in for \p fspace_id. This will be fixed in a future release. * * \since 1.10.5 * @@ -638,7 +663,7 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u * -------------------------------------------------------------------------- * \ingroup H5D * - * \brief Iterate over all chunks + * \brief Iterate over all chunks of a chunked dataset * * \dset_id * \param[in] dxpl_id Identifier of a transfer property list @@ -649,33 +674,16 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u * * \details H5Dget_chunk_iter iterates over all chunks in the dataset, calling the * user supplied callback with the details of the chunk and the supplied - * \p op_data. - * - * Callback information: - * H5D_chunk_iter_op_t is defined as: - * - * typedef int (*H5D_chunk_iter_op_t)( - * const hsize_t *offset, - * uint32_t filter_mask, - * haddr_t addr, - * uint32_t nbytes, - * void *op_data); - * - * H5D_chunk_iter_op_t parameters: - * hsize_t *offset; IN/OUT: Array of starting logical coordinates of chunk. - * uint32_t filter_mask; IN: Filter mask of chunk. - * haddr_t addr; IN: Offset in file of chunk data. - * uint32_t nbytes; IN: Size in number of bytes of chunk data in file. - * void *op_data; IN/OUT: Pointer to any user-defined data - * associated with the operation. - * - * The return values from an operator are: - * Zero (H5_ITER_CONT) causes the iterator to continue, returning zero when all - * elements have been processed. - * Positive (H5_ITER_STOP) causes the iterator to immediately return that positive - * value, indicating short-circuit success. - * Negative (H5_ITER_ERROR) causes the iterator to immediately return that value, - * indicating failure. + * context \p op_data. + * + * \par Example + * For each chunk, print the allocated chunk size (0 for un-allocated chunks). + * \snippet H5D_examples.c H5Dchunk_iter_cb + * Iterate over all chunked datasets and chunks in a file. + * \snippet H5D_examples.c H5Ovisit_cb + * + * \version 1.?.? + * \todo When was this function introduced? * */ H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb, void *op_data); @@ -696,16 +704,16 @@ H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb * * \return \herr_t * - * \details H5Dget_chunk_info() retrieves the offset coordinates - * offset, filter mask filter_mask, size size and address addr for - * the dataset specified by the identifier dset_id and the chunk - * specified by the index index. The chunk belongs to a set of - * chunks in the selection specified by fspace_id. If the queried + * \details H5Dget_chunk_info() retrieves the offset coordinates, + * \p offset, filter mask, \p filter_mask, size, \p size, and address + * \p addr for the dataset specified by the identifier \p dset_id and the chunk + * specified by the index \p index. The chunk belongs to a set of + * chunks in the selection specified by \p fspace_id. If the queried * chunk does not exist in the file, the size will be set to 0 and - * address to \c HADDR_UNDEF. The value pointed to by filter_mask will - * not be modified. NULL can be passed in for any \p out parameters. + * address to #HADDR_UNDEF. The value pointed to by filter_mask will + * not be modified. \c NULL can be passed in for any \p out parameters. * - * \p chk_idx is the chunk index in the selection. Index value + * \p chk_idx is the chunk index in the selection. The index value * may have a value of 0 up to the number of chunks stored in * the file that have a nonempty intersection with the file * dataspace selection @@ -719,9 +727,9 @@ H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb * \note Please be aware that this function currently does not * support non-trivial selections, thus \p fspace_id has no * effect. Also, the implementation does not handle the #H5S_ALL - * macro correctly. As a workaround, application can get + * macro correctly. As a workaround, an application can get * the dataspace for the dataset using H5Dget_space() and pass that - * in for \p fspace_id. This will be fixed in coming releases. + * in for \p fspace_id. This will be fixed in a future release. * * \since 1.10.5 * @@ -737,7 +745,7 @@ H5_DLL herr_t H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_idx, * * \dset_id * - * \return Returns the offset in bytes; otherwise, returns \c HADDR_UNDEF, + * \return Returns the offset in bytes; otherwise, returns #HADDR_UNDEF, * a negative value. * * \details H5Dget_offset() returns the address in the file of @@ -786,9 +794,8 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id); * used for the memory dataspace and the selection defined with \p * file_space_id is used for the selection within that dataspace. * - * If raw data storage space has not been allocated for the dataset - * and a fill value has been defined, the returned buffer \p buf - * is filled with the fill value. + * The number of elements selected in the memory dataspace \Emph{must} + * be equal to the number of elements selected in the file dataspace. * * The behavior of the library for the various combinations of * valid dataspace identifiers and #H5S_ALL for the \p mem_space_id @@ -833,14 +840,12 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id); * </tr> * </table> * - * \details Setting an #H5S_ALL selection indicates that the entire - * dataspace, as defined by the current dimensions of a dataspace, - * will be selected. The number of elements selected in the memory - * dataspace must match the number of elements selected in the - * file dataspace. + * \note If no storage space was allocated for the dataset + * and a fill value is defined, the returned buffer \p buf + * is filled with the fill value. * - * \p dxpl_id can be the constant #H5P_DEFAULT, in which case the - * default data transfer properties are used. + * \par Example + * \snippet H5D_examples.c read * */ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, @@ -953,6 +958,8 @@ H5_DLL herr_t H5Dread_async(const char *app_file, const char *app_func, unsigned * time if the dataset's fill time is set to #H5D_FILL_TIME_IFSET * or #H5D_FILL_TIME_ALLOC. * + * \par_compr_note + * * \attention If a dataset's storage layout is 'compact', care must be * taken when writing data to the dataset in parallel. A compact * dataset's raw data is cached in memory and may be flushed @@ -960,6 +967,9 @@ H5_DLL herr_t H5Dread_async(const char *app_file, const char *app_func, unsigned * applications should always attempt to write identical data to * the dataset from all processes. * + * \par Example + * \snippet H5D_examples.c update + * * \see H5Pset_fill_time(), H5Pset_alloc_time() * */ @@ -1000,11 +1010,6 @@ H5_DLL herr_t H5Dwrite_async(const char *app_file, const char *app_func, unsigne * pipeline, including filters, and will be written directly to * the file. Only one chunk can be written with this function. * - * H5Dwrite_chunk() replaces the now deprecated H5DOwrite_chunk() - * function, which was located in the high level optimization - * library. The parameters and behavior are identical to the - * original. - * * \p filters is a mask providing a record of which filters are * used with the the chunk. The default value of the mask is * zero (0), indicating that all enabled filters are applied. A @@ -1032,11 +1037,10 @@ H5_DLL herr_t H5Dwrite_async(const char *app_file, const char *app_func, unsigne * in a file. H5Dwrite_chunk() bypasses hyperslab selection, the * conversion of data from one datatype to another, and the filter * pipeline to write the chunk. Developers should have experience - * with these processes before using this function. Please see - * Using the Direct Chunk Write Function for more information. + * with these processes before using this function. * - * \note H5Dread_chunk() and H5Dwrite_chunk() are not supported under - * parallel and do not support variable length types. + * \note H5Dread_chunk() and H5Dwrite_chunk() are currently not supported + * with parallel HDF5 and do not support variable-length types. * * \since 1.10.2 * @@ -1074,10 +1078,10 @@ H5_DLL herr_t H5Dwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, con * the dimension limits and must specify a point that falls on * a dataset chunk boundary. * - * The mask \p filters indicates which filters are used with the - * chunk when written. A zero value indicates that all enabled - * filters are applied on the chunk. A filter is skipped if the - * bit corresponding to the filter’s position in the pipeline + * The mask \p filters indicates which filters were used when the + * chunk was written. A zero value (all bits 0) indicates that all + * enabled filters are applied on the chunk. A filter is skipped if + * the bit corresponding to the filter’s position in the pipeline * (0 ≤ position < 32) is turned on. * * \p buf is the memory buffer containing the chunk read from @@ -1091,8 +1095,8 @@ H5_DLL herr_t H5Dwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, con * with these processes before using this function. Please see * Using the Direct Chunk Write Function for more information. * - * \note H5Dread_chunk() and H5Dwrite_chunk() are not supported under - * parallel and do not support variable length types. + * \note H5Dread_chunk() and H5Dwrite_chunk() are currently not supported + * with parallel HDF5 and do not support variable-length datatypes. * * \since 1.10.2 * @@ -1122,52 +1126,9 @@ H5_DLL herr_t H5Dread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, * in the memory buffer \p buf, executing the callback function * \p op once for each such data element. * - * The prototype of the callback function \p op is as follows - * (as defined in the source code file H5Lpublic.h): - * \snippet this H5D_operator_t_snip - * The parameters of this callback function are: - * - * <table> - * <tr><td>\c elem</td> - * <td><tt>[in,out]</tt></td> - * <td>Pointer to the memory buffer containing the current - * data element</td></tr> - * <tr><td>\c type_id</td> - * <td><tt>[in]</tt></td> - * <td>Datatype identifier of the elements stored in elem</td></tr> - * <tr><td>\c ndim</td> - * <td><tt>[in]</tt></td> - * <td>Number of dimensions for the point array</td></tr> - * <tr><td>\c point</td> - * <td><tt>[in]</tt></td> - * <td>Array containing the location of the element within - * the original dataspace</td></tr> - * <tr><td>\c operator_data</td> - * <td><tt>[in,out]</tt></td> - * <td>Pointer to any user-defined data associated with the - * operation</td></tr> - * </table> - * - * The possible return values from the callback function, and - * the effect ofeach,are as follows: - * - * \li Zero causes the iterator to continue, returning zero - * when all data elements have been processed. - * \li A positive value causes the iterator to immediately - * return that positive value, indicating short-circuit success. - * \li A negative value causes the iterator to immediately return - * that value, indicating failure. - * - * The \p operator_data parameter is a user-defined pointer to - * the data required to process dataset elements in the course - * of the iteration. If operator needs to pass data back to the - * application, such data can be returned in this same buffer. This - * pointer is passed back to each step of the iteration in the - * operator callback function’s operator_data parameter. - * - * Unlike other HDF5 iterators, this iteration operation cannot - * be restarted at the point of exit; a second H5Diterate() - * call will always restart at the beginning. + * \attention Unlike other HDF5 iterators, this iteration operation cannot + * be restarted at the point of exit; a second H5Diterate() + * call will always restart at the beginning. * * * \since 1.10.2 @@ -1217,30 +1178,25 @@ H5_DLL herr_t H5Dvlen_get_buf_size(hid_t dset_id, hid_t type_id, hid_t space_id, * * \return \herr_t * - * \details H5Dfill() fills the dataspace selection in memory, \p space_id, + * \details H5Dfill() fills the dataspace selection, \p space_id, in memory * with the fill value specified in \p fill. If \p fill is NULL, * a fill value of 0 (zero) is used. * * \p fill_type_id specifies the datatype of the fill value. - * \p buf specifies the buffer in which the dataspace elements - * will be written. - * \p buf_type_id specifies the datatype of those data elements. + * \p buf specifies the buffer in which the fill elements + * will be written. \p buf_type_id specifies the datatype of + * those data elements. * * \note Note that if the fill value datatype differs from the memory - * buffer datatype, the fill value will be converted to the memory - * buffer datatype before filling the selection. + * buffer datatype, the fill value will be converted to the memory + * buffer datatype before filling the selection. * * \note Applications sometimes write data only to portions of an - * allocated dataset. It is often useful in such cases to fill - * the unused space with a known fill value. See the following - * function for more information: - * - H5Pset_fill_value() - * - H5Pget_fill_value() - * - H5Pfill_value_defined() - * - H5Pset_fill_time() - * - H5Pget_fill_time() - * - H5Pcreate() - * - H5Pcreate_anon() + * allocated dataset. It is often useful in such cases to fill + * the unused space with a known fill value. + * + * \see H5Pset_fill_value(), H5Pget_fill_value(), H5Pfill_value_defined(), + * H5Pset_fill_time(), H5Pget_fill_time(), H5Pcreate(), H5Dcreate_anon() * */ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf_type_id, hid_t space_id); @@ -1287,22 +1243,21 @@ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf * - If the dataset’s fill time is set to #H5D_FILL_TIME_ALLOC * (see H5Pset_alloc_time()) * - * \note - * \li If the sizes specified in \p size array are smaller than - * the dataset’s current dimension sizes, H5Dset_extent() will reduce - * the dataset’s dimension sizes to the specified values. It is the - * user application’s responsibility to ensure that valuable data is - * not lost as H5Dset_extent() does not check. + * \note If the sizes specified in \p size array are smaller than the dataset’s + * current dimension sizes, H5Dset_extent() will reduce the dataset’s + * dimension sizes to the specified values. It is the user application’s + * responsibility to ensure that valuable data is not lost as + * H5Dset_extent() does not check. * - * \li Except for external datasets, H5Dset_extent() is for use with - * chunked datasets only, not contiguous datasets. + * \note Except for external datasets, H5Dset_extent() is for use with + * chunked datasets only, not contiguous datasets. * - * \li A call to H5Dset_extent() affects the dataspace of a dataset. - * If a dataspace handle was opened for a dataset prior to a call to - * H5Dset_extent() then that dataspace handle will no longer reflect - * the correct dataspace extent of the dataset. H5Dget_space() must - * be called (after closing the previous handle) to obtain the current - * dataspace extent. + * \note A call to H5Dset_extent() affects the dataspace of a dataset. If a + * dataspace handle was opened for a dataset prior to a call to + * H5Dset_extent() then that dataspace handle will no longer reflect the + * correct dataspace extent of the dataset. H5Dget_space() must be called + * (after closing the previous handle) to obtain the current dataspace + * extent. * * \since 1.8.0 * @@ -1337,6 +1292,8 @@ H5_DLL herr_t H5Dset_extent_async(const char *app_file, const char *app_func, un * open files. After that, the OS is responsible for ensuring * that the data is actually flushed to disk. * + * \since 1.10.0 + * */ H5_DLL herr_t H5Dflush(hid_t dset_id); @@ -1395,40 +1352,7 @@ H5_DLL herr_t H5Drefresh(hid_t dset_id); * * To retrieve the data to be scattered, H5Dscatter() repeatedly * calls \p op, which should return a valid source buffer, until - * enough data to fill the selection has been retrieved. The - * prototype of the callback function \p op is as follows (as - * defined in the source code file H5Dpublic.h): - * \snippet this H5D_scatter_func_t_snip - * The parameters of this callback function are described below: - * - * <table> - * <tr><td>\c src_buf</td> - * <td><tt>[out]</tt></td> - * <td>Pointer to the buffer holding the next set of elements to - * scatter. On entry, the value of where \c src_buf points to - * is undefined. The callback function should set \c src_buf - * to point to the next set of elements.</td></tr> - * <tr><td>\c src_buf_bytes_used</td> - * <td><tt>[out]</tt></td> - * <td>Pointer to the number of valid bytes in \c src_buf. On - * entry, the value where \c src_buf_bytes_used points to is - * undefined. The callback function should set - * \c src_buf_bytes_used to the of valid bytes in \c src_buf. - * This number must be a multiple of the datatype size. - * </td></tr> - * <tr><td>\c op_data</td> - * <td><tt>[in,out]</tt></td> - * <td>User-defined pointer to data required by the callback - * function. A pass-through of the \c op_data pointer provided - * with the H5Dscatter() function call.</td></tr> - * </table> - * - * The callback function should always return at least one - * element in \p src_buf, and must not return more elements - * than are remaining to be scattered. This function will be - * repeatedly called until all elements to be scattered have - * been returned. The callback function should return zero (0) - * to indicate success, and a negative value to indicate failure. + * enough data to fill the selection has been retrieved. * * \since 1.10.2 * @@ -1480,27 +1404,9 @@ H5_DLL herr_t H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hi * If no callback function is provided, H5Dgather() simply gathers * the data into \p dst_buf and returns. If a callback function is * provided, H5Dgather() repeatedly gathers up to \p dst_buf_size - * bytes to process the serialized data. The prototype of the - * callback function \p op is as follows (as defined in the source - * code file H5Dpublic.h): - * \snippet this H5D_gather_func_t_snip - * The parameters of this callback function are described in the - * table below. - * <table> - * <tr><td>\c dst_buf</td> - * <td>Pointer to the destination buffer which has been filled - * with the next set of elements gathered. This will always be - * identical to the \p dst_buf passed to H5Dgather().</td></tr> - * <tr><td>\c dst_buf_bytes_used</td> - * <td>Pointer to the number of valid bytes in \p dst_buf. - * This number must be a multiple of the datatype - * size.</td></tr> - * <tr><td>\c op_data</td> - * <td>User-defined pointer to data required by the callback - * function; a pass-through of the \p op_data pointer - * provided with the H5Dgather() function call.</td></tr> - * </table> - * The callback function should process, store, or otherwise, + * bytes to process the serialized data. + * + * The callback function \p op should process, store, or otherwise, * make use of the data returned in \p dst_buf before it returns, * because the buffer will be overwritten unless it is the last * call to the callback. This function will be repeatedly called @@ -1524,11 +1430,11 @@ H5_DLL herr_t H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, * * \return \herr_t * - * \details H5Dclose() ends access to a dataset specified by \p dset_id - * and releases resources used by it. + * \details H5Dclose() terminates access to a dataset via the identifier + * \p dset_id and releases the underlying resources. * - * \attention Further use of a released dataset identifier is illegal; a - * function using such an identifier will generate an error. + * \par Example + * \snippet H5D_examples.c read * * \since 1.8.0 * @@ -1544,12 +1450,14 @@ H5_DLL herr_t H5Dclose(hid_t dset_id); */ H5_DLL herr_t H5Dclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id, hid_t es_id); - +/// \cond DEV /* Internal API routines */ H5_DLL herr_t H5Ddebug(hid_t dset_id); H5_DLL herr_t H5Dformat_convert(hid_t dset_id); H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); +/// \endcond +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -1573,6 +1481,7 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); #define H5Dset_extent_async_wrap H5_NO_EXPAND(H5Dset_extent_async) #define H5Dclose_async_wrap H5_NO_EXPAND(H5Dclose_async) #endif /* H5D_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * @@ -1613,8 +1522,7 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); * * \return \hid_t{dataset} * - * \deprecated This function is deprecated in favor of the function H5Dcreate2() - * or the macro H5Dcreate(). + * \deprecation_note{H5Dcreate2() or the macro H5Dcreate()} * * \details H5Dcreate1() creates a data set with a name, \p name, in the * location specified by the identifier \p loc_id. \p loc_id may be a @@ -1680,8 +1588,7 @@ H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa * * \return \hid_t{dataset} * - * \deprecated This function is deprecated in favor of the function H5Dopen2() - * or the macro H5Dopen(). + * \deprecation_note{H5Dopen2() or the macro H5Dopen()} * * \details H5Dopen1() opens an existing dataset for access at the location * specified by \p loc_id. \p loc_id may be a file, group, dataset, @@ -1711,10 +1618,10 @@ H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name); * * \return \herr_t * - * \deprecated This function is deprecated in favor of the function H5Dset_extent(). + * \deprecation_note{H5Dset_extent()} * * \details H5Dextend() verifies that the dataset is at least of size \p size, - * extending it if necessary. The dimensionality of size is the same as + * extending it if necessary. The length of \p size is the same as * that of the dataspace of the dataset being changed. * * This function can be applied to the following datasets: @@ -1734,7 +1641,7 @@ H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name); * the sizes specified in size. The function H5Dset_extent() must be * used if the dataset dimension sizes are are to be reduced. * - * \version 1.8.0 Function Function deprecated in this release. Parameter size + * \version 1.8.0 Function deprecated in this release. Parameter size * syntax changed to \Code{const hsize_t size[]} in this release. * */ @@ -1752,8 +1659,7 @@ H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]); * * \return \herr_t * - * \deprecated This function has been deprecated in HDF5-1.12 in favor of the - * function H5Treclaim(). + * \deprecation_note{H5Treclaim()} * * \details H5Dvlen_reclaim() reclaims memory buffers created to store VL * datatypes. @@ -1771,7 +1677,7 @@ H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]); * frees them from the bottom up, releasing all the memory without * creating memory leaks. * - * \version 1.12.0 Routine was deprecated + * \version 1.12.0 Function was deprecated * */ H5_DLL herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf); @@ -639,7 +639,7 @@ H5E__get_class_name(const H5E_cls_t *cls, char *name, size_t size) /* Set the user's buffer, if provided */ if (name) { - HDstrncpy(name, cls->cls_name, MIN((size_t)(len + 1), size)); + HDstrncpy(name, cls->cls_name, size); if ((size_t)len >= size) name[size - 1] = '\0'; } /* end if */ diff --git a/src/H5ESmodule.h b/src/H5ESmodule.h index cbc812e..5169b52 100644 --- a/src/H5ESmodule.h +++ b/src/H5ESmodule.h @@ -29,8 +29,10 @@ #define H5_MY_PKG_ERR H5E_EVENTSET #define H5_MY_PKG_INIT YES -/** - * \defgroup H5ES H5ES +/**\defgroup H5ES H5ES + * + * \todo Add the event set life cycle. + * * \brief Event Set Interface * * \details \Bold{This interface can be only used with the HDF5 VOL connectors that diff --git a/src/H5Eint.c b/src/H5Eint.c index b38833f..6438cd9 100644 --- a/src/H5Eint.c +++ b/src/H5Eint.c @@ -129,7 +129,7 @@ H5E__get_msg(const H5E_msg_t *msg, H5E_type_t *type, char *msg_str, size_t size) /* Copy the message into the user's buffer, if given */ if (msg_str) { - HDstrncpy(msg_str, msg->msg, MIN((size_t)(len + 1), size)); + HDstrncpy(msg_str, msg->msg, size); if ((size_t)len >= size) msg_str[size - 1] = '\0'; } /* end if */ diff --git a/src/H5Emodule.h b/src/H5Emodule.h index 43d5d36..58a3517 100644 --- a/src/H5Emodule.h +++ b/src/H5Emodule.h @@ -29,33 +29,54 @@ #define H5_MY_PKG_ERR H5E_ERROR #define H5_MY_PKG_INIT YES -/** - * \defgroup H5E H5E - * \brief Error Handling Interface - * - * \details The Error interface provides error handling in the form of a stack. - * The \Code{FUNC_ENTER} macro clears the error stack whenever an - * interface function is entered. When an error is detected, an entry - * is pushed onto the stack. As the functions unwind, additional - * entries are pushed onto the stack. The API function will return some - * indication that an error occurred and the application can print the - * error stack. - * - * Certain API functions in the \c H5E package, such as H5Eprint1(), do - * not clear the error stack. Otherwise, any function which does not - * have an underscore immediately after the package name will clear the - * error stack. For instance, H5Fopen() clears the error stack while - * \Code{H5F_open} does not. - * - * An error stack has a fixed maximum size. If this size is exceeded - * then the stack will be truncated and only the inner-most functions - * will have entries on the stack. This is expected to be a rare - * condition. - * - * Each thread has its own error stack, but since multi-threading has - * not been added to the library yet, this package maintains a single - * error stack. The error stack is statically allocated to reduce the - * complexity of handling errors within the \c H5E package. +/**\defgroup H5E H5E + * + * Use the functions in this module to manage HDF5 error stacks and error + * messages. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5E_examples.c create + * </td> + * <td> + * \snippet{lineno} H5E_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5E_examples.c update + * </td> + * <td> + * \snippet{lineno} H5E_examples.c delete + * </td> + * </tr> + * </table> + * + * \internal The \c FUNC_ENTER macro clears the error stack whenever an + * interface function is entered. When an error is detected, an entry + * is pushed onto the stack. As the functions unwind, additional + * entries are pushed onto the stack. The API function will return + * some indication that an error occurred and the application can + * print the error stack. + * + * \internal Certain API functions in the \ref H5E package, such as H5Eprint(), + * do not clear the error stack. Otherwise, any function which does + * not have an underscore immediately after the package name will + * clear the error stack. For instance, H5Fopen() clears the error + * stack while \Code{H5F_open} does not. + * + * \internal An error stack has a fixed maximum size. If this size is exceeded + * then the stack will be truncated and only the inner-most functions + * will have entries on the stack. This is expected to be a rare + * condition. + * + * \internal Each thread has its own error stack, but since multi-threading has + * not been added to the library yet, this package maintains a single + * error stack. The error stack is statically allocated to reduce the + * complexity of handling errors within the \ref H5E package. + * */ #endif /* H5Emodule_H */ diff --git a/src/H5Epublic.h b/src/H5Epublic.h index 0294023..9dfd1fc 100644 --- a/src/H5Epublic.h +++ b/src/H5Epublic.h @@ -716,12 +716,13 @@ typedef herr_t (*H5E_auto1_t)(void *client_data); * * \return \herr_t * + * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated + * in this release. + * * \details H5Eclear1() clears the error stack for the current thread.\n * The stack is also cleared whenever an API function is called, with * certain exceptions (for instance, H5Eprint1()). * - * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated - * in this release. */ H5_DLL herr_t H5Eclear1(void); /** @@ -737,6 +738,9 @@ H5_DLL herr_t H5Eclear1(void); * function * \return \herr_t * + * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and + * deprecated in this release. + * * \details H5Eget_auto1() returns the current settings for the automatic error * stack traversal function, \p func, and its data, * \p client_data. Either or both arguments may be \c NULL, in which case the @@ -763,8 +767,6 @@ H5_DLL herr_t H5Eclear1(void); * H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing * H5Eset_auto2() and H5Eget_auto1() does not fail. * - * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and - * deprecated in this release. */ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); /** @@ -781,6 +783,9 @@ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); * \param[in] str Error description string * \return \herr_t * + * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and + * deprecated in this release. + * * \details H5Epush1() pushes a new error record onto the error stack for the * current thread.\n * The error has major and minor numbers \p maj_num @@ -791,8 +796,6 @@ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); * allocated. * * \since 1.4.0 - * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and - * deprecated in this release. */ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min, const char *str); @@ -805,6 +808,9 @@ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_ma * \param[in] stream File pointer, or \c NULL for \c stderr * \return \herr_t * + * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and + * deprecated in this release. + * * \details H5Eprint1() prints prints the error stack for the current thread * on the specified stream, \p stream. Even if the error stack is empty, a * one-line message of the following form will be printed: @@ -815,8 +821,6 @@ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_ma * that prints error messages. Users are encouraged to write their own * more specific error handlers. * - * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and - * deprecated in this release. */ H5_DLL herr_t H5Eprint1(FILE *stream); /** @@ -829,6 +833,9 @@ H5_DLL herr_t H5Eprint1(FILE *stream); * \param[in] client_data Data passed to the error function * \return \herr_t * + * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and + * deprecated in this release. + * * \details H5Eset_auto1() turns on or off automatic printing of errors. When * turned on (non-null \p func pointer), any API function which returns * an error indication will first call \p func, passing it \p @@ -845,8 +852,6 @@ H5_DLL herr_t H5Eprint1(FILE *stream); * Automatic stack traversal is always in the #H5E_WALK_DOWNWARD * direction. * - * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and - * deprecated in this release. */ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); /** @@ -860,6 +865,9 @@ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); * \param[in] client_data Data to be passed to \p func * \return \herr_t * + * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and + * deprecated in this release. + * * \details H5Ewalk1() walks the error stack for the current thread and calls * the function specified in \p func for each error along the way. * @@ -877,8 +885,6 @@ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); * is as follows: * \snippet this H5E_walk1_t_snip * - * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and - * deprecated in this release. */ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client_data); /** @@ -891,6 +897,8 @@ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client * \param[in] maj Major error number * \return \herr_t * + * \deprecated 1.8.0 Function deprecated in this release. + * * \details Given a major error number, H5Eget_major() returns a constant * character string that describes the error. * @@ -898,7 +906,6 @@ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client * array). An application calling this function must free the memory * associated with the return value to prevent a memory leak. * - * \deprecated 1.8.0 Function deprecated in this release. */ H5_DLL char *H5Eget_major(H5E_major_t maj); /** @@ -911,6 +918,8 @@ H5_DLL char *H5Eget_major(H5E_major_t maj); * \param[in] min Minor error number * \return \herr_t * + * \deprecated 1.8.0 Function deprecated and return type changed in this release. + * * \details Given a minor error number, H5Eget_minor() returns a constant * character string that describes the error. * @@ -920,7 +929,6 @@ H5_DLL char *H5Eget_major(H5E_major_t maj); * the memory associated with the return value to prevent a memory * leak. This is a change from the 1.6.x release series. * - * \deprecated 1.8.0 Function deprecated and return type changed in this release. */ H5_DLL char *H5Eget_minor(H5E_minor_t min); #endif /* H5_NO_DEPRECATED_SYMBOLS */ @@ -1688,6 +1688,111 @@ done: } /* end H5FD_unlock() */ /*------------------------------------------------------------------------- + * Function: H5FDctl + * + * Purpose: Perform a CTL operation. + * + * The desired operation is specified by the op_code + * parameter. + * + * The flags parameter controls management of op_codes that + * are unknown to the callback + * + * The input and output parameters allow op_code specific + * input and output + * + * Return: Non-negative on success/Negative on failure + * + * Programmer: JRM -- 8/3/21 + * + *------------------------------------------------------------------------- + */ +herr_t +H5FDctl(H5FD_t *file, uint64_t op_code, uint64_t flags, const void *input, void **output) +{ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_API(FAIL) + H5TRACE5("e", "*#ULUL*x**x", file, op_code, flags, input, output); + + /* Check arguments */ + if (!file) + HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "file pointer cannot be NULL") + + if (!file->cls) + HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "file class pointer cannot be NULL") + + /* Don't attempt to validate the op code. If appropriate, that will + * be done by the underlying VFD callback, along with the input and + * output parameters. + */ + + /* Call private function */ + if (H5FD_ctl(file, op_code, flags, input, output) < 0) + HGOTO_ERROR(H5E_VFL, H5E_FCNTL, FAIL, "VFD ctl request failed") + +done: + + FUNC_LEAVE_API(ret_value) + +} /* end H5FDctl() */ + +/*------------------------------------------------------------------------- + * Function: H5FD_ctl + * + * Purpose: Private version of H5FDctl() + * + * The desired operation is specified by the op_code + * parameter. + * + * The flags parameter controls management of op_codes that + * are unknown to the callback + * + * The input and output parameters allow op_code specific + * input and output + * + * Return: Non-negative on success/Negative on failure + * + * Programmer: JRM -- 8/3/21 + * + *------------------------------------------------------------------------- + */ +herr_t +H5FD_ctl(H5FD_t *file, uint64_t op_code, uint64_t flags, const void *input, void **output) +{ + herr_t ret_value = SUCCEED; /* Return value */ + + FUNC_ENTER_NOAPI(FAIL) + + /* Sanity checks */ + HDassert(file); + HDassert(file->cls); + + /* Dispatch to driver if the ctl function exists. + * + * If it doesn't, fail if the H5FD_CTL__FAIL_IF_UNKNOWN_FLAG is set. + * + * Otherwise, report success. + */ + if (file->cls->ctl) { + + if ((file->cls->ctl)(file, op_code, flags, input, output) < 0) + + HGOTO_ERROR(H5E_VFL, H5E_FCNTL, FAIL, "VFD ctl request failed") + } + else if (flags & H5FD_CTL__FAIL_IF_UNKNOWN_FLAG) { + + HGOTO_ERROR(H5E_VFL, H5E_FCNTL, FAIL, + "VFD ctl request failed (no ctl callback and fail if unknown flag is set)") + } + +done: + + FUNC_LEAVE_NOAPI(ret_value) + +} /* end H5FD_ctl() */ + +/*------------------------------------------------------------------------- * Function: H5FD_get_fileno * * Purpose: Quick and dirty routine to retrieve the file's 'fileno' value diff --git a/src/H5FDcore.c b/src/H5FDcore.c index 50288c4..820c74f 100644 --- a/src/H5FDcore.c +++ b/src/H5FDcore.c @@ -183,6 +183,7 @@ static const H5FD_class_t H5FD_core_g = { H5FD__core_lock, /* lock */ H5FD__core_unlock, /* unlock */ H5FD__core_delete, /* del */ + NULL, /* ctl */ H5FD_FLMAP_DICHOTOMY /* fl_map */ }; diff --git a/src/H5FDdevelop.h b/src/H5FDdevelop.h index 57f0a42..4895658 100644 --- a/src/H5FDdevelop.h +++ b/src/H5FDdevelop.h @@ -192,6 +192,7 @@ typedef struct H5FD_class_t { herr_t (*lock)(H5FD_t *file, hbool_t rw); herr_t (*unlock)(H5FD_t *file); herr_t (*del)(const char *name, hid_t fapl); + herr_t (*ctl)(H5FD_t *file, uint64_t op_code, uint64_t flags, const void *input, void **output); H5FD_mem_t fl_map[H5FD_MEM_NTYPES]; } H5FD_class_t; @@ -254,6 +255,7 @@ H5_DLL herr_t H5FDtruncate(H5FD_t *file, hid_t dxpl_id, hbool_t closing); H5_DLL herr_t H5FDlock(H5FD_t *file, hbool_t rw); H5_DLL herr_t H5FDunlock(H5FD_t *file); H5_DLL herr_t H5FDdelete(const char *name, hid_t fapl_id); +H5_DLL herr_t H5FDctl(H5FD_t *file, uint64_t op_code, uint64_t flags, const void *input, void **output); #ifdef __cplusplus } diff --git a/src/H5FDdirect.c b/src/H5FDdirect.c index a1b7b7e..7cca09f 100644 --- a/src/H5FDdirect.c +++ b/src/H5FDdirect.c @@ -172,6 +172,7 @@ static const H5FD_class_t H5FD_direct_g = { H5FD__direct_lock, /* lock */ H5FD__direct_unlock, /* unlock */ H5FD__direct_delete, /* del */ + NULL, /* ctl */ H5FD_FLMAP_DICHOTOMY /* fl_map */ }; diff --git a/src/H5FDfamily.c b/src/H5FDfamily.c index b265e1d..af67c78 100644 --- a/src/H5FDfamily.c +++ b/src/H5FDfamily.c @@ -137,6 +137,7 @@ static const H5FD_class_t H5FD_family_g = { H5FD__family_lock, /* lock */ H5FD__family_unlock, /* unlock */ H5FD__family_delete, /* del */ + NULL, /* ctl */ H5FD_FLMAP_DICHOTOMY /* fl_map */ }; @@ -582,7 +583,7 @@ done: * memb_name & temp in the code below, but early (4.4.7, at least) gcc only * allows diagnostic pragmas to be toggled outside of functions. */ -H5_GCC_DIAG_OFF("format-nonliteral") +H5_GCC_CLANG_DIAG_OFF("format-nonliteral") static H5FD_t * H5FD__family_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr) { @@ -735,7 +736,7 @@ done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5FD__family_open() */ -H5_GCC_DIAG_ON("format-nonliteral") +H5_GCC_CLANG_DIAG_ON("format-nonliteral") /*------------------------------------------------------------------------- * Function: H5FD__family_close @@ -905,7 +906,7 @@ H5FD__family_get_eoa(const H5FD_t *_file, H5FD_mem_t H5_ATTR_UNUSED type) * memb_name in the code below, but early (4.4.7, at least) gcc only * allows diagnostic pragmas to be toggled outside of functions. */ -H5_GCC_DIAG_OFF("format-nonliteral") +H5_GCC_CLANG_DIAG_OFF("format-nonliteral") static herr_t H5FD__family_set_eoa(H5FD_t *_file, H5FD_mem_t type, haddr_t abs_eoa) { @@ -974,7 +975,7 @@ done: FUNC_LEAVE_NOAPI(ret_value) } -H5_GCC_DIAG_ON("format-nonliteral") +H5_GCC_CLANG_DIAG_ON("format-nonliteral") /*------------------------------------------------------------------------- * Function: H5FD__family_get_eof diff --git a/src/H5FDhdfs.c b/src/H5FDhdfs.c index 9491e82..ac48b42 100644 --- a/src/H5FDhdfs.c +++ b/src/H5FDhdfs.c @@ -1,15 +1,13 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * Read-Only HDFS Virtual File Driver (VFD) * - * Copyright (c) 2018, The HDF Group. * - * * + * Copyright by The HDF Group. * * All rights reserved. * * * - * NOTICE: * - * All information contained herein is, and remains, the property of The HDF * - * Group. The intellectual and technical concepts contained herein are * - * proprietary to The HDF Group. Dissemination of this information or * - * reproduction of this material is strictly forbidden unless prior written * - * permission is obtained from The HDF Group. * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* @@ -312,6 +310,7 @@ static const H5FD_class_t H5FD_hdfs_g = { NULL, /* lock */ NULL, /* unlock */ NULL, /* del */ + NULL, /* ctl */ H5FD_FLMAP_DICHOTOMY /* fl_map */ }; diff --git a/src/H5FDhdfs.h b/src/H5FDhdfs.h index 8d65ac7..7c871a4 100644 --- a/src/H5FDhdfs.h +++ b/src/H5FDhdfs.h @@ -1,15 +1,14 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * Read-Only HDFS Virtual File Driver (VFD) * - * Copyright (c) 2018, The HDF Group. * + * Copyright by The HDF Group. * * * * All rights reserved. * * * - * NOTICE: * - * All information contained herein is, and remains, the property of The HDF * - * Group. The intellectual and technical concepts contained herein are * - * proprietary to The HDF Group. Dissemination of this information or * - * reproduction of this material is strictly forbidden unless prior written * - * permission is obtained from The HDF Group. * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* diff --git a/src/H5FDlog.c b/src/H5FDlog.c index f996b9e..87871ab 100644 --- a/src/H5FDlog.c +++ b/src/H5FDlog.c @@ -212,6 +212,7 @@ static const H5FD_class_t H5FD_log_g = { H5FD__log_lock, /* lock */ H5FD__log_unlock, /* unlock */ H5FD__log_delete, /* del */ + NULL, /* ctl */ H5FD_FLMAP_DICHOTOMY /* fl_map */ }; diff --git a/src/H5FDmirror.c b/src/H5FDmirror.c index 8cbeff6..d539f4d 100644 --- a/src/H5FDmirror.c +++ b/src/H5FDmirror.c @@ -192,6 +192,7 @@ static const H5FD_class_t H5FD_mirror_g = { H5FD__mirror_lock, /* lock */ H5FD__mirror_unlock, /* unlock */ NULL, /* del */ + NULL, /* ctl */ H5FD_FLMAP_DICHOTOMY /* fl_map */ }; diff --git a/src/H5FDmpi.c b/src/H5FDmpi.c index 048b8f3..7eb1463 100644 --- a/src/H5FDmpi.c +++ b/src/H5FDmpi.c @@ -41,26 +41,42 @@ * Programmer: Quincey Koziol * Friday, January 30, 2004 * + * Changes: Reworked function to use the ctl callback so we can get + * rid of H5FD_class_mpi_t. Since there are no real limits + * on what the ctl callback can do, its file parameter can't + * be constant. Thus, I had to remove the const qualifier + * on this functions file parameter as well. Note also the + * circumlocution required to use the ctl callbacks output + * parameter to pass back the rank without introducing + * compiler warnings. + * JRM -- 8/13/21 + * *------------------------------------------------------------------------- */ int -H5FD_mpi_get_rank(const H5FD_t *file) +H5FD_mpi_get_rank(H5FD_t *file) { - const H5FD_class_mpi_t *cls; - - int ret_value; + const H5FD_class_t *cls; + uint64_t flags = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG | H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG; + int rank = -1; + void * rank_ptr = (void *)(&rank); + int ret_value; FUNC_ENTER_NOAPI(FAIL) HDassert(file); - cls = (const H5FD_class_mpi_t *)(file->cls); + cls = (const H5FD_class_t *)(file->cls); HDassert(cls); - HDassert(cls->get_rank); /* All MPI drivers must implement this */ + HDassert(cls->ctl); /* All MPI drivers must implement this */ /* Dispatch to driver */ - if ((ret_value = (cls->get_rank)(file)) < 0) + if ((cls->ctl)(file, H5FD_CTL__GET_MPI_RANK_OPCODE, flags, NULL, &rank_ptr) < 0) HGOTO_ERROR(H5E_VFL, H5E_CANTGET, FAIL, "driver get_rank request failed") + HDassert(rank >= 0); + + ret_value = rank; + done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5FD_mpi_get_rank() */ @@ -77,25 +93,43 @@ done: * Programmer: Quincey Koziol * Friday, January 30, 2004 * + * Changes: Reworked function to use the ctl callback so we can get + * rid of H5FD_class_mpi_t. Since there are no real limits + * on what the ctl callback can do, its file parameter can't + * be constant. Thus, I had to remove the const qualifier + * on this functions file parameter as well. Note also the + * circumlocution required to use the ctl callbacks output + * parameter to pass back the rank without introducing + * compiler warnings. + * JRM -- 8/13/21 + * *------------------------------------------------------------------------- */ int -H5FD_mpi_get_size(const H5FD_t *file) +H5FD_mpi_get_size(H5FD_t *file) { - const H5FD_class_mpi_t *cls; - int ret_value; + const H5FD_class_t *cls; + uint64_t flags = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG | H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG; + int size = 0; + void * size_ptr = (void *)(&size); + int ret_value; FUNC_ENTER_NOAPI(FAIL) HDassert(file); - cls = (const H5FD_class_mpi_t *)(file->cls); + cls = (const H5FD_class_t *)(file->cls); HDassert(cls); - HDassert(cls->get_size); /* All MPI drivers must implement this */ + HDassert(cls->ctl); /* All MPI drivers must implement this */ /* Dispatch to driver */ - if ((ret_value = (cls->get_size)(file)) < 0) + if ((cls->ctl)(file, H5FD_CTL__GET_MPI_SIZE_OPCODE, flags, NULL, &size_ptr) < 0) HGOTO_ERROR(H5E_VFL, H5E_CANTGET, FAIL, "driver get_size request failed") + if (0 >= size) + HGOTO_ERROR(H5E_VFL, H5E_CANTGET, FAIL, "driver get_size request returned bad value") + + ret_value = size; + done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5FD_mpi_get_size() */ @@ -112,25 +146,43 @@ done: * Programmer: Quincey Koziol * Friday, January 30, 2004 * + * Changes: Reworked function to use the ctl callback so we can get + * rid of H5FD_class_mpi_t. Since there are no real limits + * on what the ctl callback can do, its file parameter can't + * be constant. Thus, I had to remove the const qualifier + * on this functions file parameter as well. Note also the + * circumlocution required to use the ctl callbacks output + * parameter to pass back the rank without introducing + * compiler warnings. + * JRM -- 8/13/21 + * *------------------------------------------------------------------------- */ MPI_Comm -H5FD_mpi_get_comm(const H5FD_t *file) +H5FD_mpi_get_comm(H5FD_t *file) { - const H5FD_class_mpi_t *cls; - MPI_Comm ret_value; + const H5FD_class_t *cls; + uint64_t flags = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG | H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG; + MPI_Comm comm = MPI_COMM_NULL; + void * comm_ptr = (void *)(&comm); + MPI_Comm ret_value; FUNC_ENTER_NOAPI(MPI_COMM_NULL) HDassert(file); - cls = (const H5FD_class_mpi_t *)(file->cls); + cls = (const H5FD_class_t *)(file->cls); HDassert(cls); - HDassert(cls->get_comm); /* All MPI drivers must implement this */ + HDassert(cls->ctl); /* All MPI drivers must implement this */ /* Dispatch to driver */ - if ((ret_value = (cls->get_comm)(file)) == MPI_COMM_NULL) + if ((cls->ctl)(file, H5FD_CTL__GET_MPI_COMMUNICATOR_OPCODE, flags, NULL, &comm_ptr) < 0) HGOTO_ERROR(H5E_VFL, H5E_CANTGET, MPI_COMM_NULL, "driver get_comm request failed") + if (comm == MPI_COMM_NULL) + HGOTO_ERROR(H5E_VFL, H5E_CANTGET, MPI_COMM_NULL, "driver get_comm request failed -- bad comm") + + ret_value = comm; + done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5FD_mpi_get_comm() */ diff --git a/src/H5FDmpio.c b/src/H5FDmpio.c index dd40399..7c85897 100644 --- a/src/H5FDmpio.c +++ b/src/H5FDmpio.c @@ -72,66 +72,60 @@ typedef struct H5FD_mpio_t { /* Private Prototypes */ /* Callbacks */ -static herr_t H5FD__mpio_term(void); -static H5FD_t * H5FD__mpio_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr); -static herr_t H5FD__mpio_close(H5FD_t *_file); -static herr_t H5FD__mpio_query(const H5FD_t *_f1, unsigned long *flags); -static haddr_t H5FD__mpio_get_eoa(const H5FD_t *_file, H5FD_mem_t type); -static herr_t H5FD__mpio_set_eoa(H5FD_t *_file, H5FD_mem_t type, haddr_t addr); -static haddr_t H5FD__mpio_get_eof(const H5FD_t *_file, H5FD_mem_t type); -static herr_t H5FD__mpio_get_handle(H5FD_t *_file, hid_t fapl, void **file_handle); -static herr_t H5FD__mpio_read(H5FD_t *_file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size, - void *buf); -static herr_t H5FD__mpio_write(H5FD_t *_file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size, - const void *buf); -static herr_t H5FD__mpio_flush(H5FD_t *_file, hid_t dxpl_id, hbool_t closing); -static herr_t H5FD__mpio_truncate(H5FD_t *_file, hid_t dxpl_id, hbool_t closing); -static herr_t H5FD__mpio_delete(const char *filename, hid_t fapl_id); -static int H5FD__mpio_mpi_rank(const H5FD_t *_file); -static int H5FD__mpio_mpi_size(const H5FD_t *_file); -static MPI_Comm H5FD__mpio_communicator(const H5FD_t *_file); +static herr_t H5FD__mpio_term(void); +static H5FD_t *H5FD__mpio_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr); +static herr_t H5FD__mpio_close(H5FD_t *_file); +static herr_t H5FD__mpio_query(const H5FD_t *_f1, unsigned long *flags); +static haddr_t H5FD__mpio_get_eoa(const H5FD_t *_file, H5FD_mem_t type); +static herr_t H5FD__mpio_set_eoa(H5FD_t *_file, H5FD_mem_t type, haddr_t addr); +static haddr_t H5FD__mpio_get_eof(const H5FD_t *_file, H5FD_mem_t type); +static herr_t H5FD__mpio_get_handle(H5FD_t *_file, hid_t fapl, void **file_handle); +static herr_t H5FD__mpio_read(H5FD_t *_file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size, + void *buf); +static herr_t H5FD__mpio_write(H5FD_t *_file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size, + const void *buf); +static herr_t H5FD__mpio_flush(H5FD_t *_file, hid_t dxpl_id, hbool_t closing); +static herr_t H5FD__mpio_truncate(H5FD_t *_file, hid_t dxpl_id, hbool_t closing); +static herr_t H5FD__mpio_delete(const char *filename, hid_t fapl_id); +static herr_t H5FD__mpio_ctl(H5FD_t *_file, uint64_t op_code, uint64_t flags, const void *input, + void **output); /* The MPIO file driver information */ -static const H5FD_class_mpi_t H5FD_mpio_g = { - { - /* Start of superclass information */ - "mpio", /* name */ - HADDR_MAX, /* maxaddr */ - H5F_CLOSE_SEMI, /* fc_degree */ - H5FD__mpio_term, /* terminate */ - NULL, /* sb_size */ - NULL, /* sb_encode */ - NULL, /* sb_decode */ - 0, /* fapl_size */ - NULL, /* fapl_get */ - NULL, /* fapl_copy */ - NULL, /* fapl_free */ - 0, /* dxpl_size */ - NULL, /* dxpl_copy */ - NULL, /* dxpl_free */ - H5FD__mpio_open, /* open */ - H5FD__mpio_close, /* close */ - NULL, /* cmp */ - H5FD__mpio_query, /* query */ - NULL, /* get_type_map */ - NULL, /* alloc */ - NULL, /* free */ - H5FD__mpio_get_eoa, /* get_eoa */ - H5FD__mpio_set_eoa, /* set_eoa */ - H5FD__mpio_get_eof, /* get_eof */ - H5FD__mpio_get_handle, /* get_handle */ - H5FD__mpio_read, /* read */ - H5FD__mpio_write, /* write */ - H5FD__mpio_flush, /* flush */ - H5FD__mpio_truncate, /* truncate */ - NULL, /* lock */ - NULL, /* unlock */ - H5FD__mpio_delete, /* del */ - H5FD_FLMAP_DICHOTOMY /* fl_map */ - }, /* End of superclass information */ - H5FD__mpio_mpi_rank, /* get_rank */ - H5FD__mpio_mpi_size, /* get_size */ - H5FD__mpio_communicator /* get_comm */ +static const H5FD_class_t H5FD_mpio_g = { + "mpio", /* name */ + HADDR_MAX, /* maxaddr */ + H5F_CLOSE_SEMI, /* fc_degree */ + H5FD__mpio_term, /* terminate */ + NULL, /* sb_size */ + NULL, /* sb_encode */ + NULL, /* sb_decode */ + 0, /* fapl_size */ + NULL, /* fapl_get */ + NULL, /* fapl_copy */ + NULL, /* fapl_free */ + 0, /* dxpl_size */ + NULL, /* dxpl_copy */ + NULL, /* dxpl_free */ + H5FD__mpio_open, /* open */ + H5FD__mpio_close, /* close */ + NULL, /* cmp */ + H5FD__mpio_query, /* query */ + NULL, /* get_type_map */ + NULL, /* alloc */ + NULL, /* free */ + H5FD__mpio_get_eoa, /* get_eoa */ + H5FD__mpio_set_eoa, /* set_eoa */ + H5FD__mpio_get_eof, /* get_eof */ + H5FD__mpio_get_handle, /* get_handle */ + H5FD__mpio_read, /* read */ + H5FD__mpio_write, /* write */ + H5FD__mpio_flush, /* flush */ + H5FD__mpio_truncate, /* truncate */ + NULL, /* lock */ + NULL, /* unlock */ + H5FD__mpio_delete, /* del */ + H5FD__mpio_ctl, /* ctl */ + H5FD_FLMAP_DICHOTOMY /* fl_map */ }; #ifdef H5FDmpio_DEBUG @@ -245,7 +239,7 @@ H5FD_mpio_init(void) /* Register the MPI-IO VFD, if it isn't already */ if (H5I_VFL != H5I_get_type(H5FD_MPIO_g)) - H5FD_MPIO_g = H5FD_register((const H5FD_class_t *)&H5FD_mpio_g, sizeof(H5FD_class_mpi_t), FALSE); + H5FD_MPIO_g = H5FD_register((const H5FD_class_t *)&H5FD_mpio_g, sizeof(H5FD_class_t), FALSE); if (!H5FD_mpio_Debug_inited) { const char *s; /* String for environment variables */ @@ -1802,83 +1796,78 @@ done: } /* end H5FD__mpio_delete() */ /*------------------------------------------------------------------------- - * Function: H5FD__mpio_mpi_rank + * Function: H5FD__mpio_ctl * - * Purpose: Returns the MPI rank for a process + * Purpose: MPIO version of the ctl callback. * - * Return: Success: non-negative - * Failure: negative + * The desired operation is specified by the op_code + * parameter. * - * Programmer: Quincey Koziol - * Thursday, May 16, 2002 + * The flags parameter controls management of op_codes that + * are unknown to the callback * - *------------------------------------------------------------------------- - */ -static int -H5FD__mpio_mpi_rank(const H5FD_t *_file) -{ - const H5FD_mpio_t *file = (const H5FD_mpio_t *)_file; - - FUNC_ENTER_STATIC_NOERR - - /* Sanity checks */ - HDassert(file); - HDassert(H5FD_MPIO == file->pub.driver_id); - - FUNC_LEAVE_NOAPI(file->mpi_rank) -} /* end H5FD__mpio_mpi_rank() */ - -/*------------------------------------------------------------------------- - * Function: H5FD__mpio_mpi_size + * The input and output parameters allow op_code specific + * input and output * - * Purpose: Returns the number of MPI processes + * At present, the supported op codes are: * - * Return: Success: non-negative - * Failure: negative + * H5FD_CTL__GET_MPI_COMMUNICATOR_OPCODE + * H5FD_CTL__GET_MPI_RANK_OPCODE + * H5FD_CTL__GET_MPI_SIZE_OPCODE * - * Programmer: Quincey Koziol - * Thursday, May 16, 2002 + * Note that these opcodes must be supported by all VFDs that + * support MPI. + * + * Return: Non-negative on success/Negative on failure + * + * Programmer: JRM -- 8/3/21 * *------------------------------------------------------------------------- */ -static int -H5FD__mpio_mpi_size(const H5FD_t *_file) +static herr_t +H5FD__mpio_ctl(H5FD_t *_file, uint64_t op_code, uint64_t flags, const void H5_ATTR_UNUSED *input, + void **output) { - const H5FD_mpio_t *file = (const H5FD_mpio_t *)_file; + H5FD_mpio_t *file = (H5FD_mpio_t *)_file; + herr_t ret_value = SUCCEED; /* Return value */ - FUNC_ENTER_STATIC_NOERR + FUNC_ENTER_NOAPI(FAIL) /* Sanity checks */ HDassert(file); HDassert(H5FD_MPIO == file->pub.driver_id); - FUNC_LEAVE_NOAPI(file->mpi_size) -} /* end H5FD__mpio_mpi_size() */ + switch (op_code) { -/*------------------------------------------------------------------------- - * Function: H5FD__mpio_communicator - * - * Purpose: Returns the MPI communicator for the file. - * - * Return: Success: The communicator - * Failure: Can't fail - * - * Programmer: Robb Matzke - * Monday, August 9, 1999 - * - *------------------------------------------------------------------------- - */ -static MPI_Comm -H5FD__mpio_communicator(const H5FD_t *_file) -{ - const H5FD_mpio_t *file = (const H5FD_mpio_t *)_file; + case H5FD_CTL__GET_MPI_COMMUNICATOR_OPCODE: + HDassert(output); + HDassert(*output); + **((MPI_Comm **)output) = file->comm; + break; - FUNC_ENTER_STATIC_NOERR + case H5FD_CTL__GET_MPI_RANK_OPCODE: + HDassert(output); + HDassert(*output); + **((int **)output) = file->mpi_rank; + break; - /* Sanity checks */ - HDassert(file); - HDassert(H5FD_MPIO == file->pub.driver_id); + case H5FD_CTL__GET_MPI_SIZE_OPCODE: + HDassert(output); + HDassert(*output); + **((int **)output) = file->mpi_size; + break; + + default: /* unknown op code */ + if (flags & H5FD_CTL__FAIL_IF_UNKNOWN_FLAG) { + + HGOTO_ERROR(H5E_VFL, H5E_FCNTL, FAIL, "unknown op_code and fail if unknown") + } + break; + } + +done: + + FUNC_LEAVE_NOAPI(ret_value) - FUNC_LEAVE_NOAPI(file->comm) -} /* end H5FD__mpio_communicator() */ +} /* end H5FD__mpio_ctl() */ #endif /* H5_HAVE_PARALLEL */ diff --git a/src/H5FDmulti.c b/src/H5FDmulti.c index 86f7664..0d1967d 100644 --- a/src/H5FDmulti.c +++ b/src/H5FDmulti.c @@ -44,7 +44,7 @@ #define my_strdup strdup #endif -/* Macros for enabling/disabling particular GCC warnings +/* Macros for enabling/disabling particular GCC / clang warnings * * These are (renamed) duplicates of macros in H5private.h. If you make changes * here, be sure to update those as well. @@ -166,6 +166,8 @@ static herr_t H5FD_multi_truncate(H5FD_t *_file, hid_t dxpl_id, hbool_t closing static herr_t H5FD_multi_lock(H5FD_t *_file, hbool_t rw); static herr_t H5FD_multi_unlock(H5FD_t *_file); static herr_t H5FD_multi_delete(const char *filename, hid_t fapl_id); +static herr_t H5FD_multi_ctl(H5FD_t *_file, uint64_t op_code, uint64_t flags, const void *input, + void **output); /* The class struct */ static const H5FD_class_t H5FD_multi_g = { @@ -201,6 +203,7 @@ static const H5FD_class_t H5FD_multi_g = { H5FD_multi_lock, /* lock */ H5FD_multi_unlock, /* unlock */ H5FD_multi_delete, /* del */ + H5FD_multi_ctl, /* ctl */ H5FD_FLMAP_DEFAULT /* fl_map */ }; @@ -646,7 +649,7 @@ H5FD_multi_sb_encode(H5FD_t *_file, char *name /*out*/, unsigned char *buf /*out H5Eclear2(H5E_DEFAULT); /* Name and version number */ - strncpy(name, "NCSAmulti", (size_t)8); + strncpy(name, "NCSAmult", (size_t)9); name[8] = '\0'; assert(7 == H5FD_MEM_NTYPES); @@ -682,7 +685,7 @@ H5FD_multi_sb_encode(H5FD_t *_file, char *name /*out*/, unsigned char *buf /*out p = buf + 8 + nseen * 2 * 8; UNIQUE_MEMBERS (file->fa.memb_map, mt) { size_t n = strlen(file->fa.memb_name[mt]) + 1; - strncpy((char *)p, file->fa.memb_name[mt], n); + strcpy((char *)p, file->fa.memb_name[mt]); p += n; for (i = n; i % 8; i++) *p++ = '\0'; @@ -2019,6 +2022,7 @@ open_members(H5FD_multi_t *file) return 0; } +H5_MULTI_GCC_DIAG_ON("format-nonliteral") /*------------------------------------------------------------------------- * Function: H5FD_multi_delete @@ -2029,6 +2033,7 @@ open_members(H5FD_multi_t *file) * *------------------------------------------------------------------------- */ +H5_MULTI_GCC_DIAG_OFF("format-nonliteral") static herr_t H5FD_multi_delete(const char *filename, hid_t fapl_id) { @@ -2068,6 +2073,54 @@ H5FD_multi_delete(const char *filename, hid_t fapl_id) } /* end H5FD_multi_delete() */ H5_MULTI_GCC_DIAG_ON("format-nonliteral") +/*------------------------------------------------------------------------- + * Function: H5FD_multi_ctl + * + * Purpose: Multi VFD version of the ctl callback. + * + * The desired operation is specified by the op_code + * parameter. + * + * The flags parameter controls management of op_codes that + * are unknown to the callback + * + * The input and output parameters allow op_code specific + * input and output + * + * At present, this VFD supports no op codes of its own. + * + * Return: Non-negative on success/Negative on failure + * + *------------------------------------------------------------------------- + */ +static herr_t +H5FD_multi_ctl(H5FD_t *_file, uint64_t op_code, uint64_t flags, const void *input, void **output) +{ + H5FD_multi_t * file = (H5FD_multi_t *)_file; + static const char *func = "H5FD_multi_ctl"; /* Function Name for error reporting */ + herr_t ret_value = 0; + + /* Silence compiler */ + (void)file; + (void)input; + (void)output; + + /* Clear the error stack */ + H5Eclear2(H5E_DEFAULT); + + switch (op_code) { + /* Unknown op code */ + default: + if (flags & H5FD_CTL__FAIL_IF_UNKNOWN_FLAG) + H5Epush_ret(func, H5E_ERR_CLS, H5E_VFL, H5E_FCNTL, + "VFD ctl request failed (unknown op code and fail if unknown flag is set)", -1); + + break; + } + + return ret_value; +} /* end H5FD_multi_ctl() */ + #ifdef H5private_H /* * This is not related to the functionality of the driver code. diff --git a/src/H5FDprivate.h b/src/H5FDprivate.h index c00c123..6dbd483 100644 --- a/src/H5FDprivate.h +++ b/src/H5FDprivate.h @@ -45,13 +45,6 @@ /* Definitions for file MPI type property */ #define H5FD_MPI_XFER_FILE_MPI_TYPE_NAME "H5FD_mpi_file_mpi_type" -/* Sub-class the H5FD_class_t to add more specific functions for MPI-based VFDs */ -typedef struct H5FD_class_mpi_t { - H5FD_class_t super; /* Superclass information & methods */ - int (*get_rank)(const H5FD_t *file); /* Get the MPI rank of a process */ - int (*get_size)(const H5FD_t *file); /* Get the MPI size of a communicator */ - MPI_Comm (*get_comm)(const H5FD_t *file); /* Get the communicator for a file */ -} H5FD_class_mpi_t; #endif /****************************/ @@ -137,6 +130,7 @@ H5_DLL herr_t H5FD_truncate(H5FD_t *file, hbool_t closing); H5_DLL herr_t H5FD_lock(H5FD_t *file, hbool_t rw); H5_DLL herr_t H5FD_unlock(H5FD_t *file); H5_DLL herr_t H5FD_delete(const char *name, hid_t fapl_id); +H5_DLL herr_t H5FD_ctl(H5FD_t *file, uint64_t op_code, uint64_t flags, const void *input, void **output); H5_DLL herr_t H5FD_get_fileno(const H5FD_t *file, unsigned long *filenum); H5_DLL herr_t H5FD_get_vfd_handle(H5FD_t *file, hid_t fapl, void **file_handle); H5_DLL herr_t H5FD_set_base_addr(H5FD_t *file, haddr_t base_addr); @@ -156,9 +150,9 @@ H5_DLL herr_t H5FD_set_mpio_atomicity(H5FD_t *file, hbool_t flag); H5_DLL herr_t H5FD_get_mpio_atomicity(H5FD_t *file, hbool_t *flag); /* Driver specific methods */ -H5_DLL int H5FD_mpi_get_rank(const H5FD_t *file); -H5_DLL int H5FD_mpi_get_size(const H5FD_t *file); -H5_DLL MPI_Comm H5FD_mpi_get_comm(const H5FD_t *_file); +H5_DLL int H5FD_mpi_get_rank(H5FD_t *file); +H5_DLL int H5FD_mpi_get_size(H5FD_t *file); +H5_DLL MPI_Comm H5FD_mpi_get_comm(H5FD_t *file); #endif /* H5_HAVE_PARALLEL */ #endif /* H5FDprivate_H */ diff --git a/src/H5FDpublic.h b/src/H5FDpublic.h index 0cfb072..b8f4f12 100644 --- a/src/H5FDpublic.h +++ b/src/H5FDpublic.h @@ -138,6 +138,77 @@ */ #define H5FD_FEAT_DEFAULT_VFD_COMPATIBLE 0x00008000 +/* ctl function definitions: */ +#define H5FD_CTL_OPC_RESERVED 512 /* Opcodes below this value are reserved for library use */ +#define H5FD_CTL_OPC_EXPER_MIN \ + H5FD_CTL_OPC_RESERVED /* Minimum opcode value available for experimental use \ + */ +#define H5FD_CTL_OPC_EXPER_MAX \ + (H5FD_CTL_OPC_RESERVED + 511) /* Maximum opcode value available for experimental use */ + +/* ctl function op codes: */ +#define H5FD_CTL__INVALID_OPCODE 0 +#define H5FD_CTL__TEST_OPCODE 1 +#define H5FD_CTL__GET_MPI_COMMUNICATOR_OPCODE 2 +#define H5FD_CTL__GET_MPI_RANK_OPCODE 3 +#define H5FD_CTL__GET_MPI_SIZE_OPCODE 4 + +/* ctl function flags: */ + +/* Definitions: + * + * WARNING: While the following definitions of Terminal + * and Passthrough VFDs should be workable for now, they + * have to be adjusted as our use cases for VFDs expand. + * + * JRM -- 8/4/21 + * + * + * Terminal VFD: Lowest VFD in the VFD stack through + * which all VFD calls pass. Note that this definition + * is situational. For example, the sec2 VFD is typically + * terminal. However, in the context of the family file + * driver, it is not -- the family file driver is the + * bottom VFD through which all VFD calls pass, and thus + * it is terminal. + * + * Similarly, on the splitter VFD, a sec2 VFD on the + * R/W channel is terminal, but a sec2 VFD on the W/O + * channel is not. + * + * + * Pass through VFD: Any VFD that relays all VFD calls + * (with the possible exception of some non-I/O related + * calls) to underlying VFD(s). + */ + +/* Unknown op codes should be ignored silently unless the + * H5FD_CTL__FAIL_IF_UNKNOWN_FLAG is set. + * + * On terminal VFDs, unknown op codes should generate an + * error unconditionally if this flag is set. + * + * On pass through VFDs, unknown op codes should be routed + * to the underlying VFD(s) as indicated by any routing + * flags. In the absence of such flags, the VFD should + * generate an error. + */ +#define H5FD_CTL__FAIL_IF_UNKNOWN_FLAG 0x0001 + +/* The H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG is used only + * by non-ternminal VFDs, and only applies to unknown + * opcodes. (known op codes should be handled as + * appropriate.) + * + * If this flag is set for an uknown op code, that + * op code should be passed to the next VFD down + * the VFD stack en-route to the terminal VFD. + * If that VFD does not support the ctl call, the + * pass through VFD should fail or succeed as directed + * by the H5FD_CTL__FAIL_IF_UNKNOWN_FLAG. + */ +#define H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG 0x0002 + /*******************/ /* Public Typedefs */ /*******************/ diff --git a/src/H5FDros3.c b/src/H5FDros3.c index c0361f9..a32d65e 100644 --- a/src/H5FDros3.c +++ b/src/H5FDros3.c @@ -269,6 +269,7 @@ static const H5FD_class_t H5FD_ros3_g = { NULL, /* lock */ NULL, /* unlock */ NULL, /* del */ + NULL, /* ctl */ H5FD_FLMAP_DICHOTOMY /* fl_map */ }; diff --git a/src/H5FDsec2.c b/src/H5FDsec2.c index d823e3c..15103da 100644 --- a/src/H5FDsec2.c +++ b/src/H5FDsec2.c @@ -139,6 +139,8 @@ static herr_t H5FD__sec2_truncate(H5FD_t *_file, hid_t dxpl_id, hbool_t closing static herr_t H5FD__sec2_lock(H5FD_t *_file, hbool_t rw); static herr_t H5FD__sec2_unlock(H5FD_t *_file); static herr_t H5FD__sec2_delete(const char *filename, hid_t fapl_id); +static herr_t H5FD__sec2_ctl(H5FD_t *_file, uint64_t op_code, uint64_t flags, const void *input, + void **output); static const H5FD_class_t H5FD_sec2_g = { "sec2", /* name */ @@ -173,6 +175,7 @@ static const H5FD_class_t H5FD_sec2_g = { H5FD__sec2_lock, /* lock */ H5FD__sec2_unlock, /* unlock */ H5FD__sec2_delete, /* del */ + H5FD__sec2_ctl, /* ctl */ H5FD_FLMAP_DICHOTOMY /* fl_map */ }; @@ -1068,3 +1071,48 @@ H5FD__sec2_delete(const char *filename, hid_t H5_ATTR_UNUSED fapl_id) done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5FD__sec2_delete() */ + +/*------------------------------------------------------------------------- + * Function: H5FD__sec2_ctl + * + * Purpose: Sec2 VFD version of the ctl callback. + * + * The desired operation is specified by the op_code + * parameter. + * + * The flags parameter controls management of op_codes that + * are unknown to the callback + * + * The input and output parameters allow op_code specific + * input and output + * + * At present, no op codes are supported by this VFD. + * + * Return: Non-negative on success/Negative on failure + * + *------------------------------------------------------------------------- + */ +static herr_t +H5FD__sec2_ctl(H5FD_t *_file, uint64_t op_code, uint64_t flags, const void H5_ATTR_UNUSED *input, + void H5_ATTR_UNUSED **output) +{ + H5FD_sec2_t *file = (H5FD_sec2_t *)_file; + herr_t ret_value = SUCCEED; + + FUNC_ENTER_STATIC + + /* Sanity checks */ + HDassert(file); + HDassert(H5FD_SEC2 == file->pub.driver_id); + + switch (op_code) { + /* Unknown op code */ + default: + if (flags & H5FD_CTL__FAIL_IF_UNKNOWN_FLAG) + HGOTO_ERROR(H5E_VFL, H5E_FCNTL, FAIL, "unknown op_code and fail if unknown flag is set") + break; + } + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5FD__sec2_ctl() */ diff --git a/src/H5FDsplitter.c b/src/H5FDsplitter.c index c27cd1b..3113e8b 100644 --- a/src/H5FDsplitter.c +++ b/src/H5FDsplitter.c @@ -129,6 +129,8 @@ static herr_t H5FD__splitter_flush(H5FD_t *_file, hid_t dxpl_id, hbool_t closin static herr_t H5FD__splitter_truncate(H5FD_t *_file, hid_t dxpl_id, hbool_t closing); static herr_t H5FD__splitter_lock(H5FD_t *_file, hbool_t rw); static herr_t H5FD__splitter_unlock(H5FD_t *_file); +static herr_t H5FD__splitter_ctl(H5FD_t *_file, uint64_t op_code, uint64_t flags, const void *input, + void **output); static const H5FD_class_t H5FD_splitter_g = { "splitter", /* name */ @@ -163,6 +165,7 @@ static const H5FD_class_t H5FD_splitter_g = { H5FD__splitter_lock, /* lock */ H5FD__splitter_unlock, /* unlock */ NULL, /* del */ + H5FD__splitter_ctl, /* ctl */ H5FD_FLMAP_DICHOTOMY /* fl_map */ }; @@ -340,10 +343,12 @@ H5Pset_fapl_splitter(hid_t fapl_id, H5FD_splitter_vfd_config_t *vfd_config) HGOTO_ERROR(H5E_VFL, H5E_CANTALLOC, FAIL, "unable to allocate file access property list struct") info->ignore_wo_errs = vfd_config->ignore_wo_errs; - HDstrncpy(info->wo_path, vfd_config->wo_path, H5FD_SPLITTER_PATH_MAX); - HDstrncpy(info->log_file_path, vfd_config->log_file_path, H5FD_SPLITTER_PATH_MAX); - info->rw_fapl_id = H5P_FILE_ACCESS_DEFAULT; /* pre-set value */ - info->wo_fapl_id = H5P_FILE_ACCESS_DEFAULT; /* pre-set value */ + HDstrncpy(info->wo_path, vfd_config->wo_path, H5FD_SPLITTER_PATH_MAX + 1); + info->wo_path[H5FD_SPLITTER_PATH_MAX] = '\0'; + HDstrncpy(info->log_file_path, vfd_config->log_file_path, H5FD_SPLITTER_PATH_MAX + 1); + info->log_file_path[H5FD_SPLITTER_PATH_MAX] = '\0'; + info->rw_fapl_id = H5P_FILE_ACCESS_DEFAULT; /* pre-set value */ + info->wo_fapl_id = H5P_FILE_ACCESS_DEFAULT; /* pre-set value */ /* Set non-default channel FAPL IDs in splitter configuration info */ if (H5P_DEFAULT != vfd_config->rw_fapl_id) { @@ -412,8 +417,8 @@ H5Pget_fapl_splitter(hid_t fapl_id, H5FD_splitter_vfd_config_t *config /*out*/) if (NULL == (fapl_ptr = (const H5FD_splitter_fapl_t *)H5P_peek_driver_info(plist_ptr))) HGOTO_ERROR(H5E_PLIST, H5E_BADVALUE, FAIL, "unable to get specific-driver info") - HDstrncpy(config->wo_path, fapl_ptr->wo_path, H5FD_SPLITTER_PATH_MAX); - HDstrncpy(config->log_file_path, fapl_ptr->log_file_path, H5FD_SPLITTER_PATH_MAX); + HDstrncpy(config->wo_path, fapl_ptr->wo_path, H5FD_SPLITTER_PATH_MAX + 1); + HDstrncpy(config->log_file_path, fapl_ptr->log_file_path, H5FD_SPLITTER_PATH_MAX + 1); config->ignore_wo_errs = fapl_ptr->ignore_wo_errs; /* Copy R/W and W/O FAPLs */ @@ -587,8 +592,8 @@ H5FD__splitter_fapl_copy(const void *_old_fa) HGOTO_ERROR(H5E_VFL, H5E_CANTALLOC, NULL, "unable to allocate log file FAPL") H5MM_memcpy(new_fa_ptr, old_fa_ptr, sizeof(H5FD_splitter_fapl_t)); - HDstrncpy(new_fa_ptr->wo_path, old_fa_ptr->wo_path, H5FD_SPLITTER_PATH_MAX); - HDstrncpy(new_fa_ptr->log_file_path, old_fa_ptr->log_file_path, H5FD_SPLITTER_PATH_MAX); + HDstrncpy(new_fa_ptr->wo_path, old_fa_ptr->wo_path, H5FD_SPLITTER_PATH_MAX + 1); + HDstrncpy(new_fa_ptr->log_file_path, old_fa_ptr->log_file_path, H5FD_SPLITTER_PATH_MAX + 1); /* Copy R/W and W/O FAPLs */ if (H5FD__copy_plist(old_fa_ptr->rw_fapl_id, &(new_fa_ptr->rw_fapl_id)) < 0) @@ -688,8 +693,8 @@ H5FD__splitter_open(const char *name, unsigned flags, hid_t splitter_fapl_id, ha HGOTO_ERROR(H5E_PLIST, H5E_CANTGET, NULL, "unable to get VFL driver info") /* Copy simpler info */ - HDstrncpy(file_ptr->fa.wo_path, fapl_ptr->wo_path, H5FD_SPLITTER_PATH_MAX); - HDstrncpy(file_ptr->fa.log_file_path, fapl_ptr->log_file_path, H5FD_SPLITTER_PATH_MAX); + HDstrncpy(file_ptr->fa.wo_path, fapl_ptr->wo_path, H5FD_SPLITTER_PATH_MAX + 1); + HDstrncpy(file_ptr->fa.log_file_path, fapl_ptr->log_file_path, H5FD_SPLITTER_PATH_MAX + 1); file_ptr->fa.ignore_wo_errs = fapl_ptr->ignore_wo_errs; /* Copy R/W and W/O channel FAPLs. */ @@ -1143,6 +1148,63 @@ done: } /* end H5FD__splitter_unlock */ /*------------------------------------------------------------------------- + * Function: H5FD__splitter_ctl + * + * Purpose: Splitter VFD version of the ctl callback. + * + * The desired operation is specified by the op_code + * parameter. + * + * The flags parameter controls management of op_codes that + * are unknown to the callback + * + * The input and output parameters allow op_code specific + * input and output + * + * At present, this VFD supports no op codes of its own and + * simply passes ctl calls on to the R/W channel VFD. + * + * Return: Non-negative on success/Negative on failure + * + *------------------------------------------------------------------------- + */ +static herr_t +H5FD__splitter_ctl(H5FD_t *_file, uint64_t op_code, uint64_t flags, const void *input, void **output) +{ + H5FD_splitter_t *file = (H5FD_splitter_t *)_file; + herr_t ret_value = SUCCEED; + + FUNC_ENTER_STATIC + + /* Sanity checks */ + HDassert(file); + HDassert(H5FD_SPLITTER == file->pub.driver_id); + + switch (op_code) { + /* Unknown op code */ + default: + if (flags & H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG) { + /* Pass ctl call down to R/W channel VFD */ + if (H5FDctl(file->rw_file, op_code, flags, input, output) < 0) + HGOTO_ERROR(H5E_VFL, H5E_FCNTL, FAIL, "VFD ctl request failed") + } + else { + /* If no valid VFD routing flag is specified, fail for unknown op code + * if H5FD_CTL__FAIL_IF_UNKNOWN_FLAG flag is set. + */ + if (flags & H5FD_CTL__FAIL_IF_UNKNOWN_FLAG) + HGOTO_ERROR(H5E_VFL, H5E_FCNTL, FAIL, + "VFD ctl request failed (unknown op code and fail if unknown flag is set)") + } + + break; + } + +done: + FUNC_LEAVE_NOAPI(ret_value) +} /* end H5FD__splitter_ctl() */ + +/*------------------------------------------------------------------------- * Function: H5FD__splitter_query * * Purpose: Set the flags that this VFL driver is capable of supporting. diff --git a/src/H5FDstdio.c b/src/H5FDstdio.c index 6631325..312263c 100644 --- a/src/H5FDstdio.c +++ b/src/H5FDstdio.c @@ -215,6 +215,7 @@ static const H5FD_class_t H5FD_stdio_g = { H5FD_stdio_lock, /* lock */ H5FD_stdio_unlock, /* unlock */ H5FD_stdio_delete, /* del */ + NULL, /* ctl */ H5FD_FLMAP_DICHOTOMY /* fl_map */ }; diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h index 7f0299a..81c1ede 100644 --- a/src/H5Fmodule.h +++ b/src/H5Fmodule.h @@ -29,8 +29,7 @@ #define H5_MY_PKG_ERR H5E_FILE #define H5_MY_PKG_INIT YES -/** - * \defgroup H5F H5F +/**\defgroup H5F H5F * * Use the functions in this module to manage HDF5 files. * @@ -41,15 +40,23 @@ * creation or access \c mode control the interaction with the underlying * storage such as file systems. * - * \Emph{Proper error handling is part of the life cycle.} * <table> - * <tr><th>Create</th><th>Open</th></tr> + * <tr><th>Create</th><th>Read</th></tr> * <tr valign="top"> * <td> - * \snippet H5F_examples.c life_cycle + * \snippet{lineno} H5F_examples.c create * </td> * <td> - * \snippet H5F_examples.c life_cycle_w_open + * \snippet{lineno} H5F_examples.c read + * </td> + * </tr> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5F_examples.c update + * </td> + * <td> + * \snippet{lineno} H5F_examples.c delete * </td> * </tr> * </table> diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h index 98d2a9f..c3230e1 100644 --- a/src/H5Fpublic.h +++ b/src/H5Fpublic.h @@ -1777,6 +1777,7 @@ H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag); H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); #endif /* H5_HAVE_PARALLEL */ +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -1796,6 +1797,7 @@ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); #define H5Fflush_async_wrap H5_NO_EXPAND(H5Fflush_async) #define H5Fclose_async_wrap H5_NO_EXPAND(H5Fclose_async) #endif /* H5F_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * diff --git a/src/H5Fsuper.c b/src/H5Fsuper.c index e7a3b53..4df0064 100644 --- a/src/H5Fsuper.c +++ b/src/H5Fsuper.c @@ -1043,7 +1043,7 @@ done: HDONE_ERROR(H5E_FILE, H5E_CANTUNPIN, FAIL, "unable to unpin driver info") /* Evict the driver info block from the cache */ - if (H5AC_expunge_entry(f, H5AC_DRVRINFO, sblock->driver_addr, H5AC__NO_FLAGS_SET) < 0) + if (sblock && H5AC_expunge_entry(f, H5AC_DRVRINFO, sblock->driver_addr, H5AC__NO_FLAGS_SET) < 0) HDONE_ERROR(H5E_FILE, H5E_CANTEXPUNGE, FAIL, "unable to expunge driver info block") } /* end if */ diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h index fe26bd2..a0e121d 100644 --- a/src/H5Gmodule.h +++ b/src/H5Gmodule.h @@ -29,8 +29,29 @@ #define H5_MY_PKG_ERR H5E_SYM #define H5_MY_PKG_INIT YES -/** - * \defgroup H5G H5G +/** \defgroup H5G H5G + * + * Use the functions in this module to manage HDF5 groups. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5G_examples.c create + * </td> + * <td> + * \snippet{lineno} H5G_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5G_examples.c update + * </td> + * <td> + * \snippet{lineno} H5G_examples.c delete + * </td> + * </tr> + * </table> * * \details \Bold{Groups in HDF5:} A group associates names with objects and * provides a mechanism for mapping a name to an object. Since all diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h index b009d41..d9c29f6 100644 --- a/src/H5Gpublic.h +++ b/src/H5Gpublic.h @@ -467,6 +467,7 @@ H5_DLL herr_t H5Gclose(hid_t group_id); H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t group_id, hid_t es_id); +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -488,6 +489,7 @@ H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigne #define H5Gget_info_by_idx_async_wrap H5_NO_EXPAND(H5Gget_info_by_idx_async) #define H5Gclose_async_wrap H5_NO_EXPAND(H5Gclose_async) #endif /* H5G_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * diff --git a/src/H5Idbg.c b/src/H5Idbg.c index 7b5eb5a..8bf8ecb 100644 --- a/src/H5Idbg.c +++ b/src/H5Idbg.c @@ -110,9 +110,9 @@ H5I__id_dump_cb(void *_item, void H5_ATTR_UNUSED *_key, void *_udata) case H5I_DATATYPE: { const H5T_t *dt = (const H5T_t *)info->object; - H5_GCC_DIAG_OFF("cast-qual") + H5_GCC_CLANG_DIAG_OFF("cast-qual") object = (void *)H5T_get_actual_type((H5T_t *)dt); /* Casting away const OK - QAK */ - H5_GCC_DIAG_ON("cast-qual") + H5_GCC_CLANG_DIAG_ON("cast-qual") path = H5T_nameof((const H5T_t *)object); break; diff --git a/src/H5Iint.c b/src/H5Iint.c index 164fafc..86a2810 100644 --- a/src/H5Iint.c +++ b/src/H5Iint.c @@ -391,7 +391,7 @@ H5I__mark_node(void *_info, void H5_ATTR_UNUSED *key, void *_udata) */ if (udata->force || (info->count - (!udata->app_ref * info->app_count)) <= 1) { /* Check if this is an un-realized future object */ - H5_GCC_DIAG_OFF("cast-qual") + H5_GCC_CLANG_DIAG_OFF("cast-qual") if (info->is_future) { /* Discard the future object */ if ((info->discard_cb)((void *)info->object) < 0) { @@ -437,7 +437,7 @@ H5I__mark_node(void *_info, void H5_ATTR_UNUSED *key, void *_udata) mark = TRUE; } } - H5_GCC_DIAG_ON("cast-qual") + H5_GCC_CLANG_DIAG_ON("cast-qual") /* Remove ID if requested */ if (mark) { @@ -705,9 +705,9 @@ H5I_subst(hid_t id, const void *new_object) HGOTO_ERROR(H5E_ID, H5E_NOTFOUND, NULL, "can't get ID ref count") /* Get the old object pointer to return */ - H5_GCC_DIAG_OFF("cast-qual") + H5_GCC_CLANG_DIAG_OFF("cast-qual") ret_value = (void *)info->object; /* (Casting away const OK -QAK) */ - H5_GCC_DIAG_ON("cast-qual") + H5_GCC_CLANG_DIAG_ON("cast-qual") /* Set the new object pointer for the ID */ info->object = new_object; @@ -739,9 +739,9 @@ H5I_object(hid_t id) /* General lookup of the ID */ if (NULL != (info = H5I__find_id(id))) { /* Get the object pointer to return */ - H5_GCC_DIAG_OFF("cast-qual") + H5_GCC_CLANG_DIAG_OFF("cast-qual") ret_value = (void *)info->object; /* (Casting away const OK -QAK) */ - H5_GCC_DIAG_ON("cast-qual") + H5_GCC_CLANG_DIAG_ON("cast-qual") } FUNC_LEAVE_NOAPI(ret_value) @@ -775,9 +775,9 @@ H5I_object_verify(hid_t id, H5I_type_t type) /* Verify that the type of the ID is correct & lookup the ID */ if (type == H5I_TYPE(id) && NULL != (info = H5I__find_id(id))) { /* Get the object pointer to return */ - H5_GCC_DIAG_OFF("cast-qual") + H5_GCC_CLANG_DIAG_OFF("cast-qual") ret_value = (void *)info->object; /* (Casting away const OK -QAK) */ - H5_GCC_DIAG_ON("cast-qual") + H5_GCC_CLANG_DIAG_ON("cast-qual") } FUNC_LEAVE_NOAPI(ret_value) @@ -938,9 +938,9 @@ H5I__remove_common(H5I_type_info_t *type_info, hid_t id) if (type_info->last_id_info == info) type_info->last_id_info = NULL; - H5_GCC_DIAG_OFF("cast-qual") + H5_GCC_CLANG_DIAG_OFF("cast-qual") ret_value = (void *)info->object; /* (Casting away const OK -QAK) */ - H5_GCC_DIAG_ON("cast-qual") + H5_GCC_CLANG_DIAG_ON("cast-qual") if (!H5I_marking_g) info = H5FL_FREE(H5I_id_info_t, info); @@ -1040,7 +1040,7 @@ H5I__dec_ref(hid_t id, void **request) /* Get the ID's type */ type_info = H5I_type_info_array_g[H5I_TYPE(id)]; - H5_GCC_DIAG_OFF("cast-qual") + H5_GCC_CLANG_DIAG_OFF("cast-qual") /* (Casting away const OK -QAK) */ if (!type_info->cls->free_func || (type_info->cls->free_func)((void *)info->object, request) >= 0) { /* Remove the node from the type */ @@ -1050,7 +1050,7 @@ H5I__dec_ref(hid_t id, void **request) } /* end if */ else ret_value = -1; - H5_GCC_DIAG_ON("cast-qual") + H5_GCC_CLANG_DIAG_ON("cast-qual") } /* end if */ else { --(info->count); @@ -1529,9 +1529,9 @@ H5I__iterate_cb(void *_item, void H5_ATTR_UNUSED *_key, void *_udata) /* The stored object pointer might be an H5VL_object_t, in which * case we'll need to get the wrapped object struct (H5F_t *, etc.). */ - H5_GCC_DIAG_OFF("cast-qual") + H5_GCC_CLANG_DIAG_OFF("cast-qual") object = H5I__unwrap((void *)info->object, type); /* Casting away const OK */ - H5_GCC_DIAG_ON("cast-qual") + H5_GCC_CLANG_DIAG_ON("cast-qual") /* Invoke callback function */ cb_ret_val = (*udata->user_func)((void *)object, info->id, udata->user_udata); @@ -1654,7 +1654,7 @@ H5I__find_id(hid_t id) } /* Check if this is a future ID */ - H5_GCC_DIAG_OFF("cast-qual") + H5_GCC_CLANG_DIAG_OFF("cast-qual") if (id_info && id_info->is_future) { hid_t actual_id = H5I_INVALID_HID; /* ID for actual object */ void *future_object; /* Pointer to the future object */ @@ -1686,7 +1686,7 @@ H5I__find_id(hid_t id) id_info->realize_cb = NULL; id_info->discard_cb = NULL; } - H5_GCC_DIAG_ON("cast-qual") + H5_GCC_CLANG_DIAG_ON("cast-qual") /* Set return value */ ret_value = id_info; @@ -1721,9 +1721,9 @@ H5I__find_id_cb(void *_item, void H5_ATTR_UNUSED *_key, void *_udata) HDassert(udata); /* Get a pointer to the VOL connector's data */ - H5_GCC_DIAG_OFF("cast-qual") + H5_GCC_CLANG_DIAG_OFF("cast-qual") object = H5I__unwrap((void *)info->object, type); /* Casting away const OK */ - H5_GCC_DIAG_ON("cast-qual") + H5_GCC_CLANG_DIAG_ON("cast-qual") /* Check for a match */ if (object == udata->object) { diff --git a/src/H5Imodule.h b/src/H5Imodule.h index 8db31c8..08f8bb0 100644 --- a/src/H5Imodule.h +++ b/src/H5Imodule.h @@ -30,8 +30,85 @@ #define H5_MY_PKG_INIT NO /**\defgroup H5I H5I - * \brief Identifier Interface - * \todo Describe concisely what the functions in this module are about. + * + * Use the functions in this module to manage identifiers defined by the HDF5 + * library. See \ref H5IUD for user-defined identifiers and identifier + * types. + * + * HDF5 identifiers are usually created as a side-effect of creating HDF5 + * entities such as groups, datasets, attributes, or property lists. + * + * Identifiers defined by the HDF5 library can be used to retrieve information + * such as path names and reference counts, and their validity can be checked. + * + * Identifiers can be updated by manipulating their reference counts. + * + * Unused identifiers should be reclaimed by closing the associated item, e.g., + * HDF5 object, or decrementing the reference count to 0. + * + * \note Identifiers (of type \ref hid_t) are run-time auxiliaries and + * not persisted in the file. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5I_examples.c create + * </td> + * <td> + * \snippet{lineno} H5I_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5I_examples.c update + * </td> + * <td> + * \snippet{lineno} H5I_examples.c delete + * </td> + * </tr> + * </table> + * + * \defgroup H5IUD User-defined ID Types + * \ingroup H5I + * + * The \ref H5I module contains functions to define new identifier types. + * For convenience, handles of type \ref hid_t can then be associated with the + * new identifier types and user objects. + * + * New identifier types can be created by registering a new identifier type + * with the HDF5 library. Once a new identifier type has bee registered, + * it can be used to generate identifiers for user objects. + * + * User-defined identifier types can be searched and iterated. + * + * Like library-defined identifiers, user-defined identifiers \Emph{and} + * identifier types are reference counted, and the reference counts can be + * manipulated accordingly. + * + * User-defined identifiers no longer in use should be deleted or reclaimed, + * and identifier types should be destroyed if they are no longer required. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5I_examples.c create_ud + * </td> + * <td> + * \snippet{lineno} H5I_examples.c read_ud + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5I_examples.c update_ud + * </td> + * <td> + * \snippet{lineno} H5I_examples.c delete_ud + * </td> + * </tr> + * </table> + * */ #endif /* H5Imodule_H */ diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h index a5f830b..8d4dbf8 100644 --- a/src/H5Ipublic.h +++ b/src/H5Ipublic.h @@ -106,7 +106,7 @@ extern "C" { /* Public API functions */ /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Registers an object under a type and returns an ID for it * @@ -128,7 +128,7 @@ extern "C" { */ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Returns the object referenced by an ID * @@ -151,7 +151,7 @@ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); */ H5_DLL void *H5Iobject_verify(hid_t id, H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Removes an ID from its type * @@ -190,12 +190,7 @@ H5_DLL void *H5Iremove_verify(hid_t id, H5I_type_t type); * \return Returns the object type if successful; otherwise #H5I_BADID. * * \details H5Iget_type() retrieves the type of the object identified by - * \p id. - * - * Valid types returned by the function are: - * \id_types - * - * If no valid type can be determined or the identifier submitted is + * \p id. If no valid type can be determined or the identifier submitted is * invalid, the function returns #H5I_BADID. * * This function is of particular use in determining the type of @@ -391,7 +386,7 @@ H5_DLL int H5Idec_ref(hid_t id); */ H5_DLL int H5Iget_ref(hid_t id); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Creates and returns a new ID type * @@ -423,7 +418,7 @@ H5_DLL int H5Iget_ref(hid_t id); */ H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Deletes all identifiers of the given type * @@ -447,7 +442,7 @@ H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free */ H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Removes an identifier type and all identifiers within that type * @@ -470,7 +465,7 @@ H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); */ H5_DLL herr_t H5Idestroy_type(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Increments the reference count on an ID type * @@ -489,7 +484,7 @@ H5_DLL herr_t H5Idestroy_type(H5I_type_t type); */ H5_DLL int H5Iinc_type_ref(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Decrements the reference count on an identifier type * @@ -509,7 +504,7 @@ H5_DLL int H5Iinc_type_ref(H5I_type_t type); */ H5_DLL int H5Idec_type_ref(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Retrieves the reference count on an ID type * @@ -528,7 +523,7 @@ H5_DLL int H5Idec_type_ref(H5I_type_t type); */ H5_DLL int H5Iget_type_ref(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Finds the memory referred to by an ID within the given ID type such * that some criterion is satisfied @@ -569,7 +564,7 @@ H5_DLL int H5Iget_type_ref(H5I_type_t type); */ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Calls a callback for each member of the identifier type specified * @@ -598,7 +593,7 @@ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); */ H5_DLL herr_t H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Returns the number of identifiers in a given identifier type * @@ -618,7 +613,7 @@ H5_DLL herr_t H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data); */ H5_DLL herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Determines whether an identifier type is registered * diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h index 16f1f34..cffd25c 100644 --- a/src/H5Lmodule.h +++ b/src/H5Lmodule.h @@ -30,8 +30,29 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5L H5L - * \brief Link Interface - * \todo Describe concisely what the functions in this module are about. + * + * Use the functions in this module to manage HDF5 links and link types. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5L_examples.c create + * </td> + * <td> + * \snippet{lineno} H5L_examples.c iter_cb + * \snippet{lineno} H5L_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5L_examples.c update + * </td> + * <td> + * \snippet{lineno} H5L_examples.c delete + * </td> + * </tr> + * </table> * * \defgroup TRAV Link Traversal * \ingroup H5L diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h index f665526..72b0182 100644 --- a/src/H5Lpublic.h +++ b/src/H5Lpublic.h @@ -1380,6 +1380,7 @@ H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_si H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id); +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -1401,6 +1402,7 @@ H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hi #define H5Lexists_async_wrap H5_NO_EXPAND(H5Lexists_async) #define H5Literate_async_wrap H5_NO_EXPAND(H5Literate_async) #endif /* H5L_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * diff --git a/src/H5Mmodule.h b/src/H5Mmodule.h index 3dae3e2..848f63f 100644 --- a/src/H5Mmodule.h +++ b/src/H5Mmodule.h @@ -26,9 +26,9 @@ #define H5_MY_PKG_ERR H5E_MAP #define H5_MY_PKG_INIT YES -/** - * \defgroup H5M H5M - * \brief Map Interface +/**\defgroup H5M H5M + * + * \todo Describe the map life cycle. * * \details \Bold{The interface can only be used with the HDF5 VOL connectors that * implement map objects.} The native HDF5 library does not support this diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h index b3a0903..3f94edb 100644 --- a/src/H5Mpublic.h +++ b/src/H5Mpublic.h @@ -588,6 +588,7 @@ H5_DLL herr_t H5Miterate_by_name(hid_t loc_id, const char *map_name, hsize_t *id */ H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t dxpl_id); +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -606,6 +607,7 @@ H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hi #define H5Mput_async_wrap H5_NO_EXPAND(H5Mput_async) #define H5Mget_async_wrap H5_NO_EXPAND(H5Mget_async) #endif /* H5M_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * diff --git a/src/H5Omodule.h b/src/H5Omodule.h index 134aa92..8afba29 100644 --- a/src/H5Omodule.h +++ b/src/H5Omodule.h @@ -30,9 +30,46 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5O H5O - * \brief Object Interface * - * \todo Describe concisely what the functions in this module are about. + * Use the functions in this module to manage HDF5 objects. + * + * HDF5 objects (groups, datasets, datatype objects) are usually created + * using functions in the object-specific modules (\ref H5G, \ref H5D, + * \ref H5T). However, new objects can also be created by copying existing + * objects. + * + * Many functions in this module are variations on object introspection, + * that is, the retrieval of detailed information about HDF5 objects in a file. + * Objects in an HDF5 file can be "visited" in an iterative fashion. + * + * HDF5 objects are usually updated using functions in the object-specific + * modules. However, there are certain generic object properties, such as + * reference counts, that can be manipulated using functions in this module. + * + * HDF5 objects are deleted as a side effect of rendering them unreachable + * from the root group. The net effect is the diminution of the object's + * reference count to zero, which can (but should not usually) be effected + * by a function in this module. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5O_examples.c create + * </td> + * <td> + * \snippet{lineno} H5O_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5O_examples.c update + * </td> + * <td> + * \snippet{lineno} H5O_examples.c delete + * </td> + * </tr> + * </table> * */ #endif /* H5Omodule_H */ diff --git a/src/H5Opublic.h b/src/H5Opublic.h index 7bc7784..d9d0500 100644 --- a/src/H5Opublic.h +++ b/src/H5Opublic.h @@ -35,14 +35,14 @@ /*****************/ /* Flags for object copy (H5Ocopy) */ -#define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /* Copy only immediate members */ -#define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /* Expand soft links into new objects */ -#define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /* Expand external links into new objects */ -#define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /* Copy objects that are pointed by references */ -#define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /* Copy object without copying attributes */ -#define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /* Copy NULL messages (empty space) */ -#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /* Merge committed datatypes in dest file */ -#define H5O_COPY_ALL (0x007Fu) /* All object copying flags (for internal checking) */ +#define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /**< Copy only immediate members */ +#define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /**< Expand soft links into new objects */ +#define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /**< Expand external links into new objects */ +#define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /**< Copy objects that are pointed by references */ +#define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /**< Copy object without copying attributes */ +#define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /**< Copy NULL messages (empty space) */ +#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /**< Merge committed datatypes in dest file */ +#define H5O_COPY_ALL (0x007Fu) /**< All object copying flags (for internal checking) */ /* Flags for shared message indexes. * Pass these flags in using the mesg_type_flags parameter in @@ -51,25 +51,27 @@ * but we need to assign each kind of message to a different bit so that * one index can hold multiple types.) */ -#define H5O_SHMESG_NONE_FLAG 0x0000 /* No shared messages */ -#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /* Simple Dataspace Message. */ -#define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /* Datatype Message. */ -#define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /* Fill Value Message. */ -#define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /* Filter pipeline message. */ -#define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /* Attribute Message. */ +#define H5O_SHMESG_NONE_FLAG 0x0000 /**< No shared messages */ +#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /**< Simple Dataspace Message. */ +#define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /**< Datatype Message. */ +#define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /**< Fill Value Message. */ +#define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /**< Filter pipeline message. */ +#define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /**< Attribute Message. */ #define H5O_SHMESG_ALL_FLAG \ (H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG | \ H5O_SHMESG_ATTR_FLAG) +/* clang-format off */ /* Object header status flag definitions */ -#define H5O_HDR_CHUNK0_SIZE 0x03 /* 2-bit field indicating # of bytes to store the size of chunk 0's data */ -#define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /* Attribute creation order is tracked */ -#define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /* Attribute creation order has index */ -#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /* Non-default attribute storage phase change values stored */ -#define H5O_HDR_STORE_TIMES 0x20 /* Store access, modification, change & birth times for object */ +#define H5O_HDR_CHUNK0_SIZE 0x03 /**< 2-bit field indicating # of bytes to store the size of chunk 0's data */ +#define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /**< Attribute creation order is tracked */ +#define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /**< Attribute creation order has index */ +#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /**< Non-default attribute storage phase change values stored */ +#define H5O_HDR_STORE_TIMES 0x20 /**< Store access, modification, change & birth times for object */ #define H5O_HDR_ALL_FLAGS \ (H5O_HDR_CHUNK0_SIZE | H5O_HDR_ATTR_CRT_ORDER_TRACKED | H5O_HDR_ATTR_CRT_ORDER_INDEXED | \ H5O_HDR_ATTR_STORE_PHASE_CHANGE | H5O_HDR_STORE_TIMES) +/* clang-format on */ /* Maximum shared message values. Number of indexes is 8 to allow room to add * new types of messages. @@ -81,9 +83,9 @@ * Theses flags determine which fields will be filled in in the H5O_info_t * struct. */ -#define H5O_INFO_BASIC 0x0001u /* Fill in the fileno, addr, type, and rc fields */ -#define H5O_INFO_TIME 0x0002u /* Fill in the atime, mtime, ctime, and btime fields */ -#define H5O_INFO_NUM_ATTRS 0x0004u /* Fill in the num_attrs field */ +#define H5O_INFO_BASIC 0x0001u /**< Fill in the fileno, addr, type, and rc fields */ +#define H5O_INFO_TIME 0x0002u /**< Fill in the atime, mtime, ctime, and btime fields */ +#define H5O_INFO_NUM_ATTRS 0x0004u /**< Fill in the num_attrs field */ #define H5O_INFO_ALL (H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS) //! <!-- [H5O_native_info_fields_snip] --> @@ -91,8 +93,8 @@ * Flags for H5Oget_native_info(). Theses flags determine which fields will be * filled in in the \ref H5O_native_info_t struct. */ -#define H5O_NATIVE_INFO_HDR 0x0008u /* Fill in the hdr field */ -#define H5O_NATIVE_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */ +#define H5O_NATIVE_INFO_HDR 0x0008u /**< Fill in the hdr field */ +#define H5O_NATIVE_INFO_META_SIZE 0x0010u /**< Fill in the meta_size field */ #define H5O_NATIVE_INFO_ALL (H5O_NATIVE_INFO_HDR | H5O_NATIVE_INFO_META_SIZE) //! <!-- [H5O_native_info_fields_snip] --> @@ -146,15 +148,15 @@ typedef struct H5O_hdr_info_t { * (For H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx() version 3) */ typedef struct H5O_info2_t { - unsigned long fileno; /* File number that object is located in */ - H5O_token_t token; /* Token representing the object */ - H5O_type_t type; /* Basic object type (group, dataset, etc.) */ - 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 */ + unsigned long fileno; /**< File number that object is located in */ + H5O_token_t token; /**< Token representing the object */ + H5O_type_t type; /**< Basic object type (group, dataset, etc.) */ + 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; /**< Number of attributes attached to object */ } H5O_info2_t; //! <!-- [H5O_info2_t_snip] --> @@ -165,11 +167,10 @@ typedef struct H5O_info2_t { */ typedef struct H5O_native_info_t { H5O_hdr_info_t hdr; /**< Object header information */ - /* Extra metadata storage for obj & attributes */ struct { H5_ih_info_t obj; /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */ H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */ - } meta_size; + } meta_size; /**< Extra metadata storage for obj & attributes */ } H5O_native_info_t; //! <!-- [H5O_native_info_t_snip] --> @@ -181,6 +182,17 @@ typedef uint32_t H5O_msg_crt_idx_t; //! <!-- [H5O_iterate2_t_snip] --> /** * Prototype for H5Ovisit(), H5Ovisit_by_name() operator (version 3) + * + * \param[in] obj Object that serves as the root of the iteration; + * the same value as the H5Ovisit3() \c obj_id parameter + * \param[in] name Name of object, relative to \p obj, being examined at current + * step of the iteration + * \param[out] info Information about that object + * \param[in,out] op_data User-defined pointer to data required by the application + * in processing the object; a pass-through of the \c op_data + * pointer provided with the H5Ovisit3() function call + * \return \herr_t_iter + * */ typedef herr_t (*H5O_iterate2_t)(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data); //! <!-- [H5O_iterate2_t_snip] --> @@ -460,28 +472,7 @@ H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id); * \return \herr_t * * \details H5Oget_info3() specifies an object by its identifier, \p loc_id , and - * retrieves the metadata describing that object in \p oinfo , an H5O_info2_t \c struct. - * - * The H5O_info2_t \c struct is defined in H5Opublic.h as follows : - * \snippet this H5O_info2_t_snip - * - * Note the following about H5O_info2_t : - * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) - * only \c ctime has been implemented. - * - The \c atime value is the last time the object was read or written. - * - The \c mtime value is the last time the raw data in the object was changed. - * - The \c ctime value is the last time the metadata for the object was changed. - * - The \c btime value is the time the object was created. - * - * The H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The H5O_type_t \c enum indicates the object type and - * is defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p loc_id - * refers only to the types specified by H5O_type_t. + * retrieves the metadata describing that object in \p oinfo. * * The \p fields parameter contains flags to determine which fields will be filled in * the H5O_info2_t \c struct returned in \p oinfo. @@ -530,29 +521,6 @@ H5_DLL herr_t H5Oget_info3(hid_t loc_id, H5O_info2_t *oinfo, unsigned fields); * \p loc_id and \p name, respectively, and retrieves the metadata * describing that object in \p oinfo, an H5O_info2_t struct. * - * \p oinfo, in which the object information is returned, is a \c struct of - * type H5O_info2_t, which is defined in H5Opublic.h in the HDF5 source code: - * - * \snippet this H5O_info2_t_snip - * - * Note the following about H5O_info2_t : - * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) - * only \c ctime has been implemented. - * - The \c atime value is the last time the object was read or written. - * - The \c mtime value is the last time the raw data in the object was changed. - * - The \c ctime value is the last time the metadata for the object was changed. - * - The \c btime value is the time the object was created. - * - * The H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The H5O_type_t \c enum indicates the object type and - * is defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p loc_id - * refers only to the types specified by H5O_type_t. - * * The \p fields parameter contains flags to determine which fields will be filled in * the H5O_info2_t \c struct returned in \p oinfo. * These flags are defined in the H5Opublic.h file: @@ -608,34 +576,6 @@ H5_DLL herr_t H5Oget_info_by_name_async(const char *app_file, const char *app_fu * If \p loc_id fully specifies the group in which the object resides, * \p group_name can be a dot (\c .). * - * \p idx_type is of type #H5_index_t, defined in H5public.h as: - * \snippet H5public.h H5_index_t_snip - * - * \p order is of type #H5_iter_order_t defined in H5public.h as: - * \snippet H5public.h H5_iter_order_t_snip - * - * \p oinfo, in which the object information is returned, is a \c struct of - * type H5O_info2_t, which is defined in H5Opublic.h in the HDF5 source code: - * \snippet this H5O_info2_t_snip - * - * Note the following about H5O_info2_t : - * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) - * only \c ctime has been implemented. - * - The \c atime value is the last time the object was read or written. - * - The \c mtime value is the last time the raw data in the object was changed. - * - The \c ctime value is the last time the metadata for the object was changed. - * - The \c btime value is the time the object was created. - * - * H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The #H5O_type_t \c enum indicates the object type and - * is defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p loc_id - * refers only to the types specified by #H5O_type_t. - * * The \p fields parameter contains flags to determine which fields will be filled in * the H5O_info2_t \c struct returned in \p oinfo. * These flags are defined in the H5Opublic.h file: @@ -668,11 +608,7 @@ H5_DLL herr_t H5Oget_info_by_idx3(hid_t loc_id, const char *group_name, H5_index * \return \herr_t * * \details H5Oget_native_info() retrieves the native file format information for an object - * specified by \p loc_id. The information is retrieved into the - * buffer specified by \p oinfo, which is defined as a \c struct of - * type H5O_native_info_t in H5Opublic.h: - * - * \snippet this H5O_native_info_t_snip + * specified by \p loc_id. * * The \p fields parameter indicates which fields to fill in * H5O_native_info_t. Possible values defined in H5Opublic.h are: @@ -703,12 +639,9 @@ H5_DLL herr_t H5Oget_native_info(hid_t loc_id, H5O_native_info_t *oinfo, unsigne * * \return \herr_t * - * \details H5Oget_native_info_by_name() retrieves the native file format information for an object - * specified by \p loc_id and the name \p name. The information is - * retrieved into the buffer specified by \p oinfo, which is defined - * as a \c struct of type H5O_native_info_t in H5Opublic.h: - * - * \snippet this H5O_native_info_t_snip + * \details H5Oget_native_info_by_name() retrieves the native file format + * information for an object specified by \p loc_id and the name \p + * name. * * The \p fields parameter which fields to fill in H5O_native_info_t. * Possible values defined in H5Opublic.h are: @@ -747,16 +680,7 @@ H5_DLL herr_t H5Oget_native_info_by_name(hid_t loc_id, const char *name, H5O_nat * specified by \p loc_id, group name, \p group_name, the index by which * objects in the group are tracked, \p idx_type, the order by which * the index is to be traversed, \p order , and an object's position - * \p n within that index. The information is retrieved into the - * buffer specified by \p oinfo, which is defined as a \c struct of - * type H5O_native_info_t in H5Opublic.h: - * \snippet this H5O_native_info_t_snip - * - * \p idx_type is of type #H5_index_t, defined in H5public.h as: - * \snippet H5public.h H5_index_t_snip - * - * \p order is of type #H5_iter_order_t defined in H5public.h as: - * \snippet H5public.h H5_iter_order_t_snip + * \p n within that index. * * The \p fields parameter indicates which fields to fill in H5O_native_info_t. * Possible values defined in H5Opublic.h are: @@ -1236,11 +1160,8 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes - * + * unnecessary, so the iteration may begin more quickly. + * Note that the index type passed in \p idx_type is a * <em>best effort</em> setting. If the application passes in * a value indicating iteration in creation order and a group is @@ -1250,62 +1171,7 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders - * - * The prototype of the callback function op is as follows (as - * defined in the source code file H5Opublic.h): - * - * \snippet this H5O_iterate2_t_snip - * - * The parameters of this callback function have the following values - * or meanings: - * <table> - * <tr> - * <td>\c obj</td> - * <td>Object that serves as root of the iteration; - * same value as the H5Ovisit() \p obj_id parameter</td> - * </tr> - * <tr> - * <td>\c name</td> - * <td>Name of object, relative to \c obj, being examined at - * current step of the iteration</td> - * </tr> - * <tr> - * <td>\c info</td> - * <td>H5O_info2_t \c struct containing information - * regarding that object</td> - * </tr> - * <tr> - * <td>\c op_data</td> - * <td>User-defined pointer to data required by the application in - * processing the object; a pass-through of the \c op_data pointer - * provided with the H5Ovisit() function call</td> - * </tr> - * </table> - * - * The H5O_info2_t \c struct is defined in H5Opublic.h as follows: - * \snippet this H5O_info2_t_snip - * - * H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The #H5O_type_t enum indicates the object type and is - * defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p obj_id - * refers only to the types specified by #H5O_type_t. - * - * The return values from an operator are: - * - Zero causes the visit iterator to continue, returning zero when all - * group members have been processed. - * - A positive value causes the visit iterator to immediately return that - * positive value, indicating short-circuit success. - * - A negative value causes the visit iterator to immediately return that - * value, indicating failure. + * along the index specified in \p idx_type. * * The H5Ovisit3() \p op_data parameter is a user-defined pointer to the data * required to process objects in the course of the iteration. This pointer @@ -1329,24 +1195,6 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm * group change during the iteration, the resulting behavior * is undefined. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \par Example * An example snippet from test/links.c: * \snippet links.c H5Ovisit3_snip @@ -1411,10 +1259,7 @@ H5_DLL herr_t H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * <em>best effort</em> setting. If the application passes in a @@ -1425,49 +1270,7 @@ H5_DLL herr_t H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders - * - * The prototype of the callback function op is as follows (as - * defined in the source code file H5Opublic.h): - * - * \snippet this H5O_iterate2_t_snip - * - * The parameters of this callback function have the following - * values or meanings: - * <table> - * <tr> - * <td>\c obj</td> - * <td>Object that serves as root of the iteration</td> - * </tr> - * <tr> - * <td>\c name</td> - * <td>Name of object, relative to \c obj, being examined at - * current step of the iteration</td> - * </tr> - * <tr> - * <td>\c info</td> - * <td>H5O_info2_t \c struct containing information - * regarding that object</td> - * </tr> - * <tr> - * <td>\c op_data</td> - * <td>User-defined pointer to data required by the application in - * processing the object</td> - * </tr> - * </table> - * - * The H5O_info2_t \c struct is defined in H5Opublic.h as follows: - * \snippet this H5O_info2_t_snip - * - * H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The #H5O_type_t enum indicates the object type and is - * defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip + * along the index specified in \p idx_type. * * The H5Ovisit_by_name3() \p op_data parameter is a user-defined * pointer to the data required to process objects in the course @@ -1495,24 +1298,6 @@ H5_DLL herr_t H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * in the file has been presented to the application for whatever * processing the application requires. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \par Example * An example snippet from test/links.c: * \snippet links.c H5Ovisit_by_name3_snip @@ -1579,26 +1364,11 @@ H5_DLL herr_t H5Oclose_async(const char *app_file, const char *app_func, unsigne * files. After that, the OS is responsible for ensuring that * the data is actually flushed to disk. * - * \par See Also: - * - H5Dflush() - * - H5Drefresh() - * - H5Oflush() - * - H5Grefresh() - * - H5Oflush() - * - H5Orefresh() - * - H5Tflush() - * - H5Trefresh() - * \par - * - \c H5DOappend() - * - H5Fstart_swmr_write() - * - H5Pget_append_flush() - * - H5Pget_object_flush_cb() - * - H5Pset_append_flush() - * - H5Pset_object_flush_cb() - * \par - * - H5Oare_mdc_flushes_disabled() - * - H5Odisable_mdc_flushes() - * - H5Oenable_mdc_flushes() + * \see H5Dflush(), H5Drefresh(), H5Oflush(), H5Grefresh(), H5Oflush(), + * H5Orefresh(), H5Tflush(), H5Trefresh() + * \see H5DOappend(), H5Fstart_swmr_write(), H5Pget_append_flush(), + * H5Pget_object_flush_cb(), H5Pset_append_flush(), H5Pset_object_flush_cb() + * \see H5Oare_mdc_flushes_disabled(), H5Odisable_mdc_flushes(), H5Oenable_mdc_flushes() * * \since 1.10.0 * @@ -1670,21 +1440,17 @@ H5_DLL herr_t H5Orefresh_async(const char *app_file, const char *app_func, unsig * HDF5 object level (datasets, groups, committed datatypes) * and the entire metadata cache level. * - * \note HDF5 objects include datasets, groups, and committed datatypes. - * Only #hid_t identifiers that represent these objects can be passed to the function. - * \note Passing in a #hid_t identifier that represents any other HDF5 entity is - * considered an error. - * \note It is an error to pass an HDF5 file identifier - * (obtained from H5Fopen() or H5Fcreate()) - * to this function. - * \note Misuse of this function can cause the cache to exhaust - * available memory. - * \note Objects can be returned to the default automatic flush behavior - * with H5Oenable_mdc_flushes(). - * \note Flush prevention only pertains to new or dirty metadata entries. - * Clean entries can be evicted from the cache. - * \note Calling this function on an object that has already had flushes - * disabled will return an error. + * \note HDF5 objects include datasets, groups, and committed datatypes. Only + * #hid_t identifiers that represent these objects can be passed to the + * function. Passing in a #hid_t identifier that represents any other + * HDF5 entity is considered an error. It is an error to pass an HDF5 + * file identifier (obtained from H5Fopen() or H5Fcreate()) to this + * function. Misuse of this function can cause the cache to exhaust + * available memory. Objects can be returned to the default automatic + * flush behavior with H5Oenable_mdc_flushes(). Flush prevention only + * pertains to new or dirty metadata entries. Clean entries can be + * evicted from the cache. Calling this function on an object that has + * already had flushes disabled will return an error. * * \since 1.10.0 * @@ -1714,28 +1480,18 @@ H5_DLL herr_t H5Odisable_mdc_flushes(hid_t object_id); * metadata cache level. * * - * \note HDF5 objects include datasets, groups, and committed datatypes. - * Only #hid_t identifiers that represent these objects can be - * passed to the function. - * - * \note Passing in a #hid_t identifier that represents any other HDF5 entity - * is considered an error. - * - * \note It is an error to pass an HDF5 file identifier - * (obtained from H5Fopen() or H5Fcreate()) - * to this function. - * - * \note Using this function on an object that has not had flushes disabled - * is considered an error. The state of an object can be determined - * with H5Oare_mdc_flushes_disabled(). - * - * \note An object will be returned to the default flush algorithm when it is closed. - * - * \note All objects will be returned to the default flush algorithm when - * the file is closed. - * - * \note An object’s entries will not necessarily be flushed as a result of - * calling this function. + * \note HDF5 objects include datasets, groups, and committed datatypes. Only + * #hid_t identifiers that represent these objects can be passed to the + * function. Passing in a #hid_t identifier that represents any other + * HDF5 entity is considered an error. It is an error to pass an HDF5 + * file identifier (obtained from H5Fopen() or H5Fcreate()) to this + * function. Using this function on an object that has not had flushes + * disabled is considered an error. The state of an object can be + * determined with H5Oare_mdc_flushes_disabled(). An object will be + * returned to the default flush algorithm when it is closed. All objects + * will be returned to the default flush algorithm when the file is + * closed. An object’s entries will not necessarily be flushed as a + * result of calling this function. * * \since 1.10.0 * @@ -1871,6 +1627,7 @@ H5_DLL herr_t H5Otoken_to_str(hid_t loc_id, const H5O_token_t *token, char **tok */ H5_DLL herr_t H5Otoken_from_str(hid_t loc_id, const char *token_str, H5O_token_t *token); +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -1894,6 +1651,7 @@ H5_DLL herr_t H5Otoken_from_str(hid_t loc_id, const char *token_str, H5O_token_t #define H5Orefresh_async_wrap H5_NO_EXPAND(H5Orefresh_async) #define H5Ocopy_async_wrap H5_NO_EXPAND(H5Ocopy_async) #endif +/// \endcond /* The canonical 'undefined' token value */ #define H5O_TOKEN_UNDEF (H5OPEN H5O_TOKEN_UNDEF_g) @@ -1908,8 +1666,8 @@ H5_DLLVAR const H5O_token_t H5O_TOKEN_UNDEF_g; /* Macros */ /* Deprecated flags for earlier versions of H5Oget_info* */ -#define H5O_INFO_HDR 0x0008u /* Fill in the hdr field */ -#define H5O_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */ +#define H5O_INFO_HDR 0x0008u /**< Fill in the hdr field */ +#define H5O_INFO_META_SIZE 0x0010u /**< Fill in the meta_size field */ #undef H5O_INFO_ALL #define H5O_INFO_ALL (H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE) @@ -1942,7 +1700,7 @@ typedef struct H5O_info1_t { time_t mtime; /**< Modification time */ time_t ctime; /**< Change time */ time_t btime; /**< Birth time */ - hsize_t num_attrs; /**< # of attributes attached to object */ + hsize_t num_attrs; /**< Number of attributes attached to object */ H5O_hdr_info_t hdr; /**< Object header information */ /* Extra metadata storage for obj & attributes */ struct { @@ -1955,6 +1713,16 @@ typedef struct H5O_info1_t { //! <!-- [H5O_iterate1_t_snip] --> /** * Prototype for H5Ovisit(), H5Ovisit_by_name() operator (versions 1 & 2) + * + * \param[in] obj Object that serves as the root of the iteration; + * the same value as the H5Ovisit1() \c obj_id parameter + * \param[in] name Name of object, relative to \p obj, being examined at current + * step of the iteration + * \param[out] info Information about that object + * \param[in,out] op_data User-defined pointer to data required by the application + * in processing the object + * \return \herr_t_iter + * */ typedef herr_t (*H5O_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t *info, void *op_data); //! <!-- [H5O_iterate1_t_snip] --> @@ -2027,36 +1795,7 @@ H5_DLL hid_t H5Oopen_by_addr(hid_t loc_id, haddr_t addr); * the function H5Oget_info3() or the macro #H5Oget_info. * * \details H5Oget_info1() specifies an object by its identifier, \p loc_id , and - * retrieves the metadata describing that object in \p oinfo , - * defined as a \c struct of type H5O_info1_t : - * - * \snippet this H5O_info1_t_snip - * - * Note the following about H5O_info1_t : - * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) - * only \c ctime has been implemented. - * - The \c atime value is the last time the object was read or written. - * - The \c mtime value is the last time the raw data in the object was changed. - * - The \c ctime value is the last time the metadata for the object was changed. - * - The \c btime value is the time the object was created. - * - The fields nested in the \c meta_size field are for internal library use only. - * - * The #H5O_type_t \c enum indicates the object type and - * is defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p loc_id - * refers only to the types specified by #H5O_type_t. - * - * An H5O_hdr_info_t \c struct holds object header metadata and is - * defined in H5Opublic.h as follows: - * \snippet this H5O_hdr_info_t_snip - * - * Valid values for the \c version field are \c H5O_VERSION_1 and \c H5O_VERSION_2. - * Version 2 of the object header is smaller and more efficient than version 1. - * - * Please be aware that the information held by H5O_hdr_info_t may only be useful to - * developers with extensive HDF5 experience. + * retrieves the metadata describing that object in \p oinfo. * * \note If you are iterating through a lot of different objects to * retrieve information via the H5Oget_info() family of routines, @@ -2156,16 +1895,6 @@ H5_DLL herr_t H5Oget_info_by_name1(hid_t loc_id, const char *name, H5O_info1_t * * If \p loc_id fully specifies the group in which the object resides, * \p group_name can be a dot (\c .). * - * \p idx_type is of type #H5_index_t, defined in H5public.h as: - * \snippet H5public.h H5_index_t_snip - * - * \p order is of type #H5_iter_order_t defined in H5public.h as: - * \snippet H5public.h H5_iter_order_t_snip - * - * \p oinfo, in which the object information is returned, is a \c struct of - * type H5O_info1_t . - * \snippet this H5O_info1_t_snip - * * The link access property list, \c lapl_id, is not currently used; * it should be passed in as #H5P_DEFAULT. * @@ -2361,10 +2090,7 @@ H5_DLL herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * <em>best effort</em> setting. If the application passes in @@ -2375,56 +2101,7 @@ H5_DLL herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders - * - * The prototype of the callback function op is as follows (as - * defined in the source code file H5Opublic.h): - * - * \snippet this H5O_iterate1_t_snip - * - * The parameters of this callback function have the following values - * or meanings: - * <table> - * <tr> - * <td>\c obj</td> - * <td>Object that serves as root of the iteration; - * same value as the H5Ovisit1() \p obj_id parameter</td> - * </tr> - * <tr> - * <td>\c name</td> - * <td>Name of object, relative to \c obj, being examined at - * current step of the iteration</td> - * </tr> - * <tr> - * <td>\c info</td> - * <td>H5O_info1_t \c struct containing information - * regarding that object</td> - * </tr> - * <tr> - * <td>\c op_data</td> - * <td>User-defined pointer to data required by the application in - * processing the object</td> - * </tr> - * </table> - * - * The H5O_info1_t \c struct is defined in H5Opublic.h: - * \snippet this H5O_info1_t_snip - * - * The return values from an operator are: - * - Zero causes the visit iterator to continue, returning zero when all - * group members have been processed. - * - A positive value causes the visit iterator to immediately return that - * positive value, indicating short-circuit success. - * - A negative value causes the visit iterator to immediately return that - * value, indicating failure. - * - * The H5Ovisit1() \p op_data parameter is a user-defined pointer to the data - * required to process objects in the course of the iteration. This pointer - * is passed back to each step of the iteration in the callback - * function’s \p op_data parameter. + * along the index specified in \p idx_type. * * H5Lvisit1() and H5Ovisit1() are companion functions: one for * examining and operating on links; the other for examining @@ -2438,24 +2115,6 @@ H5_DLL herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index * group change during the iteration, the resulting behavior * is undefined. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \version 1.10.5 The macro #H5Ovisit was removed and the function * H5Ovisit1() was copied to H5Ovisit(). * \version 1.10.3 Function H5Ovisit() was copied to H5Ovisit1(), @@ -2523,10 +2182,7 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * <em>best effort</em> setting. If the application passes in a @@ -2537,10 +2193,7 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders + * along the index specified in \p idx_type. * * The \p op callback function and the effect of the callback * function’s return value on the application are described @@ -2570,24 +2223,6 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * in the file has been presented to the application for whatever * processing the application requires. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \version 1.10.5 The macro #H5Ovisit_by_name was removed and the function * H5Ovisit_by_name1() was copied to #H5Ovisit_by_name. * \version 1.10.3 The H5Ovisit_by_name() function was renamed to H5Ovisit_by_name1(), @@ -2650,10 +2285,7 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * <em>best effort</em> setting. If the application passes in @@ -2664,57 +2296,7 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders - * - * The prototype of the callback function op is as follows (as - * defined in the source code file H5Opublic.h): - * - * \snippet this H5O_iterate1_t_snip - * - * The parameters of this callback function have the following values - * or meanings: - * <table> - * <tr> - * <td>\c obj</td> - * <td>Object that serves as root of the iteration; - * same value as the H5Ovisit1() \p obj_id parameter</td> - * </tr> - * <tr> - * <td>\c name</td> - * <td>Name of object, relative to \c obj, being examined at - * current step of the iteration</td> - * </tr> - * <tr> - * <td>\c info</td> - * <td>H5O_info1_t \c struct containing information - * regarding that object</td> - * </tr> - * <tr> - * <td>\c op_data</td> - * <td>User-defined pointer to data required by the application in - * processing the object; a pass-through of the \c op_data pointer - * provided with the H5Ovisit() function call</td> - * </tr> - * </table> - * - * The H5O_info1_t \c struct is defined in H5Opublic.h and - * described in the H5Oget_info1() function entry. - * - * The return values from an operator are: - * - Zero causes the visit iterator to continue, returning zero when all - * group members have been processed. - * - A positive value causes the visit iterator to immediately return that - * positive value, indicating short-circuit success. - * - A negative value causes the visit iterator to immediately return that - * value, indicating failure. - * - * The H5Ovisit2() \p op_data parameter is a user-defined pointer to the data - * required to process objects in the course of the iteration. This pointer - * is passed back to each step of the iteration in the callback - * function’s \p op_data parameter. + * along the index specified in \p idx_type. * * The \p fields parameter contains flags to determine which fields will * be retrieved by the \p op callback function. These flags are defined @@ -2733,23 +2315,6 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i * group change during the iteration, the resulting behavior * is undefined. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. * * \since 1.10.3 * @@ -2814,10 +2379,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * <em>best effort</em> setting. If the application passes in a @@ -2828,10 +2390,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders + * along the index specified in \p idx_type. * * The \p op callback function and the effect of the callback * function’s return value on the application are described @@ -2866,24 +2425,6 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * in the file has been presented to the application for whatever * processing the application requires. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \since 1.10.3 * */ @@ -359,7 +359,7 @@ H5PLget(unsigned int idx, char *path_buf, size_t buf_size) /* If the path buffer is not NULL, copy the path to the buffer */ if (path_buf) { - HDstrncpy(path_buf, path, MIN((size_t)(path_len + 1), buf_size)); + HDstrncpy(path_buf, path, buf_size); if ((size_t)path_len >= buf_size) path_buf[buf_size - 1] = '\0'; } /* end if */ diff --git a/src/H5PLint.c b/src/H5PLint.c index 6bb8404..d20401e 100644 --- a/src/H5PLint.c +++ b/src/H5PLint.c @@ -292,7 +292,7 @@ done: * get_plugin_info function pointer, but early (4.4.7, at least) gcc * only allows diagnostic pragmas to be toggled outside of functions. */ -H5_GCC_DIAG_OFF("pedantic") +H5_GCC_CLANG_DIAG_OFF("pedantic") herr_t H5PL__open(const char *path, H5PL_type_t type, const H5PL_key_t *key, hbool_t *success, H5PL_type_t *plugin_type, const void **plugin_info) @@ -414,7 +414,7 @@ done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5PL__open() */ -H5_GCC_DIAG_ON("pedantic") +H5_GCC_CLANG_DIAG_ON("pedantic") /*------------------------------------------------------------------------- * Function: H5PL__close diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h index ab9f1d5..a093096 100644 --- a/src/H5PLmodule.h +++ b/src/H5PLmodule.h @@ -28,8 +28,34 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5PL H5PL - * \brief Plugins - * \todo Describe what programmatically controlling dynamically loaded plugins (H5PL) is all about + * + * Use the functions in this module to manage the loading behavior of HDF5 + * plugins. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet H5PL_examples.c create + * </td> + * <td> + * \snippet H5PL_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet H5PL_examples.c update + * </td> + * <td> + * \snippet H5PL_examples.c delete + * </td> + * </tr> + * </table> + * + * \attention The loading behavior of HDF5 plugins can be controlled via the + * functions described below and certain environment variables, such + * as \c HDF5_PLUGIN_PRELOAD and \c HDF5_PLUGIN_PATH. + * */ #endif /* H5PLmodule_H */ diff --git a/src/H5PLplugin_cache.c b/src/H5PLplugin_cache.c index 4f5c0ce..b7cdac0 100644 --- a/src/H5PLplugin_cache.c +++ b/src/H5PLplugin_cache.c @@ -242,7 +242,7 @@ done: /* See the other use of H5PL_GET_LIB_FUNC() for an explanation * for why we disable -Wpedantic here. */ -H5_GCC_DIAG_OFF("pedantic") +H5_GCC_CLANG_DIAG_OFF("pedantic") herr_t H5PL__find_plugin_in_cache(const H5PL_search_params_t *search_params, hbool_t *found, const void **plugin_info) @@ -320,4 +320,4 @@ H5PL__find_plugin_in_cache(const H5PL_search_params_t *search_params, hbool_t *f done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5PL__find_plugin_in_cache() */ -H5_GCC_DIAG_ON("pedantic") +H5_GCC_CLANG_DIAG_ON("pedantic") diff --git a/src/H5Pdapl.c b/src/H5Pdapl.c index 2ebdbe3..d374b25 100644 --- a/src/H5Pdapl.c +++ b/src/H5Pdapl.c @@ -1453,7 +1453,7 @@ H5Pget_efile_prefix(hid_t plist_id, char *prefix /*out*/, size_t size) /* Copy to user's buffer, if given */ len = HDstrlen(my_prefix); if (prefix) { - HDstrncpy(prefix, my_prefix, MIN(len + 1, size)); + HDstrncpy(prefix, my_prefix, size); if (len >= size) prefix[size - 1] = '\0'; } /* end if */ @@ -1543,7 +1543,7 @@ H5Pget_virtual_prefix(hid_t plist_id, char *prefix /*out*/, size_t size) /* Copy to user's buffer, if given */ len = HDstrlen(my_prefix); if (prefix) { - HDstrncpy(prefix, my_prefix, MIN(len + 1, size)); + HDstrncpy(prefix, my_prefix, size); if (len >= size) prefix[size - 1] = '\0'; } /* end if */ diff --git a/src/H5Pdxpl.c b/src/H5Pdxpl.c index 217bfda..a47d8bd 100644 --- a/src/H5Pdxpl.c +++ b/src/H5Pdxpl.c @@ -1065,7 +1065,7 @@ H5Pget_data_transform(hid_t plist_id, char *expression /*out*/, size_t size) /* Copy into application buffer */ len = HDstrlen(pexp); if (expression) { - HDstrncpy(expression, pexp, MIN(len + 1, size)); + HDstrncpy(expression, pexp, size); if (len >= size) expression[size - 1] = '\0'; } /* end if */ diff --git a/src/H5Pencdec.c b/src/H5Pencdec.c index 5b0ecb6..e2a97f8 100644 --- a/src/H5Pencdec.c +++ b/src/H5Pencdec.c @@ -333,7 +333,7 @@ H5P__encode_cb(H5P_genprop_t *prop, void *_udata) /* Encode (or not, if the 'encode' flag is off) the property's name */ prop_name_len = HDstrlen(prop->name) + 1; if (udata->encode) { - HDstrncpy((char *)*(udata->pp), prop->name, prop_name_len); + HDstrcpy((char *)*(udata->pp), prop->name); *(uint8_t **)(udata->pp) += prop_name_len; } /* end if */ *(udata->enc_size_ptr) += prop_name_len; diff --git a/src/H5Plapl.c b/src/H5Plapl.c index 879e6ed..d00efaf 100644 --- a/src/H5Plapl.c +++ b/src/H5Plapl.c @@ -1044,7 +1044,7 @@ H5Pget_elink_prefix(hid_t plist_id, char *prefix /*out*/, size_t size) /* Copy to user's buffer, if given */ len = HDstrlen(my_prefix); if (prefix) { - HDstrncpy(prefix, my_prefix, MIN(len + 1, size)); + HDstrncpy(prefix, my_prefix, size); if (len >= size) prefix[size - 1] = '\0'; } /* end if */ diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index 18f30c6..6e92e66 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -30,49 +30,165 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5P H5P - * \brief Property List Interface * - * \details The HDF5 Property List Interface provides a mechanism to take - * advantage of more powerful or unusual features in HDF5. + * Use the functions in this module to manage HDF5 property lists and property + * list classes. HDF5 property lists are the main vehicle to configure the + * behavior of HDF5 API functions. * - * HDF5 objects have properties or characteristics associated with - * them, and there are default properties that handle the most - * common needs. These default properties can be modified using the - * HDF5 Property List Interface. For example, the data storage - * layout property of a dataset is contiguous by default. For better - * performance, the layout can be modified to be chunked or chunked - * and compressed. + * Typically, property lists are created by instantiating one of the built-in + * or user-defined property list classes. After adding suitable properties, + * property lists are used when opening or creating HDF5 items, or when reading + * or writing data. Property lists can be modified by adding or changing + * properties. Property lists are deleted by closing the associated handles. * - * \todo Describe concisely what the functions in this module are about. + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c create + * </td> + * <td> + * \snippet{lineno} H5P_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c update + * </td> + * <td> + * \snippet{lineno} H5P_examples.c delete + * </td> + * </tr> + * </table> * - * \defgroup GPLO General Property List Operations + * \defgroup ALCAPL Attribute and Link Creation Properties * \ingroup H5P - * \defgroup GPLOA General Property List Operations (Advanced) + * Currently, there are only two creation properties that you can use to control + * the creation of HDF5 attributes and links. The first creation property, the + * choice of a character encoding, applies to both attributes and links. + * The second creation property applies to links only, and advises the library + * to automatically create missing intermediate groups when creating new objects. + * + * \defgroup DAPL Dataset Access Properties * \ingroup H5P - * \defgroup FCPL File Creation Properties + * Use dataset access properties to modify the default behavior of the HDF5 + * library when accessing datasets. The properties include adjusting the size + * of the chunk cache, providing prefixes for external content and virtual + * dataset file paths, and controlling flush behavior, etc. These properties + * are \Emph{not} persisted with datasets, and can be adjusted at runtime before + * a dataset is created or opened. + * + * \defgroup DCPL Dataset Creation Properties + * \ingroup H5P + * Use dataset creation properties to control aspects of dataset creation such + * as fill time, storage layout, compression methods, etc. + * Unlike dataset access and transfer properties, creation properties \Emph{are} + * stored with the dataset, and cannot be changed once a dataset has been + * created. + * + * \defgroup DXPL Dataset Transfer Properties * \ingroup H5P + * Use dataset transfer properties to customize certain aspects of reading + * and writing datasets such as transformations, MPI-IO I/O mode, error + * detection, etc. These properties are \Emph{not} persisted with datasets, + * and can be adjusted at runtime before a dataset is read or written. + * * \defgroup FAPL File Access Properties * \ingroup H5P - * \defgroup GCPL Group Creation Properties + * Use file access properties to modify the default behavior of the HDF5 + * library when accessing files. The properties include selecting a virtual + * file driver (VFD), configuring the metadata cache (MDC), control + * file locking, etc. These properties are \Emph{not} persisted with files, and + * can be adjusted at runtime before a file is created or opened. + * + * \defgroup FCPL File Creation Properties * \ingroup H5P - * \defgroup ALCAPL Attribute and Link Creation Properties + * Use file creation properties to control aspects of file creation such + * as setting a file space management strategy or creating a user block. + * Unlike file access properties, creation properties \Emph{are} + * stored with the file, and cannot be changed once a file has been + * created. + * + * \defgroup GAPL General Access Properties * \ingroup H5P - * \defgroup LAPL Link Access Properties + * \todo Should this be as standalone page? + * + * \defgroup GCPL Group Creation Properties * \ingroup H5P - * \defgroup DCPL Dataset Creation Properties + * Use group creation properties to control aspects of group creation such + * as storage layout, compression, and link creation order tracking. + * Unlike file access properties, creation properties \Emph{are} + * stored with the group, and cannot be changed once a group has been + * created. + * + * \defgroup GPLO General Property List Operations * \ingroup H5P - * \defgroup DAPL Dataset Access Properties + * + * Use the functions in this module to manage HDF5 property lists. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c create + * </td> + * <td> + * \snippet{lineno} H5P_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c update + * </td> + * <td> + * \snippet{lineno} H5P_examples.c delete + * </td> + * </tr> + * </table> + * + * \defgroup GPLOA General Property List Operations (Advanced) * \ingroup H5P - * \defgroup DXPL Dataset Transfer Properties + * + * You can create and customize user-defined property list classes using the + * functions described below. Arbitrary user-defined properties can also + * be inserted into existing property lists as so-called temporary properties. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c create_class + * </td> + * <td> + * \snippet{lineno} H5P_examples.c read_class + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5P_examples.c update_class + * </td> + * <td> + * \snippet{lineno} H5P_examples.c delete_class + * </td> + * </tr> + * </table> + * + * \defgroup LAPL Link Access Properties * \ingroup H5P + * + * + * \defgroup MAPL Map Access Properties + * \ingroup H5P + * \defgroup OCPL Object Creation Properties * \ingroup H5P + * + * * \defgroup OCPPL Object Copy Properties * \ingroup H5P - * \defgroup GACPL General Access Properties - * \ingroup H5P - * \defgroup MAPL Map Access Properties - * \ingroup H5P + * + * */ #endif /* H5Pmodule_H */ diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 10609b2..a5c5c37 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -100,7 +100,9 @@ #define H5P_CRT_ORDER_TRACKED 0x0001 #define H5P_CRT_ORDER_INDEXED 0x0002 -/* Default value for all property list classes */ +/** + * Default value of type \ref hid_t for all property list classes + */ #define H5P_DEFAULT 0 /* (hid_t) */ #ifdef __cplusplus @@ -113,14 +115,23 @@ extern "C" { /* Define property list class callback function pointer types */ //! <!-- [H5P_cls_create_func_t_snip] --> +/** + * \todo Document me! + */ typedef herr_t (*H5P_cls_create_func_t)(hid_t prop_id, void *create_data); //! <!-- [H5P_cls_create_func_t_snip] --> //! <!-- [H5P_cls_copy_func_t_snip] --> +/** + * \todo Document me! + */ typedef herr_t (*H5P_cls_copy_func_t)(hid_t new_prop_id, hid_t old_prop_id, void *copy_data); //! <!-- [H5P_cls_copy_func_t_snip] --> //! <!-- [H5P_cls_close_func_t_snip] --> +/** + * \todo Document me! + */ typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); //! <!-- [H5P_cls_close_func_t_snip] --> @@ -159,12 +170,25 @@ typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, vo typedef H5P_prp_cb1_t H5P_prp_create_func_t; typedef H5P_prp_cb2_t H5P_prp_set_func_t; typedef H5P_prp_cb2_t H5P_prp_get_func_t; +//! <!-- [H5P_prp_encode_func_t_snip] --> +/** + * \todo Document me! + */ typedef herr_t (*H5P_prp_encode_func_t)(const void *value, void **buf, size_t *size); +//! <!-- [H5P_prp_encode_func_t_snip] --> +//! <!-- [H5P_prp_decode_func_t_snip] --> +/** + * \todo Document me! + */ typedef herr_t (*H5P_prp_decode_func_t)(const void **buf, void *value); +//! <!-- [H5P_prp_decode_func_t_snip] --> typedef H5P_prp_cb2_t H5P_prp_delete_func_t; typedef H5P_prp_cb1_t H5P_prp_copy_func_t; //! <!-- [H5P_prp_compare_func_t_snip] --> +/** + * \todo Document me! + */ typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size); //! <!-- [H5P_prp_compare_func_t_snip] --> @@ -172,6 +196,9 @@ typedef H5P_prp_cb1_t H5P_prp_close_func_t; /* Define property list iteration function type */ //! <!-- [H5P_iterate_t_snip] --> +/** + * \todo Document me! + */ typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data); //! <!-- [H5P_iterate_t_snip] --> @@ -2211,7 +2238,7 @@ H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flag */ H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); /** - * \ingroup OCPL + * \ingroup DCPL * * \brief Sets deflate (GNU gzip) compression method and compression level * @@ -2220,6 +2247,8 @@ H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, uns * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_deflate() sets the deflate compression method and the * compression level, \p level, for a dataset or group creation * property list, \p plist_id. @@ -5237,7 +5266,7 @@ H5_DLL herr_t H5Pget_vol_cap_flags(hid_t plist_id, unsigned *cap_flags); #ifdef H5_HAVE_PARALLEL /** - * \ingroup GACPL + * \ingroup GAPL * * \brief Sets metadata I/O mode for read operations to collective or independent (default) * @@ -5306,7 +5335,7 @@ H5_DLL herr_t H5Pget_vol_cap_flags(hid_t plist_id, unsigned *cap_flags); */ H5_DLL herr_t H5Pset_all_coll_metadata_ops(hid_t plist_id, hbool_t is_collective); /** - * \ingroup GACPL + * \ingroup GAPL * * \brief Retrieves metadata read mode setting * @@ -6266,6 +6295,8 @@ H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_shuffle() sets the shuffle filter, #H5Z_FILTER_SHUFFLE, * in the dataset creation property list \p plist_id. The shuffle * filter de-interlaces a block of data by reordering the bytes. @@ -6337,6 +6368,8 @@ H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_nbit() sets the N-Bit filter, #H5Z_FILTER_NBIT, in the * dataset creation property list \p plist_id. * @@ -6430,6 +6463,8 @@ H5_DLL herr_t H5Pset_nbit(hid_t plist_id); * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_scaleoffset() sets the scale-offset filter, * #H5Z_FILTER_SCALEOFFSET, for a dataset. * @@ -6539,6 +6574,8 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_szip() sets an SZIP compression filter, #H5Z_FILTER_SZIP, * for a dataset. SZIP is a compression method designed for use with * scientific data. @@ -7449,10 +7486,6 @@ H5_DLL size_t H5Pget_buffer(hid_t plist_id, void **tconv /*out*/, void **bkg /*o * If an error occurs, the buffer pointed to by \p expression is * unchanged, and the function returns a negative value. * - * \par Example - * An example snippet from examples/h5_dtransform.c: - * \snippet h5_dtransform.c H5Pget_data_transform_snip - * * \since 1.8.0 * */ @@ -8055,7 +8088,7 @@ H5_DLL herr_t H5Pget_mpio_no_collective_cause(hid_t plist_id, uint32_t *local_no * the size of the \p start, \p stride, \p count, and \p block arrays. * \p rank must be between 1 and #H5S_MAX_RANK, inclusive. * - * The \op, \p start, \p stride, \p count, and \p block parameters + * The \p op, \p start, \p stride, \p count, and \p block parameters * behave identically to their behavior for H5Sselect_hyperslab(), * please see the documentation for that routine for details about * their use. @@ -9455,9 +9488,6 @@ H5_DLL herr_t H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, v * The #H5P_prp_cb2_t is as follows: * \snippet this H5P_prp_cb2_t_snip * - * - * \cpp_c_api_note - * */ /* Function prototypes */ @@ -9571,8 +9601,7 @@ H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *de * * The #H5P_prp_cb2_t is as follows: * \snippet this H5P_prp_cb2_t_snip - - * \cpp_c_api_note + * */ H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, void *value, H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, @@ -349,7 +349,7 @@ done: * format_templ in the code below, but early (4.4.7, at least) gcc only * allows diagnostic pragmas to be toggled outside of functions. */ -H5_GCC_DIAG_OFF("format-nonliteral") +H5_GCC_CLANG_DIAG_OFF("format-nonliteral") H5_ATTR_FORMAT(printf, 2, 3) herr_t H5RS_asprintf_cat(H5RS_str_t *rs, const char *fmt, ...) @@ -392,7 +392,7 @@ H5RS_asprintf_cat(H5RS_str_t *rs, const char *fmt, ...) done: FUNC_LEAVE_NOAPI(ret_value) } /* end H5RS_asprintf_cat() */ -H5_GCC_DIAG_ON("format-nonliteral") +H5_GCC_CLANG_DIAG_ON("format-nonliteral") /*------------------------------------------------------------------------- * Function: H5RS_acat diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h index 2a34d56..fe28bb2 100644 --- a/src/H5Rmodule.h +++ b/src/H5Rmodule.h @@ -27,9 +27,32 @@ /** * \defgroup H5R H5R - * \brief Reference Interface - * \details The HDF5 Reference Interface, H5R, provides a mechanism for managing - * HDF5 referenced objects. + * + * Use the functions in this module to manage HDF5 references. Referents can + * be HDF5 objects, attributes, and selections on datasets a.k.a. dataset + * regions. + * + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5R_examples.c create + * </td> + * <td> + * \snippet{lineno} H5R_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5R_examples.c update + * </td> + * <td> + * \snippet{lineno} H5R_examples.c delete + * </td> + * </tr> + * </table> + * */ #endif /* H5Rmodule_H */ diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h index b33960e..ef798ea 100644 --- a/src/H5Rpublic.h +++ b/src/H5Rpublic.h @@ -30,9 +30,11 @@ #define H5R_OBJ_REF_BUF_SIZE sizeof(haddr_t) #define H5R_DSET_REG_REF_BUF_SIZE (sizeof(haddr_t) + 4) -/* Default reference buffer size. - * Note! Be careful with the sizes of the references because they should really - * depend on the run-time values in the file. +/** + * Default reference buffer size. + * + * \internal Note! Be careful with the sizes of the references because they + * should really depend on the run-time values in the file. */ #define H5R_REF_BUF_SIZE (64) @@ -560,6 +562,7 @@ H5_DLL ssize_t H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *name, si */ H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t size); +/// \cond DEV /* API Wrappers for async routines */ /* (Must be defined _after_ the function prototype) */ /* (And must only defined when included in application code, not the library) */ @@ -574,6 +577,7 @@ H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t siz #define H5Ropen_region_async_wrap H5_NO_EXPAND(H5Ropen_region_async) #define H5Ropen_attr_async_wrap H5_NO_EXPAND(H5Ropen_attr_async) #endif /* H5R_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * diff --git a/src/H5Smodule.h b/src/H5Smodule.h index bb33eb8..010f4a6 100644 --- a/src/H5Smodule.h +++ b/src/H5Smodule.h @@ -30,29 +30,36 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5S H5S - * \brief Dataspace Interface * - * \details The Dataspace Interface provides functions for creating and - * working with dataspaces. + * Use the functions in this module to manage HDF5 dataspaces \Emph{and} selections. * - * A dataspace has two roles: + * HDF5 dataspaces describe the \Emph{shape} of datasets in memory or in HDF5 + * files. Dataspaces can be empty (#H5S_NULL), a singleton (#H5S_SCALAR), or + * a multi-dimensional, regular grid (#H5S_SIMPLE). Dataspaces can be re-shaped. * - * \li It contains the spatial information (logical layout) of a - * dataset stored in a file. - * \li It describes an application’s data buffers and data elements - * participating in I/O. In other words, it can be used to - * select a portion or subset of a dataset. + * Subsets of dataspaces can be "book-marked" or used to restrict I/O operations + * using \Emph{selections}. Furthermore, certain set operations are supported + * for selections. * - * The spatial information of a dataset in a file includes the - * rank and dimensions of the dataset, which are a permanent part - * of the dataset definition. It can have dimensions that are fixed - * (unchanging) or unlimited, which means they can grow in size - * (or are extendible). - * - * A dataspace can consist of: - * \li no elements (NULL) - * \li a single element (scalar), or - * \li a simple array. + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5S_examples.c create + * </td> + * <td> + * \snippet{lineno} H5S_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5S_examples.c update + * </td> + * <td> + * \snippet{lineno} H5S_examples.c delete + * </td> + * </tr> + * </table> * */ diff --git a/src/H5Spublic.h b/src/H5Spublic.h index 7962035..30ca813 100644 --- a/src/H5Spublic.h +++ b/src/H5Spublic.h @@ -26,98 +26,101 @@ #define H5S_BLOCK 1 /* (hid_t) */ #define H5S_PLIST 2 /* (hid_t) */ -/* Define value for 'unlimited' dimensions */ -#define H5S_UNLIMITED HSIZE_UNDEF +#define H5S_UNLIMITED HSIZE_UNDEF /**< Value for 'unlimited' dimensions */ -/* Define user-level maximum number of dimensions */ +/** + * The maximum dataspace rank or number of dimensions + */ #define H5S_MAX_RANK 32 /* Flags for selection iterators */ #define H5S_SEL_ITER_GET_SEQ_LIST_SORTED \ - 0x0001 /* Retrieve elements from iterator \ - * in increasing offset order, for \ - * each call to retrieve sequences. \ - * Currently, this only applies to \ - * point selections, as hyperslab \ - * selections are always returned \ - * in increasing offset order. \ - * \ - * Note that the order is only \ - * increasing for each call to \ - * get_seq_list, the next set of \ - * sequences could start with an \ - * earlier offset than the previous \ - * one. \ + 0x0001 /**< Retrieve elements from iterator in increasing offset order, for \ + * each call to retrieve sequences. Currently, this only applies to \ + * point selections, as hyperslab selections are always returned in \ + * increasing offset order. Note that the order is only increasing \ + * for each call to H5Sget_seq_list(), the next set of sequences \ + * could start with an earlier offset than the previous one. \ */ #define H5S_SEL_ITER_SHARE_WITH_DATASPACE \ - 0x0002 /* Don't copy the dataspace \ - * selection when creating the \ - * selection iterator. \ - * \ - * This can improve performance \ - * of creating the iterator, but \ - * the dataspace _MUST_NOT_ be \ - * modified or closed until the \ - * selection iterator is closed \ - * or the iterator's behavior \ - * will be undefined. \ + 0x0002 /**< Don't copy the dataspace selection when creating the selection \ + * iterator. This can improve performance of creating the iterator, \ + * but the dataspace \Bold{MUST NOT} be modified or closed until the \ + * selection iterator is closed or the iterator's behavior will be \ + * undefined. \ */ -/* Different types of dataspaces */ +/** + * Types of dataspaces + */ typedef enum H5S_class_t { - H5S_NO_CLASS = -1, /*error */ - H5S_SCALAR = 0, /*scalar variable */ - H5S_SIMPLE = 1, /*simple dataspace */ - H5S_NULL = 2 /*null dataspace */ + H5S_NO_CLASS = -1, /**< Error */ + H5S_SCALAR = 0, /**< Singleton (scalar) */ + H5S_SIMPLE = 1, /**< Regular grid */ + H5S_NULL = 2 /**< Empty set */ } H5S_class_t; -/* Different ways of combining selections */ +/** + * Different ways of combining selections + */ typedef enum H5S_seloper_t { - H5S_SELECT_NOOP = -1, /* error */ - H5S_SELECT_SET = 0, /* Select "set" operation */ - H5S_SELECT_OR, /* Binary "or" operation for hyperslabs + H5S_SELECT_NOOP = -1, /**< Error */ + H5S_SELECT_SET = 0, /**< Select "set" operation */ + H5S_SELECT_OR, /**< Binary "or" operation for hyperslabs * (add new selection to existing selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A or B: CCCCCCCCCCCCCCCC + * \endcode */ - H5S_SELECT_AND, /* Binary "and" operation for hyperslabs + H5S_SELECT_AND, /**< Binary "and" operation for hyperslabs * (only leave overlapped regions in selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A and B: CCCC + * \endcode */ - H5S_SELECT_XOR, /* Binary "xor" operation for hyperslabs + H5S_SELECT_XOR, /**< Binary "xor" operation for hyperslabs * (only leave non-overlapped regions in selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A xor B: CCCCCC CCCCCC + * \endcode */ - H5S_SELECT_NOTB, /* Binary "not" operation for hyperslabs + H5S_SELECT_NOTB, /**< Binary "not" operation for hyperslabs * (only leave non-overlapped regions in original selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A not B: CCCCCC + * \endcode */ - H5S_SELECT_NOTA, /* Binary "not" operation for hyperslabs + H5S_SELECT_NOTA, /**< Binary "not" operation for hyperslabs * (only leave non-overlapped regions in new selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * B not A: CCCCCC + * \endcode */ - H5S_SELECT_APPEND, /* Append elements to end of point selection */ - H5S_SELECT_PREPEND, /* Prepend elements to beginning of point selection */ - H5S_SELECT_INVALID /* Invalid upper bound on selection operations */ + H5S_SELECT_APPEND, /**< Append elements to end of point selection */ + H5S_SELECT_PREPEND, /**< Prepend elements to beginning of point selection */ + H5S_SELECT_INVALID /**< Invalid upper bound on selection operations */ } H5S_seloper_t; -/* Enumerated type for the type of selection */ +/** + * Selection type + */ typedef enum { - H5S_SEL_ERROR = -1, /* Error */ - H5S_SEL_NONE = 0, /* Nothing selected */ - H5S_SEL_POINTS = 1, /* Points / elements selected */ - H5S_SEL_HYPERSLABS = 2, /* Hyperslab selected */ - H5S_SEL_ALL = 3, /* Entire extent selected */ - H5S_SEL_N /*THIS MUST BE LAST */ + H5S_SEL_ERROR = -1, /**< Error */ + H5S_SEL_NONE = 0, /**< Empty selection */ + H5S_SEL_POINTS = 1, /**< Set of points */ + H5S_SEL_HYPERSLABS = 2, /**< Hyperslab */ + H5S_SEL_ALL = 3, /**< Everything */ + H5S_SEL_N /**< Sentinel \internal THIS MUST BE LAST */ } H5S_sel_type; #ifdef __cplusplus @@ -1318,9 +1321,6 @@ H5_DLL herr_t H5Sset_extent_none(hid_t space_id); * \details H5Sset_extent_simple() sets or resets the size of an existing * dataspace. * - * \p rank is the dimensionality, or number of dimensions, of the - * dataspace. - * * \p dims is an array of size \p rank which contains the new size * of each dimension in the dataspace. \p max is an array of size * \p rank which contains the maximum size of each dimension in @@ -1329,10 +1329,6 @@ H5_DLL herr_t H5Sset_extent_none(hid_t space_id); * Any previous extent is removed from the dataspace, the dataspace * type is set to #H5S_SIMPLE, and the extent is set as specified. * - * Note that a dataset must be chunked if \p dims does not equal - * \p max. - * - * * \version 1.4.0 Fortran subroutine was introduced. * \since 1.0.0 * diff --git a/src/H5Tconv.c b/src/H5Tconv.c index 7ea3d4c..d11a2c7 100644 --- a/src/H5Tconv.c +++ b/src/H5Tconv.c @@ -7728,9 +7728,9 @@ herr_t H5T__conv_float_schar(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(FLOAT, SCHAR, float, signed char, SCHAR_MIN, SCHAR_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -7750,9 +7750,9 @@ herr_t H5T__conv_float_uchar(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(FLOAT, UCHAR, float, unsigned char, 0, UCHAR_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -7772,9 +7772,9 @@ herr_t H5T__conv_double_schar(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(DOUBLE, SCHAR, double, signed char, SCHAR_MIN, SCHAR_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -7794,9 +7794,9 @@ herr_t H5T__conv_double_uchar(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(DOUBLE, UCHAR, double, unsigned char, 0, UCHAR_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -7816,9 +7816,9 @@ herr_t H5T__conv_ldouble_schar(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(LDOUBLE, SCHAR, long double, signed char, SCHAR_MIN, SCHAR_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -7838,9 +7838,9 @@ herr_t H5T__conv_ldouble_uchar(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(LDOUBLE, UCHAR, long double, unsigned char, 0, UCHAR_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -7860,9 +7860,9 @@ herr_t H5T__conv_float_short(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(FLOAT, SHORT, float, short, SHRT_MIN, SHRT_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -7882,9 +7882,9 @@ herr_t H5T__conv_float_ushort(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(FLOAT, USHORT, float, unsigned short, 0, USHRT_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -7904,9 +7904,9 @@ herr_t H5T__conv_double_short(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(DOUBLE, SHORT, double, short, SHRT_MIN, SHRT_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -7926,9 +7926,9 @@ herr_t H5T__conv_double_ushort(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(DOUBLE, USHORT, double, unsigned short, 0, USHRT_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -7948,9 +7948,9 @@ herr_t H5T__conv_ldouble_short(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(LDOUBLE, SHORT, long double, short, SHRT_MIN, SHRT_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -7970,9 +7970,9 @@ herr_t H5T__conv_ldouble_ushort(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(LDOUBLE, USHORT, long double, unsigned short, 0, USHRT_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -7992,9 +7992,9 @@ herr_t H5T__conv_float_int(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(FLOAT, INT, float, int, INT_MIN, INT_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8014,9 +8014,9 @@ herr_t H5T__conv_float_uint(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(FLOAT, UINT, float, unsigned int, 0, UINT_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8036,9 +8036,9 @@ herr_t H5T__conv_double_int(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(DOUBLE, INT, double, int, INT_MIN, INT_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8058,9 +8058,9 @@ herr_t H5T__conv_double_uint(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(DOUBLE, UINT, double, unsigned int, 0, UINT_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8080,9 +8080,9 @@ herr_t H5T__conv_ldouble_int(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(LDOUBLE, INT, long double, int, INT_MIN, INT_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8102,9 +8102,9 @@ herr_t H5T__conv_ldouble_uint(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(LDOUBLE, UINT, long double, unsigned int, 0, UINT_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8124,9 +8124,9 @@ herr_t H5T__conv_float_long(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(FLOAT, LONG, float, long, LONG_MIN, LONG_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8146,9 +8146,9 @@ herr_t H5T__conv_float_ulong(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(FLOAT, ULONG, float, unsigned long, 0, ULONG_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8168,9 +8168,9 @@ herr_t H5T__conv_double_long(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(DOUBLE, LONG, double, long, LONG_MIN, LONG_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8190,9 +8190,9 @@ herr_t H5T__conv_double_ulong(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(DOUBLE, ULONG, double, unsigned long, 0, ULONG_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8212,9 +8212,9 @@ herr_t H5T__conv_ldouble_long(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(LDOUBLE, LONG, long double, long, LONG_MIN, LONG_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8234,9 +8234,9 @@ herr_t H5T__conv_ldouble_ulong(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(LDOUBLE, ULONG, long double, unsigned long, 0, ULONG_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8256,9 +8256,9 @@ herr_t H5T__conv_float_llong(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(FLOAT, LLONG, float, long long, LLONG_MIN, LLONG_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8278,9 +8278,9 @@ herr_t H5T__conv_float_ullong(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(FLOAT, ULLONG, float, unsigned long long, 0, ULLONG_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8300,9 +8300,9 @@ herr_t H5T__conv_double_llong(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(DOUBLE, LLONG, double, long long, LLONG_MIN, LLONG_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8322,9 +8322,9 @@ herr_t H5T__conv_double_ullong(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(DOUBLE, ULLONG, double, unsigned long long, 0, ULLONG_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } /*------------------------------------------------------------------------- @@ -8345,9 +8345,9 @@ herr_t H5T__conv_ldouble_llong(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(LDOUBLE, LLONG, long double, long long, LLONG_MIN, LLONG_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } #endif /*H5T_CONV_INTERNAL_LDOUBLE_LLONG*/ @@ -8369,9 +8369,9 @@ herr_t H5T__conv_ldouble_ullong(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t H5_ATTR_UNUSED bkg_stride, void *buf, void H5_ATTR_UNUSED *bkg) { - H5_GCC_DIAG_OFF("float-equal") + H5_GCC_CLANG_DIAG_OFF("float-equal") H5T_CONV_Fx(LDOUBLE, ULLONG, long double, unsigned long long, 0, ULLONG_MAX); - H5_GCC_DIAG_ON("float-equal") + H5_GCC_CLANG_DIAG_ON("float-equal") } #endif /*H5T_CONV_INTERNAL_LDOUBLE_ULLONG*/ diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h index c489edc..73424fb 100644 --- a/src/H5Tmodule.h +++ b/src/H5Tmodule.h @@ -29,10 +29,38 @@ #define H5_MY_PKG_ERR H5E_DATATYPE #define H5_MY_PKG_INIT YES -/** - * \defgroup H5T H5T - * \brief Datatype Interface - * \todo Describe concisely what the functions in this module are about. +/**\defgroup H5T H5T + * + * Use the functions in this module to manage HDF5 datatypes. + * + * HDF5 datatypes describe the element type of HDF5 datasets and attributes. + * There's a large set of predefined datatypes, but users may find it useful + * to define new datatypes through a process called \Emph{derivation}. + * + * The element type is automatically persisted as part of the HDF5 metadata of + * attributes and datasets. Additionally, datatype definitions can be persisted + * to HDF5 files and linked to groups as HDF5 datatype objects or so-called + * \Emph{committed datatypes}. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5T_examples.c create + * </td> + * <td> + * \snippet{lineno} H5T_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5T_examples.c update + * </td> + * <td> + * \snippet{lineno} H5T_examples.c delete + * </td> + * </tr> + * </table> * * \defgroup ARRAY Array Datatypes * \ingroup H5T diff --git a/src/H5VLint.c b/src/H5VLint.c index 956dad3..c1c477f 100644 --- a/src/H5VLint.c +++ b/src/H5VLint.c @@ -1809,7 +1809,7 @@ H5VL__get_connector_name(hid_t id, char *name /*out*/, size_t size) len = HDstrlen(cls->name); if (name) { - HDstrncpy(name, cls->name, MIN(len + 1, size)); + HDstrncpy(name, cls->name, size); if (len >= size) name[size - 1] = '\0'; } /* end if */ diff --git a/src/H5VLmodule.h b/src/H5VLmodule.h index 009c0e5..8fcb961 100644 --- a/src/H5VLmodule.h +++ b/src/H5VLmodule.h @@ -27,14 +27,12 @@ #define H5_MY_PKG_ERR H5E_VOL #define H5_MY_PKG_INIT YES -/** - * \defgroup H5VL H5VL - * \brief Virtual Object Layer Interface - * \todo Describe concisely what the functions in this module are about. +/**\defgroup H5VL H5VL + * + * \todo Describe the VOL plugin life cycle. * * \defgroup ASYNC Asynchronous Functions * \brief Asynchronous Functions - * \todo Describe concisely what the functions in this module are about. * * \defgroup H5VLDEF Definitions * \ingroup H5VL diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h index 76a2380..9312b72 100644 --- a/src/H5Zmodule.h +++ b/src/H5Zmodule.h @@ -29,57 +29,80 @@ #define H5_MY_PKG_ERR H5E_PLINE #define H5_MY_PKG_INIT YES -/** - * \defgroup H5Z H5Z +/**\defgroup H5Z H5Z * + * Use the functions in this module to manage HDF5 filters. * - * \brief Filter and Compression Interface + * User-defined filters are created by registering a filter descriptor of + * type #H5Z_class_t with the library. * - * \details The functions in this module let you configure filters that process - * data during I/O operation. + * Available filters can be read or examined at runtime. * - * HDF5 supports a filter pipeline that provides the capability for - * standard and customized raw data processing during I/O operations. - * HDF5 is distributed with a small set of standard filters such as - * compression (gzip, SZIP, and a shuffling algorithm) and error - * checking (Fletcher32 checksum). For further flexibility, the - * library allows a user application to extend the pipeline through - * the creation and registration of customized filters. + * It is conceivable that filters are stateful and that that state be + * updated at runtime. * - * The flexibility of the filter pipeline implementation enables the - * definition of additional filters by a user application. A filter - * \li is associated with a dataset when the dataset is created, - * \li can be used only with chunked data (i.e., datasets stored in - * the #H5D_CHUNKED storage layout), and - * \li is applied independently to each chunk of the dataset. + * Filters are deleted by unregistering. * - * The HDF5 library does not support filters for contiguous datasets - * because of the difficulty of implementing random access for partial - * I/O. Compact dataset filters are not supported because it would not - * produce significant results. + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5Z_examples.c filter + * \snippet{lineno} H5Z_examples.c create + * </td> + * <td> + * \snippet{lineno} H5Z_examples.c read + * </td> + * </tr> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5Z_examples.c update + * </td> + * <td> + * \snippet{lineno} H5Z_examples.c delete + * </tr> + * </table> * - * Filter identifiers for the filters distributed with the HDF5 - * Library are as follows: - * <table> - * <tr><td>#H5Z_FILTER_DEFLATE</td><td>The gzip compression, or - * deflation, filter</td></tr> - * <tr><td>#H5Z_FILTER_SZIP</td><td>The SZIP compression - * filter</td></tr> - * <tr><td>#H5Z_FILTER_NBIT</td><td>The N-bit compression - * filter</td></tr> - * <tr><td>#H5Z_FILTER_SCALEOFFSET</td><td>The scale-offset - * compression filter</td></tr> - * <tr><td>#H5Z_FILTER_SHUFFLE</td><td>The shuffle algorithm - * filter</td></tr> - * <tr><td>#H5Z_FILTER_FLETCHER32</td><td>The Fletcher32 checksum, - * or error checking, filter</td></tr> - * </table> - * Custom filters that have been registered with the library will have - * additional unique identifiers. + * HDF5 supports a filter pipeline that provides the capability for standard and + * customized raw data processing during I/O operations. HDF5 is distributed + * with a small set of standard filters such as compression (gzip, SZIP, and a + * shuffling algorithm) and error checking (Fletcher32 checksum). For further + * flexibility, the library allows a user application to extend the pipeline + * through the creation and registration of customized filters. * - * See \ref_dld_filters for more information on how an HDF5 - * application can apply a filter that is not registered with the HDF5 - * library. + * The flexibility of the filter pipeline implementation enables the definition + * of additional filters by a user application. A filter + * \li is associated with a dataset when the dataset is created, + * \li can be used only with chunked data (i.e., datasets stored in the + * #H5D_CHUNKED storage layout), and + * \li is applied independently to each chunk of the dataset. + * + * The HDF5 library does not support filters for contiguous datasets because of + * the difficulty of implementing random access for partial I/O. Compact dataset + * filters are not supported because it would not produce significant results. + * + * Filter identifiers for the filters distributed with the HDF5 + * Library are as follows: + * <table> + * <tr><td>#H5Z_FILTER_DEFLATE</td><td>The gzip compression, or + * deflation, filter</td></tr> + * <tr><td>#H5Z_FILTER_SZIP</td><td>The SZIP compression + * filter</td></tr> + * <tr><td>#H5Z_FILTER_NBIT</td><td>The N-bit compression + * filter</td></tr> + * <tr><td>#H5Z_FILTER_SCALEOFFSET</td><td>The scale-offset + * compression filter</td></tr> + * <tr><td>#H5Z_FILTER_SHUFFLE</td><td>The shuffle algorithm + * filter</td></tr> + * <tr><td>#H5Z_FILTER_FLETCHER32</td><td>The Fletcher32 checksum, + * or error checking, filter</td></tr> + * </table> + * Custom filters that have been registered with the library will have + * additional unique identifiers. + * + * See \ref_dld_filters for more information on how an HDF5 application can + * apply a filter that is not registered with the HDF5 library. * * \defgroup H5ZPRE Predefined Filters * \ingroup H5Z diff --git a/src/H5Ztrans.c b/src/H5Ztrans.c index 7d55efd..ab7e9be 100644 --- a/src/H5Ztrans.c +++ b/src/H5Ztrans.c @@ -1547,11 +1547,11 @@ H5Z_xform_create(const char *expr) (HDisdigit(expr[i - 1]) || (expr[i - 1] == '.')) && (HDisdigit(expr[i + 1]) || (expr[i + 1] == '-') || (expr[i + 1] == '+'))) continue; - } + } /* end if */ count++; - } - } + } /* end if */ + } /* end for */ /* When there are no "x"'s in the equation (ie, simple transform case), * we don't need to allocate any space since no array will have to be @@ -1749,11 +1749,19 @@ done: hbool_t H5Z_xform_noop(const H5Z_data_xform_t *data_xform_prop) { - hbool_t ret_value = FALSE; /* Return value */ + hbool_t ret_value = TRUE; /* Return value */ FUNC_ENTER_NOAPI_NOINIT_NOERR - ret_value = (data_xform_prop ? FALSE : TRUE); + if (data_xform_prop) { + ret_value = FALSE; + + /* Check for trivial data tranformation: expression = "x" */ + if ((HDstrlen(data_xform_prop->xform_exp) == 1) && data_xform_prop->dat_val_pointers && + (data_xform_prop->dat_val_pointers->num_ptrs == 1)) { + ret_value = TRUE; + } /* end if */ + } /* end if */ FUNC_LEAVE_NOAPI(ret_value) } /* H5Z_xform_noop() */ diff --git a/src/H5detect.c b/src/H5detect.c index 2e893cf..e8cded7 100644 --- a/src/H5detect.c +++ b/src/H5detect.c @@ -52,7 +52,7 @@ static const char *FileHeader = "\n\ /* Disable warning about cast increasing the alignment of the target type, * that's _exactly_ what this code is probing. -QAK */ -H5_GCC_DIAG_OFF("cast-align") +H5_GCC_CLANG_DIAG_OFF("cast-align") #if defined(__has_attribute) #if __has_attribute(no_sanitize_address) @@ -300,10 +300,10 @@ precision(detected_t *d) for (_byte_mask = (unsigned char)1; _byte_mask; _byte_mask = (unsigned char)(_byte_mask << 1)) { \ _buf1[_i] ^= _byte_mask; \ HDmemcpy((void *)&_v2, (const void *)_buf1, sizeof(TYPE)); \ - H5_GCC_DIAG_OFF("float-equal") \ + H5_GCC_CLANG_DIAG_OFF("float-equal") \ if (_v1 != _v2) \ _pad_mask[_i] |= _byte_mask; \ - H5_GCC_DIAG_ON("float-equal") \ + H5_GCC_CLANG_DIAG_ON("float-equal") \ _buf1[_i] ^= _byte_mask; \ } /* end for */ \ \ @@ -414,10 +414,10 @@ precision(detected_t *d) HDmemcpy(_buf + align_g[_ano] + (INFO.offset / 8), ((char *)&_val) + (INFO.offset / 8), \ (size_t)(INFO.precision / 8)); \ _val2 = *((TYPE *)(_buf + align_g[_ano])); \ - H5_GCC_DIAG_OFF("float-equal") \ + H5_GCC_CLANG_DIAG_OFF("float-equal") \ if (_val != _val2) \ H5LONGJMP(jbuf_g, 1); \ - H5_GCC_DIAG_ON("float-equal") \ + H5_GCC_CLANG_DIAG_ON("float-equal") \ /* End Cray Check */ \ (INFO.align) = align_g[_ano]; \ } \ @@ -1567,4 +1567,4 @@ main(int argc, char *argv[]) return EXIT_SUCCESS; } -H5_GCC_DIAG_ON("cast-align") +H5_GCC_CLANG_DIAG_ON("cast-align") diff --git a/src/H5module.h b/src/H5module.h index 64081bf..6d3cba8 100644 --- a/src/H5module.h +++ b/src/H5module.h @@ -27,8 +27,31 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5 H5 - * \brief General Library Functions - * \todo Describe concisely what the functions in this module are about. + * + * Use the functions in this module to manage the life cycle of HDF5 library + * instances. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5_examples.c create + * </td> + * <td> + * \snippet{lineno} H5_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet{lineno} H5_examples.c update + * </td> + * <td> + * \snippet{lineno} H5_examples.c closing_shop + * \snippet{lineno} H5_examples.c delete + * </td> + * </tr> + * </table> + * */ #endif /* H5module_H */ diff --git a/src/H5private.h b/src/H5private.h index 4b759f1..d392af3 100644 --- a/src/H5private.h +++ b/src/H5private.h @@ -451,7 +451,7 @@ #define LOCK_UN 0x08 #endif /* H5_HAVE_FLOCK */ -/* Macros for enabling/disabling particular GCC warnings +/* Macros for enabling/disabling particular GCC / clang warnings * * These are duplicated in H5FDmulti.c (we don't want to put them in the * public header and the multi VFD can't use private headers). If you make @@ -461,19 +461,45 @@ * http://www.dbp-consulting.com/tutorials/SuppressingGCCWarnings.html * http://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Pragmas.html#Diagnostic-Pragmas */ -/* These pragmas are only implemented usefully in gcc 4.6+ */ -#if ((__GNUC__ * 100) + __GNUC_MINOR__) >= 406 -#define H5_GCC_DIAG_JOINSTR(x, y) x y -#define H5_GCC_DIAG_DO_PRAGMA(x) _Pragma(#x) -#define H5_GCC_DIAG_PRAGMA(x) H5_GCC_DIAG_DO_PRAGMA(GCC diagnostic x) - -#define H5_GCC_DIAG_OFF(x) H5_GCC_DIAG_PRAGMA(push) H5_GCC_DIAG_PRAGMA(ignored H5_GCC_DIAG_JOINSTR("-W", x)) -#define H5_GCC_DIAG_ON(x) H5_GCC_DIAG_PRAGMA(pop) +#define H5_DIAG_JOINSTR(x, y) x y +#define H5_DIAG_DO_PRAGMA(x) _Pragma(#x) +#define H5_DIAG_PRAGMA(x) H5_DIAG_DO_PRAGMA(GCC diagnostic x) + +#define H5_DIAG_OFF(x) H5_DIAG_PRAGMA(push) H5_DIAG_PRAGMA(ignored H5_DIAG_JOINSTR("-W", x)) +#define H5_DIAG_ON(x) H5_DIAG_PRAGMA(pop) + +/* Macros for enabling/disabling particular GCC-only warnings. + * These pragmas are only implemented usefully in gcc 4.6+ + */ +#if (((__GNUC__ * 100) + __GNUC_MINOR__) >= 406) +#define H5_GCC_DIAG_OFF(x) H5_DIAG_OFF(x) +#define H5_GCC_DIAG_ON(x) H5_DIAG_ON(x) #else #define H5_GCC_DIAG_OFF(x) #define H5_GCC_DIAG_ON(x) #endif +/* Macros for enabling/disabling particular clang-only warnings. + */ +#if defined(__clang__) +#define H5_CLANG_DIAG_OFF(x) H5_DIAG_OFF(x) +#define H5_CLANG_DIAG_ON(x) H5_DIAG_ON(x) +#else +#define H5_CLANG_DIAG_OFF(x) +#define H5_CLANG_DIAG_ON(x) +#endif + +/* Macros for enabling/disabling particular GCC / clang warnings. + * These macros should be used for warnings supported by both gcc and clang. + */ +#if (((__GNUC__ * 100) + __GNUC_MINOR__) >= 406) || defined(__clang__) +#define H5_GCC_CLANG_DIAG_OFF(x) H5_DIAG_OFF(x) +#define H5_GCC_CLANG_DIAG_ON(x) H5_DIAG_ON(x) +#else +#define H5_GCC_CLANG_DIAG_OFF(x) +#define H5_GCC_CLANG_DIAG_ON(x) +#endif + /* Typedefs and functions for timing certain parts of the library. */ /* A set of elapsed/user/system times emitted as a time point by the diff --git a/src/H5public.h b/src/H5public.h index e7ed518..65709c6 100644 --- a/src/H5public.h +++ b/src/H5public.h @@ -172,8 +172,9 @@ * Status return values. Failed integer functions in HDF5 result almost * always in a negative value (unsigned failing functions sometimes return * zero for failure) while successful return is non-negative (often zero). - * The negative failure value is most commonly -1, but don't bet on it. The - * proper way to detect failure is something like: + * The negative failure value is most commonly -1, but don't bet on it. + * + * The proper way to detect failure is something like: * \code * if((dset = H5Dopen2(file, name)) < 0) * fprintf(stderr, "unable to open the requested dataset\n"); @@ -182,11 +183,17 @@ typedef int herr_t; /** - * Boolean type. Successful return values are zero (false) or positive - * (true). The typical true value is 1 but don't bet on it. Boolean - * functions cannot fail. Functions that return #htri_t however return zero - * (false), positive (true), or negative (failure). The proper way to test - * for truth from a #htri_t function is: + * C99-style Boolean type. Successful return values are zero (false) or positive + * (true). The typical true value is 1 but don't bet on it. + * \attention Boolean functions cannot fail. + */ +#include <stdbool.h> +typedef bool hbool_t; +/** + * Three-valued Boolean type. Functions that return #htri_t however return zero + * (false), positive (true), or negative (failure). + * + * The proper way to test for truth from a #htri_t function is: * \code * if ((retval = H5Tcommitted(type)) > 0) { * printf("data type is committed\n"); @@ -197,8 +204,7 @@ typedef int herr_t; * } * \endcode */ -typedef bool hbool_t; -typedef int htri_t; +typedef int htri_t; /* The signed version of size_t * @@ -285,9 +291,9 @@ typedef enum { /* (Actually, any positive value will cause the iterator to stop and pass back * that positive value to the function that called the iterator) */ -#define H5_ITER_ERROR (-1) -#define H5_ITER_CONT (0) -#define H5_ITER_STOP (1) +#define H5_ITER_ERROR (-1) /**< Error, stop iteration */ +#define H5_ITER_CONT (0) /**< Continue iteration */ +#define H5_ITER_STOP (1) /**< Stop iteration, short-circuit success */ //! <!-- [H5_index_t_snip] --> /** diff --git a/src/H5system.c b/src/H5system.c index fe379ad..9a966b0 100644 --- a/src/H5system.c +++ b/src/H5system.c @@ -732,8 +732,8 @@ H5_build_extpath(const char *name, char **extpath /*out*/) HDstrncpy(full_path, cwdpath, cwdlen + 1); if (!H5_CHECK_DELIMITER(cwdpath[cwdlen - 1])) - HDstrncat(full_path, H5_DIR_SEPS, HDstrlen(H5_DIR_SEPS)); - HDstrncat(full_path, new_name, HDstrlen(new_name)); + HDstrncat(full_path, H5_DIR_SEPS, path_len - (cwdlen + 1)); + HDstrncat(full_path, new_name, path_len - (cwdlen + 1) - HDstrlen(H5_DIR_SEPS)); } /* end if */ } /* end else */ @@ -277,7 +277,7 @@ error: * 'name' in the code below, but early (4.4.7, at least) gcc only * allows diagnostic pragmas to be toggled outside of functions. */ -H5_GCC_DIAG_OFF("format-nonliteral") +H5_GCC_CLANG_DIAG_OFF("format-nonliteral") static int enough_room(hid_t fapl) { @@ -319,7 +319,7 @@ done: return ret_value; } -H5_GCC_DIAG_ON("format-nonliteral") +H5_GCC_CLANG_DIAG_ON("format-nonliteral") /*------------------------------------------------------------------------- * Function: writer diff --git a/test/dtransform.c b/test/dtransform.c index 8d3a8c0..743103f 100644 --- a/test/dtransform.c +++ b/test/dtransform.c @@ -582,6 +582,7 @@ test_specials(hid_t file) const char *special4 = "-x"; const char *special5 = "+x"; const char *special6 = "2e+1*x"; + const char *special7 = "x"; TESTING("data transform of some special cases") @@ -729,6 +730,32 @@ test_specials(hid_t file) if (H5Dclose(dset_id) < 0) TEST_ERROR + /*----------------------------- + * Operation 7: x + * This operation will be + * treated if no function has + * been specified. + *----------------------------*/ + if (H5Pset_data_transform(dxpl_id, special7) < 0) + TEST_ERROR; + + for (row = 0; row < ROWS; row++) + for (col = 0; col < COLS; col++) + data_res[row][col] = transformData[row][col]; + + if ((dset_id = H5Dcreate2(file, "/special7", H5T_NATIVE_INT, dataspace, H5P_DEFAULT, H5P_DEFAULT, + H5P_DEFAULT)) < 0) + TEST_ERROR + if (H5Dwrite(dset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, dxpl_id, transformData) < 0) + TEST_ERROR + if (H5Dread(dset_id, H5T_NATIVE_INT, H5S_ALL, H5S_ALL, H5P_DEFAULT, read_buf) < 0) + TEST_ERROR + + COMPARE_INT(read_buf, data_res) + + if (H5Dclose(dset_id) < 0) + TEST_ERROR + if (H5Pclose(dxpl_id) < 0) TEST_ERROR if (H5Sclose(dataspace) < 0) diff --git a/test/error_test.c b/test/error_test.c index cf1e82c..f4dc340 100644 --- a/test/error_test.c +++ b/test/error_test.c @@ -319,7 +319,7 @@ long_desc_cb(unsigned H5_ATTR_UNUSED n, const H5E_error2_t *err_desc, void *clie * 'full_desc' in the code below, but early (4.4.7, at least) gcc only * allows diagnostic pragmas to be toggled outside of functions. */ -H5_GCC_DIAG_OFF("format-nonliteral") +H5_GCC_CLANG_DIAG_OFF("format-nonliteral") static herr_t test_long_desc(void) { @@ -375,7 +375,7 @@ error: return -1; } /* end test_long_desc() */ -H5_GCC_DIAG_ON("format-nonliteral") +H5_GCC_CLANG_DIAG_ON("format-nonliteral") /*------------------------------------------------------------------------- * Function: dump_error diff --git a/test/fheap.c b/test/fheap.c index cb9c080..86a555d 100644 --- a/test/fheap.c +++ b/test/fheap.c @@ -553,7 +553,7 @@ get_fill_size(const fheap_test_param_t *tparam) * test_desc in the code below, but early (4.4.7, at least) gcc only * allows diagnostic pragmas to be toggled outside of functions. */ -H5_GCC_DIAG_OFF("format-nonliteral") +H5_GCC_CLANG_DIAG_OFF("format-nonliteral") static int begin_test(fheap_test_param_t *tparam, const char *base_desc, fheap_heap_ids_t *keep_ids, size_t *fill_size) { @@ -581,7 +581,7 @@ begin_test(fheap_test_param_t *tparam, const char *base_desc, fheap_heap_ids_t * /* Success */ return (0); } /* end begin_test() */ -H5_GCC_DIAG_ON("format-nonliteral") +H5_GCC_CLANG_DIAG_ON("format-nonliteral") /*------------------------------------------------------------------------- * Function: reopen_file diff --git a/test/file_image.c b/test/file_image.c index 0373468..0d031f5 100644 --- a/test/file_image.c +++ b/test/file_image.c @@ -712,7 +712,7 @@ error: * 'member_file_name' in the code below, but early (4.4.7, at least) gcc only * allows diagnostic pragmas to be toggled outside of functions. */ -H5_GCC_DIAG_OFF("format-nonliteral") +H5_GCC_CLANG_DIAG_OFF("format-nonliteral") static int test_get_file_image(const char *test_banner, const int file_name_num, hid_t fapl, hbool_t user) { @@ -976,7 +976,7 @@ test_get_file_image(const char *test_banner, const int file_name_num, hid_t fapl error: return 1; } /* end test_get_file_image() */ -H5_GCC_DIAG_ON("format-nonliteral") +H5_GCC_CLANG_DIAG_ON("format-nonliteral") /****************************************************************************** * Function: test_get_file_image_error_rejection diff --git a/test/h5test.c b/test/h5test.c index 755ae93..ba0662a 100644 --- a/test/h5test.c +++ b/test/h5test.c @@ -1305,7 +1305,7 @@ h5_dump_info_object(MPI_Info info) * temp in the code below, but early (4.4.7, at least) gcc only * allows diagnostic pragmas to be toggled outside of functions. */ -H5_GCC_DIAG_OFF("format-nonliteral") +H5_GCC_CLANG_DIAG_OFF("format-nonliteral") h5_stat_size_t h5_get_file_size(const char *filename, hid_t fapl) { @@ -1410,7 +1410,7 @@ h5_get_file_size(const char *filename, hid_t fapl) return (-1); } /* end get_file_size() */ -H5_GCC_DIAG_ON("format-nonliteral") +H5_GCC_CLANG_DIAG_ON("format-nonliteral") /* * This routine is designed to provide equivalent functionality to 'printf' @@ -1925,6 +1925,7 @@ static const H5FD_class_t H5FD_dummy_g = { NULL, /* lock */ NULL, /* unlock */ NULL, /* del */ + NULL, /* ctl */ H5FD_FLMAP_DICHOTOMY /* fl_map */ }; diff --git a/test/ohdr.c b/test/ohdr.c index afcea87..d28b11e 100644 --- a/test/ohdr.c +++ b/test/ohdr.c @@ -541,7 +541,7 @@ test_unknown(unsigned bogus_id, char *filename, hid_t fapl) done in the source directory. */ HDstrncpy(testfile, FILE_BOGUS, TESTFILE_LEN); testfile[TESTFILE_LEN - 1] = '\0'; - HDstrncat(testfile, ".copy", 5); + HDstrncat(testfile, ".copy", sizeof(testfile) - HDstrlen(testfile) - 1); /* Make a copy of the data file from svn. */ if (h5_make_local_copy(FILE_BOGUS, testfile) < 0) @@ -48,20 +48,22 @@ #define DSET2_DIM 4 #endif /* H5_HAVE_DIRECT */ -const char *FILENAME[] = {"sec2_file", /*0*/ - "core_file", /*1*/ - "family_file", /*2*/ - "new_family_v16_", /*3*/ - "multi_file", /*4*/ - "direct_file", /*5*/ - "log_file", /*6*/ - "stdio_file", /*7*/ - "windows_file", /*8*/ - "new_multi_file_v16", /*9*/ - "ro_s3_file", /*10*/ - "splitter_rw_file", /*11*/ - "splitter_wo_file", /*12*/ - "splitter.log", /*13*/ +const char *FILENAME[] = {"sec2_file", /*0*/ + "core_file", /*1*/ + "family_file", /*2*/ + "new_family_v16_", /*3*/ + "multi_file", /*4*/ + "direct_file", /*5*/ + "log_file", /*6*/ + "stdio_file", /*7*/ + "windows_file", /*8*/ + "new_multi_file_v16", /*9*/ + "ro_s3_file", /*10*/ + "splitter_rw_file", /*11*/ + "splitter_wo_file", /*12*/ + "splitter.log", /*13*/ + "ctl_file", /*14*/ + "ctl_splitter_wo_file", /*15*/ NULL}; #define LOG_FILENAME "log_vfd_out.log" @@ -94,6 +96,13 @@ struct splitter_dataset_def { int n_dims; /* rank */ }; +/* Op code type enum for ctl callback test */ +typedef enum { + CTL_OPC_KNOWN_PASSTHROUGH, /* op code known to passthrough VFD */ + CTL_OPC_KNOWN_TERMINAL, /* op code known to terminal VFD */ + CTL_OPC_UNKNOWN /* unknown op code */ +} ctl_test_opc_type; + static int splitter_prepare_file_paths(H5FD_splitter_vfd_config_t *vfd_config, char *filename_rw_out); static int splitter_create_single_file_at(const char *filename, hid_t fapl_id, const struct splitter_dataset_def *data); @@ -104,6 +113,19 @@ static int splitter_RO_test(const struct splitter_dataset_def *data, hid_t child static int splitter_tentative_open_test(hid_t child_fapl_id); static int file_exists(const char *filename, hid_t fapl_id); +static herr_t run_ctl_test(uint64_t op_code, uint64_t flags, ctl_test_opc_type opc_type, hid_t fapl_id); +static H5FD_t *H5FD__ctl_test_vfd_open(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr); +static herr_t H5FD__ctl_test_vfd_close(H5FD_t *_file); +static haddr_t H5FD__ctl_test_vfd_get_eoa(const H5FD_t *_file, H5FD_mem_t type); +static herr_t H5FD__ctl_test_vfd_set_eoa(H5FD_t *_file, H5FD_mem_t type, haddr_t addr); +static haddr_t H5FD__ctl_test_vfd_get_eof(const H5FD_t *_file, H5FD_mem_t type); +static herr_t H5FD__ctl_test_vfd_read(H5FD_t *_file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, + size_t size, void *buf); +static herr_t H5FD__ctl_test_vfd_write(H5FD_t *_file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, + size_t size, const void *buf); +static herr_t H5FD__ctl_test_vfd_ctl(H5FD_t *_file, uint64_t op_code, uint64_t flags, const void *input, + void **output); + /*------------------------------------------------------------------------- * Function: test_sec2 * @@ -859,7 +881,7 @@ error: * 'first_name' in the code below, but early (4.4.7, at least) gcc only * allows diagnostic pragmas to be toggled outside of functions. */ -H5_GCC_DIAG_OFF("format-nonliteral") +H5_GCC_CLANG_DIAG_OFF("format-nonliteral") static herr_t test_family_opens(char *fname, hid_t fa_pl) { @@ -924,7 +946,7 @@ test_family_opens(char *fname, hid_t fa_pl) error: return -1; } /* end test_family_opens() */ -H5_GCC_DIAG_ON("format-nonliteral") +H5_GCC_CLANG_DIAG_ON("format-nonliteral") /*------------------------------------------------------------------------- * Function: test_family @@ -1150,7 +1172,7 @@ error: * 'newname_individual', etc. in the code below, but early (4.4.7, at least) gcc only * allows diagnostic pragmas to be toggled outside of functions. */ -H5_GCC_DIAG_OFF("format-nonliteral") +H5_GCC_CLANG_DIAG_OFF("format-nonliteral") static herr_t test_family_compat(void) { @@ -1236,7 +1258,7 @@ error: return -1; } /* end test_family_compat() */ -H5_GCC_DIAG_ON("format-nonliteral") +H5_GCC_CLANG_DIAG_ON("format-nonliteral") /*------------------------------------------------------------------------- * Function: test_family_member_fapl @@ -1376,7 +1398,7 @@ error: * 'sf_name' in the code below, but early (4.4.7, at least) gcc only * allows diagnostic pragmas to be toggled outside of functions. */ -H5_GCC_DIAG_OFF("format-nonliteral") +H5_GCC_CLANG_DIAG_OFF("format-nonliteral") static herr_t test_multi_opens(char *fname) { @@ -1396,7 +1418,7 @@ test_multi_opens(char *fname) return (fid >= 0 ? FAIL : SUCCEED); } /* end test_multi_opens() */ -H5_GCC_DIAG_ON("format-nonliteral") +H5_GCC_CLANG_DIAG_ON("format-nonliteral") /*------------------------------------------------------------------------- * Function: test_multi @@ -3398,6 +3420,499 @@ error: #undef SPLITTER_TEST_FAULT +/* + * Callback implementations for ctl feature testing VFD + */ +static H5FD_t * +H5FD__ctl_test_vfd_open(const char H5_ATTR_UNUSED *name, unsigned H5_ATTR_UNUSED flags, + hid_t H5_ATTR_UNUSED fapl_id, haddr_t H5_ATTR_UNUSED maxaddr) +{ + return HDcalloc(1, sizeof(H5FD_t)); +} +static herr_t +H5FD__ctl_test_vfd_close(H5FD_t H5_ATTR_UNUSED *_file) +{ + HDfree(_file); + return SUCCEED; +} +static haddr_t +H5FD__ctl_test_vfd_get_eoa(const H5FD_t H5_ATTR_UNUSED *file, H5FD_mem_t H5_ATTR_UNUSED type) +{ + return HADDR_UNDEF; +} +static herr_t +H5FD__ctl_test_vfd_set_eoa(H5FD_t H5_ATTR_UNUSED *_file, H5FD_mem_t H5_ATTR_UNUSED type, + haddr_t H5_ATTR_UNUSED addr) +{ + return FAIL; +} +static haddr_t +H5FD__ctl_test_vfd_get_eof(const H5FD_t H5_ATTR_UNUSED *file, H5FD_mem_t H5_ATTR_UNUSED type) +{ + return HADDR_UNDEF; +} +static herr_t +H5FD__ctl_test_vfd_read(H5FD_t H5_ATTR_UNUSED *_file, H5FD_mem_t H5_ATTR_UNUSED type, + hid_t H5_ATTR_UNUSED fapl_id, haddr_t H5_ATTR_UNUSED addr, size_t H5_ATTR_UNUSED size, + void H5_ATTR_UNUSED *buf) +{ + return FAIL; +} +static herr_t +H5FD__ctl_test_vfd_write(H5FD_t H5_ATTR_UNUSED *_file, H5FD_mem_t H5_ATTR_UNUSED type, + hid_t H5_ATTR_UNUSED fapl_id, haddr_t H5_ATTR_UNUSED addr, + size_t H5_ATTR_UNUSED size, const void H5_ATTR_UNUSED *buf) +{ + return FAIL; +} +static herr_t +H5FD__ctl_test_vfd_ctl(H5FD_t H5_ATTR_UNUSED *_file, uint64_t op_code, uint64_t flags, + const void H5_ATTR_UNUSED *input, void H5_ATTR_UNUSED **output) +{ + herr_t ret_value = SUCCEED; + + switch (op_code) { + /* Op code for testing purposes */ + case H5FD_CTL__TEST_OPCODE: + break; + + /* Unknown op code */ + default: + if (flags & H5FD_CTL__FAIL_IF_UNKNOWN_FLAG) + ret_value = FAIL; + break; + } + + return ret_value; +} + +/* Minimal VFD for ctl feature tests */ +static const H5FD_class_t H5FD_ctl_test_vfd_g = { + "ctl_test_vfd", /* name */ + HADDR_MAX, /* maxaddr */ + H5F_CLOSE_SEMI, /* fc_degree */ + NULL, /* terminate */ + NULL, /* sb_size */ + NULL, /* sb_encode */ + NULL, /* sb_decode */ + 0, /* fapl_size */ + NULL, /* fapl_get */ + NULL, /* fapl_copy */ + NULL, /* fapl_free */ + 0, /* dxpl_size */ + NULL, /* dxpl_copy */ + NULL, /* dxpl_free */ + H5FD__ctl_test_vfd_open, /* open */ + H5FD__ctl_test_vfd_close, /* close */ + NULL, /* cmp */ + NULL, /* query */ + NULL, /* get_type_map */ + NULL, /* alloc */ + NULL, /* free */ + H5FD__ctl_test_vfd_get_eoa, /* get_eoa */ + H5FD__ctl_test_vfd_set_eoa, /* set_eoa */ + H5FD__ctl_test_vfd_get_eof, /* get_eof */ + NULL, /* get_handle */ + H5FD__ctl_test_vfd_read, /* read */ + H5FD__ctl_test_vfd_write, /* write */ + NULL, /* flush */ + NULL, /* truncate */ + NULL, /* lock */ + NULL, /* unlock */ + NULL, /* del */ + H5FD__ctl_test_vfd_ctl, /* ctl */ + H5FD_FLMAP_DICHOTOMY /* fl_map */ +}; + +/*------------------------------------------------------------------------- + * Function: run_ctl_test + * + * Purpose: Helper method for VFD "ctl" callback test + * + * Return: Non-negative on success/Negative on failure + * + *------------------------------------------------------------------------- + */ +static herr_t +run_ctl_test(uint64_t op_code, uint64_t flags, ctl_test_opc_type opc_type, hid_t fapl_id) +{ + hbool_t fail_if_unknown = FALSE; + hbool_t routing_flag_set = FALSE; + hbool_t is_passthrough_vfd = FALSE; + hbool_t expect_fail = FALSE; + H5FD_t *file_drv_ptr = NULL; + herr_t ctl_result = SUCCEED; + hid_t driver_id = H5I_INVALID_HID; + char filename[1024]; + + /* Check for a few ctl function flags */ + fail_if_unknown = (flags & H5FD_CTL__FAIL_IF_UNKNOWN_FLAG); + routing_flag_set = (flags & H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG); + + /* Determine if the top-level VFD is a passthrough VFD */ + if ((driver_id = H5Pget_driver(fapl_id)) < 0) + PUTS_ERROR("couldn't get VFD ID from FAPL"); + + is_passthrough_vfd = ((driver_id == H5FD_SPLITTER) || (driver_id == H5FD_MULTI)); + + /* + * "Open" testing file. Note that our VFD for testing the ctl + * feature doesn't actually create or open files, so we don't + * need to create the testing file; we just need the VFD to + * give us a pointer to a H5FD_t structure. + */ + h5_fixname(FILENAME[14], fapl_id, filename, sizeof(filename)); + if (NULL == (file_drv_ptr = H5FDopen(filename, H5F_ACC_RDWR, fapl_id, HADDR_UNDEF))) + PUTS_ERROR("couldn't get pointer to H5FD_t structure"); + + /* Determine whether the H5FDctl call is expected to fail */ + expect_fail = fail_if_unknown && (CTL_OPC_UNKNOWN == opc_type); + if (is_passthrough_vfd) { + /* Should fail if op code is unknown to passthrough VFD + * (but known to terminal VFD), no routing flag is specified + * and the "fail if unknown" flag is specified. + */ + expect_fail = + expect_fail || ((CTL_OPC_KNOWN_TERMINAL == opc_type) && !routing_flag_set && fail_if_unknown); + } + + /* Issue opcode to VFD */ + if (expect_fail) { + H5E_BEGIN_TRY + { + ctl_result = H5FDctl(file_drv_ptr, op_code, flags, NULL, NULL); + } + H5E_END_TRY; + } + else + ctl_result = H5FDctl(file_drv_ptr, op_code, flags, NULL, NULL); + + /* Verify result of H5FDctl call */ + if (expect_fail) { + if (ctl_result == SUCCEED) + PUTS_ERROR("H5FDctl call succeeded when it should have failed"); + } + else { + if (ctl_result != SUCCEED) + PUTS_ERROR("H5FDctl call failed when it should have succeeded"); + } + + /* Close H5FD_t structure pointer */ + if (H5FDclose(file_drv_ptr) < 0) + PUTS_ERROR("couldn't close H5FD_t structure pointer"); + file_drv_ptr = NULL; + + return 0; + +error: + H5E_BEGIN_TRY + { + H5FDclose(file_drv_ptr); + } + H5E_END_TRY; + + return -1; +} + +/*------------------------------------------------------------------------- + * Function: test_ctl + * + * Purpose: Tests the VFD "ctl" callback + * + * Return: Non-negative on success/Negative on failure + * + *------------------------------------------------------------------------- + */ +static herr_t +test_ctl(void) +{ + H5FD_splitter_vfd_config_t *splitter_config = NULL; + uint64_t op_code; + uint64_t flags; + hid_t driver_id = H5I_INVALID_HID; + hid_t fapl_id = H5I_INVALID_HID; + hid_t sub_fapl_id = H5I_INVALID_HID; + + TESTING("VFD ctl callback"); + HDputs(""); + + /* Register VFD for test */ + if ((driver_id = H5FDregister(&H5FD_ctl_test_vfd_g)) < 0) + PUTS_ERROR("couldn't register VFD for testing"); + + if ((fapl_id = H5Pcreate(H5P_FILE_ACCESS)) < 0) + PUTS_ERROR("couldn't create FAPL"); + if (H5Pset_driver(fapl_id, driver_id, NULL) < 0) + PUTS_ERROR("couldn't set testing VFD on FAPL"); + + TESTING_2("known op code to terminal VFD (without fail on unknown flag)") + + op_code = H5FD_CTL__TEST_OPCODE; + flags = 0; + + /* H5FDctl call should succeed normally */ + if (run_ctl_test(op_code, flags, CTL_OPC_KNOWN_TERMINAL, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("known op code to terminal VFD (with fail on unknown flag)") + + op_code = H5FD_CTL__TEST_OPCODE; + flags = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG; + + /* H5FDctl call should succeed normally */ + if (run_ctl_test(op_code, flags, CTL_OPC_KNOWN_TERMINAL, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("known op code to terminal VFD (without fail on unknown flag/route to terminal VFD)") + + op_code = H5FD_CTL__TEST_OPCODE; + flags = H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG; + + /* H5FDctl call should succeed normally */ + if (run_ctl_test(op_code, flags, CTL_OPC_KNOWN_TERMINAL, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("known op code to terminal VFD (with fail on unknown flag/route to terminal VFD)") + + op_code = H5FD_CTL__TEST_OPCODE; + flags = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG | H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG; + + /* H5FDctl call should succeed normally */ + if (run_ctl_test(op_code, flags, CTL_OPC_KNOWN_TERMINAL, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("unknown op code to terminal VFD (without fail on unknown flag)") + + op_code = H5FD_CTL_OPC_RESERVED; + flags = 0; + + /* H5FDctl call should silently ignore unknown op code and succeed */ + if (run_ctl_test(op_code, flags, CTL_OPC_UNKNOWN, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("unknown op code to terminal VFD (with fail on unknown flag)") + + op_code = H5FD_CTL_OPC_RESERVED; + flags = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG; + + /* H5FDctl call should fail due to 'fail if unknown' flag being specified */ + if (run_ctl_test(op_code, flags, CTL_OPC_UNKNOWN, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("unknown op code to terminal VFD (without fail on unknown flag/route to terminal VFD)") + + op_code = H5FD_CTL_OPC_RESERVED; + flags = H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG; + + /* H5FDctl call should silently ignore unknown op code and succeed */ + if (run_ctl_test(op_code, flags, CTL_OPC_UNKNOWN, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("unknown op code to terminal VFD (with fail on unknown flag/route to terminal VFD)") + + op_code = H5FD_CTL_OPC_RESERVED; + flags = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG | H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG; + + /* H5FDctl call should fail due to 'fail if unknown' flag being specified */ + if (run_ctl_test(op_code, flags, CTL_OPC_UNKNOWN, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + /* Set up splitter VFD config */ + if (NULL == (splitter_config = HDcalloc(1, sizeof(H5FD_splitter_vfd_config_t)))) + TEST_ERROR; + + splitter_config->magic = H5FD_SPLITTER_MAGIC; + splitter_config->version = H5FD_CURR_SPLITTER_VFD_CONFIG_VERSION; + splitter_config->ignore_wo_errs = TRUE; + splitter_config->rw_fapl_id = H5P_DEFAULT; + splitter_config->wo_fapl_id = H5P_DEFAULT; + h5_fixname(FILENAME[15], splitter_config->wo_fapl_id, splitter_config->wo_path, H5FD_SPLITTER_PATH_MAX); + + if ((sub_fapl_id = H5Pcreate(H5P_FILE_ACCESS)) < 0) + PUTS_ERROR("couldn't create FAPL"); + if (H5Pset_driver(sub_fapl_id, driver_id, NULL) < 0) + PUTS_ERROR("couldn't set testing VFD on FAPL"); + splitter_config->rw_fapl_id = sub_fapl_id; + + if (H5Pset_fapl_splitter(fapl_id, splitter_config) < 0) + PUTS_ERROR("couldn't set splitter VFD on FAPL"); + + TESTING_2("known op code through passthrough VFD to terminal VFD (without fail on unknown flag/no " + "routing flag)") + + op_code = H5FD_CTL__TEST_OPCODE; + flags = 0; + + /* + * H5FDctl call should silently ignore unknown op code in + * passthrough VFD since no routing flag is specified and + * 'fail if unknown' flag is not specified. + */ + if (run_ctl_test(op_code, flags, CTL_OPC_KNOWN_TERMINAL, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2( + "known op code through passthrough VFD to terminal VFD (with fail on unknown flag/no routing flag)") + + op_code = H5FD_CTL__TEST_OPCODE; + flags = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG; + + /* + * H5FDctl call should fail since op code is unknown to + * passthrough VFD (though known to terminal VFD), no + * routing flag is specified and the 'fail if unknown' + * flag is specified. + */ + if (run_ctl_test(op_code, flags, CTL_OPC_KNOWN_TERMINAL, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("known op code through passthrough VFD to terminal VFD (without fail on unknown flag/route to " + "terminal VFD)") + + op_code = H5FD_CTL__TEST_OPCODE; + flags = H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG; + + /* + * H5Dctl call should succeed since the passthrough VFD + * doesn't recognize the op code, but has been instructed + * to route it down to the terminal VFD. + */ + if (run_ctl_test(op_code, flags, CTL_OPC_KNOWN_TERMINAL, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("known op code through passthrough VFD to terminal VFD (with fail on unknown flag/route to " + "terminal VFD)") + + op_code = H5FD_CTL__TEST_OPCODE; + flags = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG | H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG; + + /* + * H5Dctl call should succeed since the passthrough VFD + * doesn't recognize the op code, but has been instructed + * to route it down to the terminal VFD. + */ + if (run_ctl_test(op_code, flags, CTL_OPC_KNOWN_TERMINAL, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("unknown op code to passthrough VFD (without fail on unknown flag)") + + op_code = H5FD_CTL_OPC_RESERVED; + flags = 0; + + /* + * H5FDctl call should silently ignore unknown op code in + * passthrough VFD since no routing flag is specified and + * 'fail if unknown' flag is not specified. + */ + if (run_ctl_test(op_code, flags, CTL_OPC_UNKNOWN, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("unknown op code to passthrough VFD (with fail on unknown flag)") + + op_code = H5FD_CTL_OPC_RESERVED; + flags = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG; + + /* + * H5FDctl call should fail since op code is unknown to + * passthrough VFD, no routing flag is specified and the + * 'fail if unknown' flag is specified. + */ + if (run_ctl_test(op_code, flags, CTL_OPC_UNKNOWN, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("unknown op code to passthrough VFD (without fail on unknown flag/route to terminal VFD)") + + op_code = H5FD_CTL_OPC_RESERVED; + flags = H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG; + + /* + * H5Dctl call should succeed since the passthrough VFD + * doesn't recognize the op code, but has been instructed + * to route it down to the terminal VFD and the 'fail if + * unknown' flag has not been specified. Therefore, the + * terminal VFD should silently ignore the unknown op + * code. + */ + if (run_ctl_test(op_code, flags, CTL_OPC_UNKNOWN, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("unknown op code to passthrough VFD (with fail on unknown flag/route to terminal VFD)") + + op_code = H5FD_CTL_OPC_RESERVED; + flags = H5FD_CTL__FAIL_IF_UNKNOWN_FLAG | H5FD_CTL__ROUTE_TO_TERMINAL_VFD_FLAG; + + /* + * H5Dctl call should fail since the passthrough VFD + * doesn't recognize the op code, but has been instructed + * to route it down to the terminal VFD and the 'fail if + * unknown' flag has been specified. Therefore, the + * terminal VFD will throw an error for the unknown op + * code. + */ + if (run_ctl_test(op_code, flags, CTL_OPC_UNKNOWN, fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + TESTING_2("test cleanup") + + HDfree(splitter_config); + + if (H5FDunregister(driver_id) < 0) + TEST_ERROR; + if (H5Pclose(sub_fapl_id) < 0) + TEST_ERROR; + if (H5Pclose(fapl_id) < 0) + TEST_ERROR; + + PASSED(); + + return 0; + +error: + H5E_BEGIN_TRY + { + if (splitter_config) + HDfree(splitter_config); + H5FDunregister(driver_id); + H5Pclose(sub_fapl_id); + H5Pclose(fapl_id); + } + H5E_END_TRY; + + return -1; +} + /*------------------------------------------------------------------------- * Function: main * @@ -3429,6 +3944,7 @@ main(void) nerrors += test_windows() < 0 ? 1 : 0; nerrors += test_ros3() < 0 ? 1 : 0; nerrors += test_splitter() < 0 ? 1 : 0; + nerrors += test_ctl() < 0 ? 1 : 0; if (nerrors) { HDprintf("***** %d Virtual File Driver TEST%s FAILED! *****\n", nerrors, nerrors > 1 ? "S" : ""); diff --git a/testpar/t_filters_parallel.c b/testpar/t_filters_parallel.c index 694992a..78af0fb 100644 --- a/testpar/t_filters_parallel.c +++ b/testpar/t_filters_parallel.c @@ -62,6 +62,7 @@ static void test_write_filtered_dataset_single_no_selection(void); static void test_write_filtered_dataset_all_no_selection(void); static void test_write_filtered_dataset_point_selection(void); static void test_write_filtered_dataset_interleaved_write(void); +static void test_write_transformed_filtered_dataset_no_overlap(void); static void test_write_3d_filtered_dataset_no_overlap_separate_pages(void); static void test_write_3d_filtered_dataset_no_overlap_same_pages(void); static void test_write_3d_filtered_dataset_overlap(void); @@ -79,6 +80,7 @@ static void test_read_filtered_dataset_single_no_selection(void); static void test_read_filtered_dataset_all_no_selection(void); static void test_read_filtered_dataset_point_selection(void); static void test_read_filtered_dataset_interleaved_read(void); +static void test_read_transformed_filtered_dataset_no_overlap(void); static void test_read_3d_filtered_dataset_no_overlap_separate_pages(void); static void test_read_3d_filtered_dataset_no_overlap_same_pages(void); static void test_read_3d_filtered_dataset_overlap(void); @@ -120,6 +122,7 @@ static void (*tests[])(void) = { test_write_filtered_dataset_all_no_selection, test_write_filtered_dataset_point_selection, test_write_filtered_dataset_interleaved_write, + test_write_transformed_filtered_dataset_no_overlap, test_write_3d_filtered_dataset_no_overlap_separate_pages, test_write_3d_filtered_dataset_no_overlap_same_pages, test_write_3d_filtered_dataset_overlap, @@ -135,6 +138,7 @@ static void (*tests[])(void) = { test_read_filtered_dataset_all_no_selection, test_read_filtered_dataset_point_selection, test_read_filtered_dataset_interleaved_read, + test_read_transformed_filtered_dataset_no_overlap, test_read_3d_filtered_dataset_no_overlap_separate_pages, test_read_3d_filtered_dataset_no_overlap_same_pages, test_read_3d_filtered_dataset_overlap, @@ -428,7 +432,7 @@ test_write_filtered_dataset_no_overlap(void) /* Select hyperslab in the file */ filespace = H5Dget_space(dset_id); - VRFY((dset_id >= 0), "File dataspace retrieval succeeded"); + VRFY((filespace >= 0), "File dataspace retrieval succeeded"); VRFY((H5Sselect_hyperslab(filespace, H5S_SELECT_SET, start, stride, count, block) >= 0), "Hyperslab selection succeeded"); @@ -1288,6 +1292,177 @@ test_write_filtered_dataset_interleaved_write(void) } /* + * Tests parallel write of transformed and filtered data + * in the case where only one process is writing to a + * particular chunk in the operation. Normally, a data + * transform function will cause the parallel library to + * break to independent I/O and this isn't allowed when + * there are filters in the pipeline. However, in this + * case the parallel library recognizes that the used + * data transform function "x" is the same as not applying + * the transform function. Therefore it does not apply + * the transform function resulting in not breaking to + * independent I/O. + * + * Programmer: Jan-Willem Blokland + * 08/20/2021 + */ +static void +test_write_transformed_filtered_dataset_no_overlap(void) +{ + C_DATATYPE *data = NULL; + C_DATATYPE *read_buf = NULL; + C_DATATYPE *correct_buf = NULL; + hsize_t dataset_dims[WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t chunk_dims[WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t sel_dims[WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t start[WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t stride[WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t count[WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t block[WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + size_t i, data_size, correct_buf_size; + hid_t file_id = -1, dset_id = -1, plist_id = -1; + hid_t filespace = -1, memspace = -1; + + if (MAINPROCESS) + HDputs("Testing write to unshared transformed and filtered chunks"); + + CHECK_CUR_FILTER_AVAIL(); + + /* Set up file access property list with parallel I/O access */ + plist_id = H5Pcreate(H5P_FILE_ACCESS); + VRFY((plist_id >= 0), "FAPL creation succeeded"); + + VRFY((H5Pset_fapl_mpio(plist_id, comm, info) >= 0), "Set FAPL MPIO succeeded"); + + VRFY((H5Pset_libver_bounds(plist_id, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) >= 0), + "Set libver bounds succeeded"); + + file_id = H5Fopen(filenames[0], H5F_ACC_RDWR, plist_id); + VRFY((file_id >= 0), "Test file open succeeded"); + + VRFY((H5Pclose(plist_id) >= 0), "FAPL close succeeded"); + + /* Create the dataspace for the dataset */ + dataset_dims[0] = (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NROWS; + dataset_dims[1] = (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NCOLS; + chunk_dims[0] = (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NROWS; + chunk_dims[1] = (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NCOLS; + sel_dims[0] = (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NROWS; + sel_dims[1] = (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NCOLS; + + filespace = H5Screate_simple(WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS, dataset_dims, NULL); + VRFY((filespace >= 0), "File dataspace creation succeeded"); + + memspace = H5Screate_simple(WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS, sel_dims, NULL); + VRFY((memspace >= 0), "Memory dataspace creation succeeded"); + + /* Create chunked dataset */ + plist_id = H5Pcreate(H5P_DATASET_CREATE); + VRFY((plist_id >= 0), "DCPL creation succeeded"); + + VRFY((H5Pset_chunk(plist_id, WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS, chunk_dims) >= 0), + "Chunk size set"); + + /* Add test filter to the pipeline */ + VRFY((set_dcpl_filter(plist_id) >= 0), "Filter set"); + + dset_id = H5Dcreate2(file_id, WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_NAME, HDF5_DATATYPE_NAME, + filespace, H5P_DEFAULT, plist_id, H5P_DEFAULT); + VRFY((dset_id >= 0), "Dataset creation succeeded"); + + VRFY((H5Pclose(plist_id) >= 0), "DCPL close succeeded"); + VRFY((H5Sclose(filespace) >= 0), "File dataspace close succeeded"); + + /* Each process defines the dataset selection in memory and writes + * it to the hyperslab in the file + */ + count[0] = 1; + count[1] = (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NCOLS / + (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NCOLS; + stride[0] = (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NROWS; + stride[1] = (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NCOLS; + block[0] = (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NROWS; + block[1] = (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NCOLS; + start[0] = ((hsize_t)mpi_rank * (hsize_t)WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NROWS * count[0]); + start[1] = 0; + + if (VERBOSE_MED) { + HDprintf("Process %d is writing with count[ %" PRIuHSIZE ", %" PRIuHSIZE " ], stride[ %" PRIuHSIZE + ", %" PRIuHSIZE " ], start[ %" PRIuHSIZE ", %" PRIuHSIZE " ], block size[ %" PRIuHSIZE + ", %" PRIuHSIZE " ]\n", + mpi_rank, count[0], count[1], stride[0], stride[1], start[0], start[1], block[0], block[1]); + HDfflush(stdout); + } + + /* Select hyperslab in the file */ + filespace = H5Dget_space(dset_id); + VRFY((filespace >= 0), "File dataspace retrieval succeeded"); + + VRFY((H5Sselect_hyperslab(filespace, H5S_SELECT_SET, start, stride, count, block) >= 0), + "Hyperslab selection succeeded"); + + /* Fill data buffer */ + data_size = sel_dims[0] * sel_dims[1] * sizeof(*data); + correct_buf_size = dataset_dims[0] * dataset_dims[1] * sizeof(*correct_buf); + + data = (C_DATATYPE *)HDcalloc(1, data_size); + VRFY((NULL != data), "HDcalloc succeeded"); + + correct_buf = (C_DATATYPE *)HDcalloc(1, correct_buf_size); + VRFY((NULL != correct_buf), "HDcalloc succeeded"); + + for (i = 0; i < data_size / sizeof(*data); i++) + data[i] = (C_DATATYPE)GEN_DATA(i); + + for (i = 0; i < correct_buf_size / sizeof(*correct_buf); i++) + correct_buf[i] = (C_DATATYPE)((i % (dataset_dims[0] / (hsize_t)mpi_size * dataset_dims[1])) + + (i / (dataset_dims[0] / (hsize_t)mpi_size * dataset_dims[1]))); + + /* Create property list for collective dataset write and data transform */ + plist_id = H5Pcreate(H5P_DATASET_XFER); + VRFY((plist_id >= 0), "DXPL creation succeeded"); + + VRFY((H5Pset_dxpl_mpio(plist_id, H5FD_MPIO_COLLECTIVE) >= 0), "Set DXPL MPIO succeeded"); + + /* Set data transform expression */ + VRFY((H5Pset_data_transform(plist_id, "x") >= 0), "Set data transform expression succeeded"); + + VRFY((H5Dwrite(dset_id, HDF5_DATATYPE_NAME, memspace, filespace, plist_id, data) >= 0), + "Dataset write succeeded"); + + if (data) + HDfree(data); + + VRFY((H5Dclose(dset_id) >= 0), "Dataset close succeeded"); + + /* Verify the correct data was written */ + read_buf = (C_DATATYPE *)HDcalloc(1, correct_buf_size); + VRFY((NULL != read_buf), "HDcalloc succeeded"); + + dset_id = H5Dopen2(file_id, "/" WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_NAME, H5P_DEFAULT); + VRFY((dset_id >= 0), "Dataset open succeeded"); + + VRFY((H5Dread(dset_id, HDF5_DATATYPE_NAME, H5S_ALL, H5S_ALL, plist_id, read_buf) >= 0), + "Dataset read succeeded"); + + VRFY((0 == HDmemcmp(read_buf, correct_buf, correct_buf_size)), "Data verification succeeded"); + + if (correct_buf) + HDfree(correct_buf); + if (read_buf) + HDfree(read_buf); + + VRFY((H5Dclose(dset_id) >= 0), "Dataset close succeeded"); + VRFY((H5Sclose(filespace) >= 0), "File dataspace close succeeded"); + VRFY((H5Sclose(memspace) >= 0), "Memory dataspace close succeeded"); + VRFY((H5Pclose(plist_id) >= 0), "DXPL close succeeded"); + VRFY((H5Fclose(file_id) >= 0), "File close succeeded"); + + return; +} + +/* * Tests parallel write of filtered data in the case where * the dataset has 3 dimensions and each process writes * to its own "page" in the 3rd dimension. @@ -4224,6 +4399,232 @@ test_read_3d_filtered_dataset_no_overlap_separate_pages(void) } /* + * Tests parallel read of transformed and filtered data in the + * case where only one process is reading from a particular + * chunk in the operation. Normally, a data transform function + * will cause the parallel library to break to independent I/O + * and this isn't allowed when there are filters in the pipeline. + * However, in this case the parallel library recognizes that + * the used data transform function "x" is the same as not + * applying the transform function. Therefore it does not apply + * the transform function resulting in not breaking to + * independent I/O. + * + * The MAINPROCESS rank will first write out all of the + * data to the dataset. Then, each rank reads a part of + * the dataset and contributes its piece to a global buffer + * that is checked for consistency. + * + * Programmer: Jan-Willem Blokland + * 08/20/2021 + */ +static void +test_read_transformed_filtered_dataset_no_overlap(void) +{ + C_DATATYPE *read_buf = NULL; + C_DATATYPE *correct_buf = NULL; + C_DATATYPE *global_buf = NULL; + hsize_t dataset_dims[READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t chunk_dims[READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t sel_dims[READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t start[READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t stride[READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t count[READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t block[READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS]; + hsize_t flat_dims[1]; + size_t i, read_buf_size, correct_buf_size; + hid_t file_id = -1, dset_id = -1, plist_id = -1; + hid_t filespace = -1, memspace = -1; + int * recvcounts = NULL; + int * displs = NULL; + + if (MAINPROCESS) + HDputs("Testing read from unshared transformed and filtered chunks"); + + CHECK_CUR_FILTER_AVAIL(); + + dataset_dims[0] = (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NROWS; + dataset_dims[1] = (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NCOLS; + + /* Setup the buffer for writing and for comparison */ + correct_buf_size = (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NROWS * + (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NCOLS * sizeof(*correct_buf); + + correct_buf = (C_DATATYPE *)HDcalloc(1, correct_buf_size); + VRFY((NULL != correct_buf), "HDcalloc succeeded"); + + for (i = 0; i < correct_buf_size / sizeof(*correct_buf); i++) + correct_buf[i] = (C_DATATYPE)((i % (dataset_dims[0] / (hsize_t)mpi_size * dataset_dims[1])) + + (i / (dataset_dims[0] / (hsize_t)mpi_size * dataset_dims[1]))); + + if (MAINPROCESS) { + plist_id = H5Pcreate(H5P_FILE_ACCESS); + VRFY((plist_id >= 0), "FAPL creation succeeded"); + + VRFY((H5Pset_libver_bounds(plist_id, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) >= 0), + "Set libver bounds succeeded"); + + file_id = H5Fopen(filenames[0], H5F_ACC_RDWR, plist_id); + VRFY((file_id >= 0), "Test file open succeeded"); + + VRFY((H5Pclose(plist_id) >= 0), "FAPL close succeeded"); + + /* Create the dataspace for the dataset */ + filespace = + H5Screate_simple(READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS, dataset_dims, NULL); + VRFY((filespace >= 0), "File dataspace creation succeeded"); + + /* Create chunked dataset */ + chunk_dims[0] = (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NROWS; + chunk_dims[1] = (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NCOLS; + + plist_id = H5Pcreate(H5P_DATASET_CREATE); + VRFY((plist_id >= 0), "DCPL creation succeeded"); + + VRFY( + (H5Pset_chunk(plist_id, READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS, chunk_dims) >= 0), + "Chunk size set"); + + /* Add test filter to the pipeline */ + VRFY((set_dcpl_filter(plist_id) >= 0), "Filter set"); + + dset_id = H5Dcreate2(file_id, READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_NAME, + HDF5_DATATYPE_NAME, filespace, H5P_DEFAULT, plist_id, H5P_DEFAULT); + VRFY((dset_id >= 0), "Dataset creation succeeded"); + + VRFY((H5Pclose(plist_id) >= 0), "DCPL close succeeded"); + VRFY((H5Sclose(filespace) >= 0), "File dataspace close succeeded"); + + /* Create property list for collective dataset read */ + plist_id = H5Pcreate(H5P_DATASET_XFER); + VRFY((plist_id >= 0), "DXPL creation succeeded"); + + /* Set data transform expression */ + VRFY((H5Pset_data_transform(plist_id, "x") >= 0), "Set data transform expression succeeded"); + + VRFY((H5Dwrite(dset_id, HDF5_DATATYPE_NAME, H5S_ALL, H5S_ALL, plist_id, correct_buf) >= 0), + "Dataset write succeeded"); + + VRFY((H5Pclose(plist_id) >= 0), "DXPL close succeeded"); + VRFY((H5Dclose(dset_id) >= 0), "Dataset close succeeded"); + VRFY((H5Fclose(file_id) >= 0), "File close succeeded"); + } + + /* Set up file access property list with parallel I/O access */ + plist_id = H5Pcreate(H5P_FILE_ACCESS); + VRFY((plist_id >= 0), "FAPL creation succeeded"); + + VRFY((H5Pset_fapl_mpio(plist_id, comm, info) >= 0), "Set FAPL MPIO succeeded"); + + VRFY((H5Pset_libver_bounds(plist_id, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST) >= 0), + "Set libver bounds succeeded"); + + file_id = H5Fopen(filenames[0], H5F_ACC_RDONLY, plist_id); + VRFY((file_id >= 0), "Test file open succeeded"); + + VRFY((H5Pclose(plist_id) >= 0), "FAPL close succeeded"); + + dset_id = H5Dopen2(file_id, "/" READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_NAME, H5P_DEFAULT); + VRFY((dset_id >= 0), "Dataset open succeeded"); + + sel_dims[0] = (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NROWS; + sel_dims[1] = (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NCOLS; + + /* Setup one-dimensional memory dataspace for reading the dataset data into a contiguous buffer */ + flat_dims[0] = sel_dims[0] * sel_dims[1]; + + memspace = H5Screate_simple(1, flat_dims, NULL); + VRFY((memspace >= 0), "Memory dataspace creation succeeded"); + + /* Select hyperslab in the file */ + filespace = H5Dget_space(dset_id); + VRFY((filespace >= 0), "File dataspace retrieval succeeded"); + + /* + * Each process defines the dataset selection in the file and reads + * it to the selection in memory + */ + count[0] = 1; + count[1] = (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NCOLS / + (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NCOLS; + stride[0] = (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NROWS; + stride[1] = (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NCOLS; + block[0] = (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NROWS; + block[1] = (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NCOLS; + start[0] = ((hsize_t)mpi_rank * (hsize_t)READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NROWS * count[0]); + start[1] = 0; + + if (VERBOSE_MED) { + HDprintf("Process %d is reading with count[ %" PRIuHSIZE ", %" PRIuHSIZE " ], stride[ %" PRIuHSIZE + ", %" PRIuHSIZE " ], start[ %" PRIuHSIZE ", %" PRIuHSIZE " ], block size[ %" PRIuHSIZE + ", %" PRIuHSIZE " ]\n", + mpi_rank, count[0], count[1], stride[0], stride[1], start[0], start[1], block[0], block[1]); + HDfflush(stdout); + } + + VRFY((H5Sselect_hyperslab(filespace, H5S_SELECT_SET, start, stride, count, block) >= 0), + "Hyperslab selection succeeded"); + + /* Create property list for collective dataset read and data transform */ + plist_id = H5Pcreate(H5P_DATASET_XFER); + VRFY((plist_id >= 0), "DXPL creation succeeded"); + + VRFY((H5Pset_dxpl_mpio(plist_id, H5FD_MPIO_COLLECTIVE) >= 0), "Set DXPL MPIO succeeded"); + + /* Set data transform expression */ + VRFY((H5Pset_data_transform(plist_id, "x") >= 0), "Set data transform expression succeeded"); + + read_buf_size = flat_dims[0] * sizeof(*read_buf); + + read_buf = (C_DATATYPE *)HDcalloc(1, read_buf_size); + VRFY((NULL != read_buf), "HDcalloc succeeded"); + + VRFY((H5Dread(dset_id, HDF5_DATATYPE_NAME, memspace, filespace, plist_id, read_buf) >= 0), + "Dataset read succeeded"); + + global_buf = (C_DATATYPE *)HDcalloc(1, correct_buf_size); + VRFY((NULL != global_buf), "HDcalloc succeeded"); + + /* Collect each piece of data from all ranks into a global buffer on all ranks */ + recvcounts = (int *)HDcalloc(1, (size_t)mpi_size * sizeof(*recvcounts)); + VRFY((NULL != recvcounts), "HDcalloc succeeded"); + + for (i = 0; i < (size_t)mpi_size; i++) + recvcounts[i] = (int)flat_dims[0]; + + displs = (int *)HDcalloc(1, (size_t)mpi_size * sizeof(*displs)); + VRFY((NULL != displs), "HDcalloc succeeded"); + + for (i = 0; i < (size_t)mpi_size; i++) + displs[i] = (int)(i * flat_dims[0]); + + VRFY((MPI_SUCCESS == MPI_Allgatherv(read_buf, (int)flat_dims[0], C_DATATYPE_MPI, global_buf, recvcounts, + displs, C_DATATYPE_MPI, comm)), + "MPI_Allgatherv succeeded"); + + VRFY((0 == HDmemcmp(global_buf, correct_buf, correct_buf_size)), "Data verification succeeded"); + + if (displs) + HDfree(displs); + if (recvcounts) + HDfree(recvcounts); + if (global_buf) + HDfree(global_buf); + if (read_buf) + HDfree(read_buf); + if (correct_buf) + HDfree(correct_buf); + + VRFY((H5Dclose(dset_id) >= 0), "Dataset close succeeded"); + VRFY((H5Sclose(filespace) >= 0), "File dataspace close succeeded"); + VRFY((H5Sclose(memspace) >= 0), "Memory dataspace close succeeded"); + VRFY((H5Pclose(plist_id) >= 0), "DXPL close succeeded"); + VRFY((H5Fclose(file_id) >= 0), "File close succeeded"); + + return; +} + +/* * Tests parallel read of filtered data in the case where * the dataset has 3 dimensions and each process reads from * each "page" in the 3rd dimension. However, no chunk on a diff --git a/testpar/t_filters_parallel.h b/testpar/t_filters_parallel.h index 3804c09..7eb34ed 100644 --- a/testpar/t_filters_parallel.h +++ b/testpar/t_filters_parallel.h @@ -138,6 +138,16 @@ typedef struct { #define INTERLEAVED_WRITE_FILTERED_DATASET_NCOLS \ (INTERLEAVED_WRITE_FILTERED_DATASET_CH_NCOLS * DIM1_SCALE_FACTOR) +/* Defines for the unshared transformed and filtered chunks write test */ +#define WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_NAME "unshared_transformed_filtered_chunks_write" +#define WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS 2 +#define WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NROWS (mpi_size * DIM0_SCALE_FACTOR) +#define WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NCOLS (mpi_size * DIM1_SCALE_FACTOR) +#define WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NROWS \ + (WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NROWS / mpi_size) +#define WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NCOLS \ + (WRITE_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NCOLS / mpi_size) + /* Defines for the 3D unshared filtered dataset separate page write test */ #define WRITE_UNSHARED_FILTERED_CHUNKS_3D_SEP_PAGE_DATASET_NAME \ "3D_unshared_filtered_chunks_separate_pages_write" @@ -280,6 +290,16 @@ typedef struct { #define INTERLEAVED_READ_FILTERED_DATASET_NCOLS \ (INTERLEAVED_READ_FILTERED_DATASET_CH_NCOLS * DIM1_SCALE_FACTOR) +/* Defines for the unshared transformed and filtered chunks read test */ +#define READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_NAME "unshared_transformed_filtered_chunks_read" +#define READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_DATASET_DIMS 2 +#define READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NROWS (mpi_size * DIM0_SCALE_FACTOR) +#define READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NCOLS (mpi_size * DIM1_SCALE_FACTOR) +#define READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NROWS \ + (READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NROWS / mpi_size) +#define READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_CH_NCOLS \ + (READ_UNSHARED_TRANSFORMED_FILTERED_CHUNKS_NCOLS / mpi_size) + /* Defines for the 3D unshared filtered dataset separate page read test */ #define READ_UNSHARED_FILTERED_CHUNKS_3D_SEP_PAGE_DATASET_NAME \ "3D_unshared_filtered_chunks_separate_pages_read" diff --git a/tools/lib/h5tools_str.c b/tools/lib/h5tools_str.c index 5fcaee6..abc0058 100644 --- a/tools/lib/h5tools_str.c +++ b/tools/lib/h5tools_str.c @@ -258,7 +258,8 @@ h5tools_str_fmt(h5tools_str_t *str /*in,out*/, size_t start, const char *fmt) HDassert(temp); } - HDstrncpy(temp, str->s + start, n); + HDstrncpy(temp, str->s + start, n - 1); + temp[n - 1] = '\0'; } /* Reset the output string and append a formatted version */ diff --git a/tools/libtest/Makefile.am b/tools/libtest/Makefile.am index a93e25d..1a08a01 100644 --- a/tools/libtest/Makefile.am +++ b/tools/libtest/Makefile.am @@ -1,16 +1,16 @@ # -# Read-Only S3 Virtual File Driver (VFD) -# Copyright (c) 2017-2018, The HDF Group. -# +# Copyright by The HDF Group. # All rights reserved. # # NOTICE: -# All information contained herein is, and remains, the property of The HDF -# Group. The intellectual and technical concepts contained herein are -# proprietary to The HDF Group. Dissemination of this information or -# reproduction of this material is strictly forbidden unless prior written -# permission is obtained from The HDF Group. -## +# +# This file is part of HDF5. The full HDF5 copyright notice, including +# terms governing use, modification, and redistribution, is contained in +# the COPYING file, which can be found at the root of the source code +# distribution tree, or in https://www.hdfgroup.org/licenses. +# If you do not have access to either file, you may request a copy from +# help@hdfgroup.org. +# ## Makefile.am ## Run automake to generate a Makefile.in from this file. # diff --git a/tools/libtest/h5tools_test_utils.c b/tools/libtest/h5tools_test_utils.c index 54f6f51..37d38fd 100644 --- a/tools/libtest/h5tools_test_utils.c +++ b/tools/libtest/h5tools_test_utils.c @@ -69,7 +69,7 @@ * *****************************************************************************/ -H5_GCC_DIAG_OFF("format") +H5_GCC_CLANG_DIAG_OFF("format") /*---------------------------------------------------------------------------- * @@ -1254,7 +1254,7 @@ error: #undef UTIL_TEST_DEFAULT #undef UTIL_TEST_CREATE } /* test_set_configured_fapl */ -H5_GCC_DIAG_ON("format") +H5_GCC_CLANG_DIAG_ON("format") /*---------------------------------------------------------------------------- * diff --git a/tools/src/h5dump/h5dump_ddl.c b/tools/src/h5dump/h5dump_ddl.c index 2a69ca6..638a738 100644 --- a/tools/src/h5dump/h5dump_ddl.c +++ b/tools/src/h5dump/h5dump_ddl.c @@ -1343,13 +1343,21 @@ attr_search(hid_t oid, const char *attr_name, const H5A_info_t H5_ATTR_UNUSED *a ret = FAIL; } else { + size_t buffer_space = w - 1; + HDmemset(obj_name, '\0', w); if (op_name[0] != '/') { - HDstrncat(obj_name, buf, u + 1); - if (buf[u - 1] != '/') - HDstrncat(obj_name, "/", (size_t)2); + HDstrncat(obj_name, buf, buffer_space); + buffer_space -= MIN(buffer_space, u); + + if (buf[u - 1] != '/') { + HDstrncat(obj_name, "/", buffer_space); + buffer_space -= MIN(buffer_space, 2); + } } - HDstrncat(obj_name, op_name, v + 1); + + HDstrncat(obj_name, op_name, buffer_space); + buffer_space -= MIN(buffer_space, v); handle_attributes(oid, obj_name, NULL, 0, NULL); HDfree(obj_name); @@ -1421,10 +1429,10 @@ lnk_search(const char *path, const H5L_info2_t *li, void *_op_data) else { if (k == 2) { HDstrcpy(search_name, "/"); - HDstrncat(search_name, op_name, search_len + 1); + HDstrcat(search_name, op_name); } else - HDstrncpy(search_name, op_name, search_len + 1); + HDstrcpy(search_name, op_name); search_name[search_len + k - 1] = '\0'; if (HDstrcmp(path, search_name) == 0) { diff --git a/tools/src/h5import/h5import.c b/tools/src/h5import/h5import.c index 04e1c35..6517e43 100644 --- a/tools/src/h5import/h5import.c +++ b/tools/src/h5import/h5import.c @@ -3771,6 +3771,7 @@ getCompressionParameter(struct Input *in, FILE *strm) static int getExternalFilename(struct Input *in, FILE *strm) { + size_t temp_len; char temp[255]; const char *err1 = "Unable to get 'string' value.\n"; @@ -3779,8 +3780,10 @@ getExternalFilename(struct Input *in, FILE *strm) return (-1); } - in->externFilename = (char *)HDmalloc((size_t)(HDstrlen(temp) + 1) * sizeof(char)); - (void)HDstrncpy(in->externFilename, temp, HDstrlen(temp) + 1); + temp_len = HDstrlen(temp); + in->externFilename = (char *)HDmalloc((temp_len + 1) * sizeof(char)); + (void)HDstrcpy(in->externFilename, temp); + in->externFilename[temp_len] = '\0'; return (0); } |