diff options
67 files changed, 3758 insertions, 963 deletions
@@ -216,10 +216,11 @@ ./doxygen/dox/Cookbook.dox ./doxygen/dox/DDLBNF110.dox ./doxygen/dox/FileFormatSpec.dox +./doxygen/dox/FTS.dox ./doxygen/dox/GettingStarted.dox +./doxygen/dox/Glossary.dox ./doxygen/dox/H5AC_cache_config_t.dox ./doxygen/dox/MetadataCachingInHDF5.dox -./doxygen/dox/OtherSpecs.dox ./doxygen/dox/Overview.dox ./doxygen/dox/ReferenceManual.dox ./doxygen/dox/RFC.dox @@ -235,9 +236,12 @@ ./doxygen/dox/cookbook/Files.c ./doxygen/dox/cookbook/Files.dox ./doxygen/dox/cookbook/Performance.dox +./doxygen/examples/DebuggingHDF5Applications.html ./doxygen/examples/FF-IH_FileGroup.gif ./doxygen/examples/FF-IH_FileObject.gif +./doxygen/examples/FileFormat.html ./doxygen/examples/FileFormatSpecChunkDiagram.jpg +./doxygen/examples/Filters.html ./doxygen/examples/H5Pset_metadata_read_attempts.c ./doxygen/examples/H5Pset_object_flush_cb.c ./doxygen/examples/H5.format.1.0.html @@ -266,6 +270,7 @@ ./doxygen/examples/H5Z_examples.c ./doxygen/examples/H5_examples.c ./doxygen/examples/ImageSpec.html +./doxygen/examples/IOFlow.html ./doxygen/examples/PaletteExample1.gif ./doxygen/examples/Palettes.fm.anc.gif ./doxygen/examples/TableSpec.html @@ -280,6 +285,7 @@ ./doxygen/img/FF-IH_FileGroup.gif ./doxygen/img/FF-IH_FileObject.gif ./doxygen/img/FileFormatSpecChunkDiagram.jpg +./doxygen/img/HDF5.png ./doxygen/img/HDFG-logo.png ./doxygen/img/IOFlow.gif ./doxygen/img/IOFlow2.gif diff --git a/doxygen/CMakeLists.txt b/doxygen/CMakeLists.txt index ca36ef1..920fafa 100644 --- a/doxygen/CMakeLists.txt +++ b/doxygen/CMakeLists.txt @@ -27,6 +27,7 @@ if (DOXYGEN_FOUND) set (DOXYGEN_EXTERNAL_SEARCH NO) set (DOXYGEN_SEARCHENGINE_URL) set (DOXYGEN_STRIP_FROM_PATH ${HDF5_SOURCE_DIR}) + set (DOXYGEN_STRIP_FROM_INC_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 diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index d37222e..7958767 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -179,7 +179,7 @@ STRIP_FROM_PATH = @DOXYGEN_STRIP_FROM_PATH@ # specify the list of include paths that are normally passed to the compiler # using the -I flag. -STRIP_FROM_INC_PATH = +STRIP_FROM_INC_PATH = @DOXYGEN_STRIP_FROM_INC_PATH@ # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but # less readable) file names. This can be useful is your file systems doesn't diff --git a/doxygen/aliases b/doxygen/aliases index d5acbee..71a5488 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -297,7 +297,7 @@ ALIASES += ref_rfc20071111="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/AURA-co 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_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>" diff --git a/doxygen/dox/About.dox b/doxygen/dox/About.dox index 32930a8..a8b31d7 100644 --- a/doxygen/dox/About.dox +++ b/doxygen/dox/About.dox @@ -12,12 +12,116 @@ 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 +In this section, we describe common documentation maintenance tasks. + +\subsection plain_html Including Plain HTML Pages + +The most common use case for this is the inclusion of older documentation. +New documentation should, whenever possible, be created using Doxygen markdown! + +Use Doxygen's <a href="https://www.doxygen.nl/manual/commands.html#cmdhtmlinclude"><code>htmlinclude</code></a> +special command to include existing plain HTML pages. + +An example from this documentation set can be seen +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/dox/FileFormatSpec.dox">here</a>. + +\subsection new_rm_entry Creating a New Reference Manual Entry + +Please refer to the \ref RMT for guidance on how to create a new reference manual entry. + +\subsubsection new_example Adding and Referencing API Examples + +For each HDF5 module, such as \Code{H5F}, there is an examples source file called +\Code{H5*_examples.c}. For example, the \Code{H5F} API examples are located in +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/examples/H5F_examples.c"> +<code>H5F_examples.c</code></a>. Examples are code blocks marked as Doxygen +<a href="https://www.doxygen.nl/manual/commands.html#cmdsnippet">snippets</a>. +For example, the source code for the H5Fcreate() API sample is located between +the +\verbatim +//! <!-- [create] --> +... +//! <!-- [create] --> +\endverbatim +comments in +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/examples/H5F_examples.c"> +<code>H5F_examples.c</code></a>. + +Add a new API example by adding a new code block enclosed between matching +snippet tags. The name of the tag is usually the function name stripped of +the module prefix. + +The inclusion of such a block of code can then be triggered via Doxygen's +<a href="https://www.doxygen.nl/manual/commands.html#cmdsnippet"><code>snippet</code></a> +special command. For example, the following markup +\verbatim +* \snippet H5F_examples.c create +\endverbatim +yields +\snippet H5F_examples.c create + +\subsubsection api_macro Adding an API Macro + +API macros are handled by the <code>api_vers_2, api_vers_3, api_vers_4</code> +custom commands. The numbers indicate the number of potential API function +mappings. For example, H5Acreate() has two potential mappings, H5Acreate1() and +H5Acreate2(). To trigger the creation of a reference manual entry for H5Acreate() +use the following markup: +\verbatim +\api_vers_2{H5Acreate,H5Acreate1,H5Acreate2} +\endverbatim +This yields: + +\api_vers_2{H5Acreate,H5Acreate1,H5Acreate2} + +\subsection custom_commands Creating Custom Commands + +See Doxygen's <a href="https://www.doxygen.nl/manual/custcmd.html">Custom Commands documentation</a> +as a general reference. + +All custom commands for this project are located in the +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/aliases"><tt>aliases</tt></a> +file in the <a href="https://github.com/HDFGroup/hdf5/tree/develop/doxygen"><tt>doxygen</tt></a> +subdirectory of the <a href="https://github.com/HDFGroup/hdf5">main HDF5 repo</a>. + +The custom commands are grouped in sections. Find a suitable section for your command or +ask for help if unsure! + +\subsection new_rfc Adding a New RFC or Referencing an Existing RFC + +For ease of reference, we define custom commands for each RFC in the <tt>RFCs</tt> section +of the +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/aliases"><tt>aliases</tt></a> +file. For example the custom command \Code{ref_rfc20141210} can be used to insert a +reference to "RFC: Virtual Object Layer". In other words, the markup +\verbatim +\ref_rfc20141210 +\endverbatim +yields a clickable link: + +\ref_rfc20141210 + +To add a new RFC, add a custom command for the RFC to the +<a href="https://github.com/HDFGroup/hdf5/blob/develop/doxygen/aliases"><tt>aliases</tt></a> +file. The naming convention for the custom command is \Code{ref_rfcYYYYMMDD}, +where \Code{YYYYMMDD} is the ID of the RFC. The URL is composed of the prefix +\verbatim +https://docs.hdfgroup.org/hdf5/rfc/ +\endverbatim +and the name of your RFC file, typically, a PDF file, i.e., the full URL would +be +\verbatim +https://docs.hdfgroup.org/hdf5/rfc/my_great_rfc_name.pdf +\endverbatim + +\subsection hosting How Do Updates and Changes Get Published? + +Currently, the files underlying this documentation website are stored in an +bucket on AWS S3. The top-level bucket is <pre>s3://docs.hdfgroup.org/hdf5/</pre> +There are folders for the <tt>development</tt> branch and all supported release +version. + +Talk to your friendly IT-team if you need write access, or you need someone to +push an updated version for you! */
\ No newline at end of file diff --git a/doxygen/dox/FTS.dox b/doxygen/dox/FTS.dox new file mode 100644 index 0000000..9dae7c1 --- /dev/null +++ b/doxygen/dox/FTS.dox @@ -0,0 +1,8 @@ +/** \page FTS Full-Text Search + +\htmlonly +<script async src="https://cse.google.com/cse.js?cx=75c754173f9b90804"></script> +<div class="gcse-search"></div> +\endhtmlonly + +*/
\ No newline at end of file diff --git a/doxygen/dox/Glossary.dox b/doxygen/dox/Glossary.dox new file mode 100644 index 0000000..9ccd27d --- /dev/null +++ b/doxygen/dox/Glossary.dox @@ -0,0 +1,565 @@ +/** \page GLS Glossary + +\section GLS_A A + +<DL> + <DT>Array datatype</DT> + <DD>A family of HDF5 datatypes whose elements are arrays of a fixed rank (≤ + 32) and fixed finite extent. All array elements must be of the same HDF5 + datatype.</DD> +</DL> + +<DL> + <DT>Array variable</DT> + <DD><P>A variable that can store (logically) dense, rectilinear, multidimensional + arrays of elements of a given HDF5 datatype.</P> + <P>The combination of array rank (dimensionality) and extent is called an + array variable's shape. This includes the degenerate array shapes of a + singleton (scalar) and the empty array (null).</P> + <P>The array element datatype is sometimes referred to as the array + variable's type, which is not entirely accurate because the array variable's + type is 'array of element type' rather than 'element type'.</P> + <P>In HDF5, there are two kinds of array variables, attributes and datasets, + and the distinction is functional (i.e., how they can be used) rather than + conceptual. Attributes are commonly used for descriptive "light-weight" + HDF5 object metadata while datasets are HDF5 objects used to store + "heavy-weight" problem-sized data.</P> + </DD> +</DL> + +<DL> + <DT>Attribute</DT> + <DD><P>A named array variable that is associated with an HDF5 object, its + owner or attributee, and used to represent application domain-specific + metadata of the object. Intuitively, the set of an object's attributes can + be thought of as its key-value pair collection. Attribute names (keys) can + be arbitrary Unicode strings, but must be unique per object, i.e., an + object can have at most one attribute with a given name.</P> + <P>A scalar attribute is an attribute backed by a singleton array + variable. A null attribute is attribute backed by an empty array + variable.</P> +</DD> +</DL> + +\section GLS_B B + +<DL> + <DT>Bitfield datatype</DT> + <DD>A family of HDF5 datatypes whose elements are fixed-width bit fields.</DD> +</DL> + +\section GLS_C C + +<DL> + <DT>Chunked layout</DT> + <DD> + <P>A dataset storage layout where the dataset elements are partitioned into + fixed-size multidimensional chunks or tiles. Chunked layout is mandatory + for datasets with one or more dimensions of indefinite (infinite) extent + or where compression or other filters are applied to the dataset elements.</P> + <P>Chunked layout may improve I/O performance for certain access patterns.</P> +</DD> +</DL> + +<DL> + <DT>Committed datatype</DT> + <DD>An immutable kind of HDF5 object that is used to store an HDF5 datatype + definition, which can be referenced by multiple array variables. When linked + to an HDF5 group, a committed datatype can be located by an HDF5 path name, + and is sometimes called a named datatype.</DD> +</DL> + +<DL> + <DT>Compact layout</DT> + <DD></DD> +</DL> + +<DL> + <DT>Compound datatype</DT> + <DD> + <P>A family of HDF5 datatypes whose elements are records with named fields + of other HDF5 datatypes. Currently, on ASCII field names are supported.</P> + <P>Similar to a <CODE>struct</CODE> in C or a <CODE>COMMON</CODE> block in + Fortran.</P> +</DD> +</DL> + +<DL> + <DT>Contiguous layout</DT> + <DD>A dataset storage layout where the dataset elements are physically stored + in an HDF5 file as a contiguous block of bytes.</DD> +</DL> + +\section GLS_D D + +<DL> + <DT>Dataset</DT> + <DD> + <P>A kind of HDF5 object, a linked array variable. which can be located in + an HDF5 file through a path name. Datasets are commonly used to store + "heavy-weight" problem-sized data.</P> + <P>The HDF5 library offers a lot of features aimed at optimized dataset + access and storage, including compression and partial I/O.</P> +</DD> +</DL> + +<DL> + <DT>Dataspace</DT> + <DD>The shape of an array variable. With the exception of degenerate cases + (empty set, singleton), this is a rectilinear lattice or grid of a certain + rank (dimensionality) and extent.</DD> +</DL> + +<DL> + <DT>Datatype</DT> + <DD> + <P>An HDF5 datatype consists of an abstract data type (a set of elements) + and a bit-level representation of these elements in storage such as an HDF5 + file or memory.</P> + <P>The HDF5 library comes with a large set of predefined datatypes and + offers mechanisms for creating user-defined datatypes.</P> + <P>The ten major families or classes of HDF5 datatypes are:</P> + <UL> + <LI>Integer datatypes</LI> + <LI>Floating-point number datatypes</LI> + <LI>String datatypes</LI> + <LI>Bitfield datatypes</LI> + <LI>Opaque datatypes</LI> + <LI>Compound datatypes</LI> + <LI>Reference datatypes</LI> + <LI>Enumerated datatypes</LI> + <LI>Variable-length sequence datatypes</LI> + <LI>Array datatypes</LI> + </UL> +</DD> +</DL> + +\section GLS_E E + +<DL> + <DT>Enumeration datatype</DT> + <DD>A family of HDF5 datatypes whose elements represent named integer values + called members or enumerators. Currently, only ASCII names are supported.</DD> +</DL> + +<DL> + <DT>External layout</DT> + <DD>A form of contiguous layout where a dataset's elements are physically + stored in unformatted binary files outside the HDF5 file.</DD> +</DL> + +<DL> + <DT>External link</DT> + <DD>An HDF5 link whose destination is specified as a pair of an HDF5 file name +and an HDF5 path name in that file.</DD> +</DL> + +\section GLS_F F + +<DL> + <DT>Field</DT> + <DD>See compound datatype.</DD> +</DL> + +<DL> + <DT>File</DT> + <DD> + <OL> + <LI>A byte stream (in a storage context such as a file system or in + memory) formatted according to the HDF5 File Format Specification.</LI> + <LI>A (logical) container for HDF5 objects.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>File format</DT> + <DD></DD> +</DL> + +<DL> + <DT>Fill value</DT> + <DD></DD> +</DL> + +<DL> + <DT>Filter</DT> + <DD></DD> +</DL> + +\section GLS_G G + +<DL> + <DT>Group</DT> + <DD> + <P>A kind of HDF5 object that stores a collection of HDF5 links. Each HDF5 + file contains at least one group, it's root group.</P> + <P>Among the destinations of an HDF5 group's links may be other HDF5 groups + (including the group itself!). This ability is sometimes referred to as the + closure property of groups. It is the basis for creating hierarchical or + more general graph-like structures.</P> +</DD> +</DL> + +\section GLS_H H + +<DL> + <DT>Hard link</DT> + <DD>An HDF5 link whose destination is specified (internally) as the address of + an HDF5 object in the same HDF5 file.</DD> +</DL> + +<DL> + <DT>Hierarchy</DT> + <DD>See group.</DD> +</DL> + +<DL> + <DT>Hyperslab</DT> + <DD> + <P>A regular multidimensional pattern described by four vectors whose length + equals the rank of the pattern.</P> + <OL> + <LI><CODE>start</CODE> - the offset where the first block of the hyperslab begins</LI> + <LI><CODE>stride</CODE> - the offset between pattern blocks</LI> + <LI><CODE>count</CODE> - the number of blocks</LI> + <LI><CODE>block</CODE> - the extent of an individual pattern block</LI> + </OL> + <P>For example, the black squares on a (two-dimensional) chessboard with + origin at <CODE>(0,0)</CODE> can be represented as the union of two + hyperslabs representing the even <CODE>(0,2,4,6)</CODE> and + odd <CODE>(1,3,5,7)</CODE> rows, respectively.</P> + <IMG SRC="https://upload.wikimedia.org/wikipedia/commons/thumb/d/d7/Chessboard480.svg/176px-Chessboard480.svg.png"/> + <P>The hyperslab parameters for the even rows are: <CODE>start (0,0)</CODE>, + <CODE>stride (2,2)</CODE>, <CODE>count (4,4)</CODE>, <CODE>block + (1,1)</CODE>. Likewise the parameters for the odd rows are: <CODE>start + (1,1)</CODE>, <CODE>stride (2,2)</CODE>, <CODE>count + (4,4)</CODE>, <CODE>block (1,1)</CODE>.</P> +</DD> +</DL> + +\section GLS_I I + +<DL> + <DT>Identifier</DT> + <DD>An opaque, transient handle used by the HDF5 library to manipulate + in-memory representations of HDF5 items.</DD> +</DL> + +\section GLS_L L + +<DL> + <DT>Library</DT> + <DD></DD> +</DL> + +<DL> + <DT>Link</DT> + <DD> + <P>A named, uni-directional association between a source and a + destination. In HDF5, the source is always the HDF5 group that hosts the + link in its link collection.</P> + <P>There are several ways to specify a link's destination:</P> + <UL> + <LI>The address of an HDF5 object in the same HDF5 file; so-called hard + link.</LI> + <LI>A path name in the same or a different file; so-called soft or + external link.</LI> + <LI>User-defined</LI> + </UL> + <P>A link name can be any Unicode string that does not contain slashes + (<CODE>"/"</CODE>) or consists of a single dot character + (<CODE>"."</CODE>). A link name must be unique in a group's link + collection.</P> + </DD> +</DL> + +\section GLS_M M + +<DL> + <DT>Metadata</DT> + <DD>Data that in a given context has a descriptive or documentation function + for other data. Typically, the metadata is small compared to the data it + describes.</DD> +</DL> + +<DL> + <DT>Member</DT> + <DD> + <P>A link destination is sometimes referred to as a member of the link's + source (group). This way of speaking invites confusion: A destination (e.g., + object) can be the destination of multiple links in the same (!) or + different groups. It would then be a "member" of a given group with + multiplicity greater than one and be a member of multiple groups.</P> + <P> It is the link that is a member of the group's link collection and not + the link destination.</P> + </DD> +</DL> + +\section GLS_N N + +<DL> + <DT>Name</DT> + <DD> + <P>A Unicode string that depending on the item it names might be subject to + certain character restrictions, such as ASCII-encoded only. In HDF5, the + user might encounter the following names:</P> + <UL> + <LI>A link name</LI> + <LI>A path name</LI> + <LI>An attribute name</LI> + <LI>A field name (compound datatypes)</LI> + <LI>A constant name (enumeration datatypes)</LI> + <LI>A tag name (opaque datatypes)</LI> + <LI>A file name</LI> + </UL> + </DD> +</DL> + + +<DL> + <DT>Named datatype</DT> + <DD>See committed datatype.</DD> +</DL> + +<DL> + <DT>Null dataspace</DT> + <DD>A shape which represents the empty set. Array variables with this shape + cannot store any values.</DD> +</DL> + +\section GLS_O O + +<DL> + <DT>Object</DT> + <DD>An HDF5 group, dataset or named datatype; an HDF5 item that can be linked + to zero or more groups and decorated with zero or more HDF5 attributes.</DD> +</DL> + +<DL> + <DT>Object reference</DT> + <DD> + <OL> + <LI>A datatype for representing references to objects in a file.</LI> + <LI>A value of the object reference datatype.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Opaque datatype</DT> + <DD>A family of HDF5 datatypes whose elements are byte sequences of a given + fixed length. An opaque datatype can be tagged with a sequence of up to 256 + ASCII characters, e.g., MIME code.</DD> +</DL> + +\section GLS_P P + +<DL> + <DT>Path name</DT> + <DD>A Unicode string that is the concatenation of link names separated by + slashes (<CODE>'/'</CODE>). In HDF5, path names are used to locate and refer + to HDF5 objects.</DD> +</DL> + +<DL> + <DT>Plugin</DT> + <DD>An HDF5 library feature or capability that can be added dynamically at + application run time rather than library compilation time. Plugins are + usually implemented as shared libraries, and their discovery and loading + behavior can be controlled programmatically or through environment + variables. + </DD> +</DL> + +<DL> + <DT>Point selection</DT> + <DD>A dataspace selection that consists of a set of points (coordinates) in + the same dataspace.</DD> +</DL> + +<DL> + <DT>Property list</DT> + <DD> + <P>An HDF5 API construct, a means of customizing the behavior of the HDF5 + library when creating, accessing or modifying HDF5 items.</P> + <P>While the default property settings are sufficient in many cases, certain + HDF5 features, such as compression, can be reasonably controlled only by the + user who has to provide the desired settings via property lists.</P> +</DD> +</DL> + +\section GLS_R R + +<DL> + <DT>Rank</DT> + <DD>The number of dimensions of a non-null dataspace.</DD> +</DL> + +<DL> + <DT>Reference</DT> + <DD> + <OL> + <LI>An HDF5 object reference</LI> + <LI>An HDF5 dataset region reference</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Reference datatype</DT> + <DD> + <OL> + <LI>An HDF5 datatype whose elements represent references to HDF5 + objects.</LI> + <LI>An HDF5 datatype whose elements represent references to regions of an + HDF5 dataset.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Region reference</DT> + <DD>See dataset region reference.</DD> +</DL> + +<DL> + <DT>Root group</DT> + <DD> + <P>An HDF5 group that is present in all HDF5 files and that acts as the + entry or base point for all other data stored in an HDF5 file.</P> + <P>The root group is "the mother of all objects" in an HDF5 file in the + sense that all objects (and their attributes) can be discovered, + beginning at the root group, by combinations of the following + operations:</P> + <UL> + <LI>Link traversal</LI> + <LI>De-referencing of object references</LI> + </UL> + <P>This discovery is portable and robust with respect to file-internal + storage reorganization.</P> +</DD> +</DL> + +\section GLS_S S + +<DL> + <DT>Scalar dataspace</DT> + <DD>A kind of HDF5 dataspace that has the shape of a singleton, i.e., a set + containing a single element. Array variables with this shape store exactly one + element.</DD> +</DL> + +<DL> + <DT>Selection</DT> + <DD> + <OL> + <LI>A subset of points of an HDF5 dataspace. The subset might be a point + selection or a combination (union, intersection, etc.) of hyperslabs.</LI> + <LI>A subset of dataset elements associated with a dataspace selection as + described under 1.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Serialization</DT> + <DD> + <OL> + <LI>The flattening of an N-dimensional array into a 1-dimensional + array.</LI> + <LI>The encoding of a complex data item as a linear byte stream.</LI> + </OL> + </DD> +</DL> + +<DL> + <DT>Soft link</DT> + <DD>A kind of HDF5 link in which the link destination is specified as an HDF5 + path name. The path name may or may not refer to an actual object.</DD> +</DL> + +<DL> + <DT>Storage layout</DT> + <DD>The storage arrangement for dataset elements, links in a group's link + collection, or attributes in an object's attribute collection.</DD> +</DL> + +<DL> + <DT>String datatype</DT> + <DD></DD> +</DL> + +<DL> + <DT>Super block</DT> + <DD>An HDF5 file format primitive; a block of data which contains information + required to access HDF5 files in a portable manner on multiple platforms. The + super block contains information such as version numbers, the size of offsets + and lengths, and the location of the root group.</DD> +</DL> + +<DL> + <DT>SWMR</DT> + <DD>Single Writer Multiple Reader, a file access mode in which a single + process is permitted to write data to an HDF5 file while other processes are + permitted to read data from the same file without the need of inter-process + communication or synchronization.</DD> +</DL> + +<DL> + <DT>Symbolic link</DT> + <DD>An external link or a soft link.</DD> +</DL> + +\section GLS_U U + +<DL> + <DT>User block</DT> + <DD>An HDF5 file format primitive that allows one to set aside a fixed-size + (at least 512 bytes or any power of 2 thereafter) contiguous range of bytes at + the beginning of an HDF5 file for application purposes which will be + skipped/ignored by the HDF5 library.</DD> +</DL> + +<DL> + <DT>UTF-8</DT> + <DD> + <P>A variable-length (1-4 bytes per code point) encoding of the Unicode set + of code points. This is the encoding supported by HDF5 to represent Unicode + strings.</P> + <P>The ASCII encoding is a proper subset of UTF-8.</P> +</DD> +</DL> + +\section GLS_V V + +<DL> + <DT>Variable-length (sequence) datatype</DT> + <DD>A family of HDF5 datatypes whose elements are variable-length sequences of + a given datatype.</DD> +</DL> + +<DL> + <DT>Virtual Dataset (VDS)</DT> + <DD>An HDF5 dataset with virtual storage layout. A dataset whose elements are + partially or entirely stored physically in other datasets.</DD> +</DL> + +<DL> + <DT>Virtual File Driver (VFD)</DT> + <DD></DD> +</DL> + + +<DL> + <DT>Virtual layout</DT> + <DD></DD> +</DL> + + +<DL> + <DT>Virtual Object Layer (VOL)</DT> + <DD></DD> +</DL> + +*/ diff --git a/doxygen/dox/H5AC_cache_config_t.dox b/doxygen/dox/H5AC_cache_config_t.dox index 9b9862b..3faecd5 100644 --- a/doxygen/dox/H5AC_cache_config_t.dox +++ b/doxygen/dox/H5AC_cache_config_t.dox @@ -26,7 +26,7 @@ * * \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead * - * The trace file is a debuging feature that allow the capture of + * The trace file is a debugging feature that allow the capture of * top level metadata cache requests for purposes of debugging and/or * optimization. This field should normally be set to \c FALSE, as * trace file collection imposes considerable overhead. @@ -82,7 +82,7 @@ * H5C_incr__off ) && ( decr_mode == H5C_decr__off )}). There * is no logical reason why this should be so, but it simplifies * implementation and testing, and I can't think of any reason - * why it would be desireable. If you can think of one, I'll + * why it would be desirable. If you can think of one, I'll * revisit the issue. (JM) * \endparblock * @@ -383,7 +383,7 @@ * to disk.\n * When the sync point is reached (or when there is a user generated * flush), process zero flushes sufficient entries to bring it into - * complience with its min clean size (or flushes all dirty entries in + * compliance with its min clean size (or flushes all dirty entries in * the case of a user generated flush), broad casts the list of * entries just cleaned to all the other processes, and then exits * the sync point.\n diff --git a/doxygen/dox/OtherSpecs.dox b/doxygen/dox/OtherSpecs.dox deleted file mode 100644 index e53f26e..0000000 --- a/doxygen/dox/OtherSpecs.dox +++ /dev/null @@ -1,11 +0,0 @@ -/** \page IMG HDF5 Image and Palette Specification Version 1.2 - -\htmlinclude ImageSpec.html - -*/ - -/** \page TBL HDF5 Table Specification Version 1.0 - -\htmlinclude TableSpec.html - -*/ diff --git a/doxygen/dox/Overview.dox b/doxygen/dox/Overview.dox index 754722e..040769c 100644 --- a/doxygen/dox/Overview.dox +++ b/doxygen/dox/Overview.dox @@ -1,14 +1,12 @@ /** \mainpage notitle -This is the documentation set for HDF5. You can -<a href="hdf5-doc.tgz">download</a> it as a tgz archive for offline reading. - -This is the documention set for HDF5 in terms of specifications and software -developed and maintained by <a href="https://www.hdfgroup.org/">The HDF -Group</a>. It is impractical to document the entire HDF5 ecosystem in one place, -and you should also consult the documentation sets of the many outstanding -community projects. +This is the documentation set for HDF5. +It includes specifications and documentation +of software and tools developed and maintained by +<a href="https://www.hdfgroup.org/">The HDF Group</a>. It is impractical to document +the entire HDF5 ecosystem in one place, and you should also consult the documentation +sets of the many outstanding community projects. For a first contact with HDF5, the best place is to have a look at the \link GettingStarted getting started \endlink page that shows you how to write and @@ -19,12 +17,28 @@ technical documentation consists to varying degrees of information related to <em>tasks</em>, <em>concepts</em>, or <em>reference</em> material. As its title suggests, the \link RM Reference Manual \endlink is 100% reference material, while the \link Cookbook \endlink is focused on tasks. The different guide-type -documents cover a mix of tasks, concepts, and reference, to help a certain +documents cover a mix of tasks, concepts, and reference, to help a specific <em>audience</em> succeed. -Finally, do not miss the search engine (top right-hand corner)! If you are -looking for a specific function, it'll take you there directly. If unsure, it'll -give you an idea of what's on offer and a few promising leads. +\par Versions + Version-specific documentation (see the version in the title area) can be found + here: + - HDF5 <code>develop</code> branch (this site) + - <a href="https://docs.hdfgroup.org/hdf5/v1_12/index.html">HDF5 1.12.x</a> + - <a href="https://docs.hdfgroup.org/hdf5/v1_10/index.html">HDF5 1.10.x</a> + - <a href="https://docs.hdfgroup.org/hdf5/v1_8/index.html">HDF5 1.8.x</a> + +\par Search + If you are looking for a specific function, constant, type, etc., use the + search box in the top right-hand corner!\n Otherwise, check out the + \link FTS full-text search\endlink. + +\par Offline reading + You can <a href="hdf5-doc.tgz">download</a> it as a tgz archive for offline reading. + +\par History + A snapshot (~April 2017) of the pre-Doxygen HDF5 documentation can be found + <a href="https://docs.hdfgroup.org/archive/support/HDF5/doc/index.html">here</a>. \par ToDo List There is plenty of <a href="./todo.html">unfinished business</a>. diff --git a/doxygen/dox/Specifications.dox b/doxygen/dox/Specifications.dox index bd7e849..f6fee78 100644 --- a/doxygen/dox/Specifications.dox +++ b/doxygen/dox/Specifications.dox @@ -18,4 +18,40 @@ \li <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf"> HDF5 Dimension Scale Specification</a> -*/
\ No newline at end of file +*/ + +/** \page FMT3 HDF5 File Format Specification Version 3.0 + +\htmlinclude H5.format.html + +*/ + +/** \page FMT2 HDF5 File Format Specification Version 2.0 + +\htmlinclude H5.format.2.0.html + +*/ + +/** \page FMT11 HDF5 File Format Specification Version 1.1 + +\htmlinclude H5.format.1.1.html + +*/ + +/** \page FMT1 HDF5 File Format Specification Version 1.0 + +\htmlinclude H5.format.1.0.html + +*/ + +/** \page IMG HDF5 Image and Palette Specification Version 1.2 + +\htmlinclude ImageSpec.html + +*/ + +/** \page TBL HDF5 Table Specification Version 1.0 + +\htmlinclude TableSpec.html + +*/ diff --git a/doxygen/dox/TechnicalNotes.dox b/doxygen/dox/TechnicalNotes.dox index 2bda175..9bd2802 100644 --- a/doxygen/dox/TechnicalNotes.dox +++ b/doxygen/dox/TechnicalNotes.dox @@ -1,6 +1,10 @@ /** \page TN Technical Notes \li \link api-compat-macros API Compatibility Macros \endlink +\li \ref APPDBG "Debugging HDF5 Applications" +\li \ref FMTDISC "File Format Walkthrough" +\li \ref FILTER "Filters" +\li \ref IOFLOW "HDF5 Raw I/O Flow Notes" \li \ref TNMDC "Metadata Caching in HDF5" \li \ref MT "Thread Safe library" \li \ref VFL "Virtual File Layer" @@ -13,8 +17,32 @@ */ +/** \page IOFLOW HDF5 Raw I/O Flow Notes + +\htmlinclude IOFlow.html + +*/ + /** \page VFL HDF5 Virtual File Layer \htmlinclude VFL.html */ + +/** \page FMTDISC HDF5 File Format Discussion + +\htmlinclude FileFormat.html + +*/ + +/** \page FILTER HDF5 Filters + +\htmlinclude Filters.html + +*/ + +/** \page APPDBG Debugging HDF5 Applications + +\htmlinclude DebuggingHDF5Applications.html + +*/
\ No newline at end of file diff --git a/doxygen/dox/api-compat-macros.dox b/doxygen/dox/api-compat-macros.dox index 4a1578d..6b506a1 100644 --- a/doxygen/dox/api-compat-macros.dox +++ b/doxygen/dox/api-compat-macros.dox @@ -300,208 +300,6 @@ -DH5Lget_info_vers=1 application.c \endcode - \subsubsection fun-options-112 Function Mapping Options in Releases 1.12.x - <table> - <tr> - <th style="text-align: left;">Macro <br/> (\Code{H5xxx})</th> - <th>Default function used if no macro specified - <ul><li>Function/struct mapping:\Code{H5xxx_vers=N}</li></ul> - </th> - <th>Function used if specifying 1.10 - <ul><li>Function/struct mapping: \Code{H5xxx_vers=1}</li></ul> - </th> - </tr> - <tr> - <td>H5Lget_info()</td> - <td>H5Lget_info2() - <ul> - <li>Function mapping:\Code{H5Lget_info_vers=2}</li> - <li>Struct mapping:\Code{H5L_info_t_vers=2}</li> - </ul> - </td> - <td>H5Lget_info1() - <ul> - <li>Function mapping \Code{H5Lget_info_vers=1}</li> - <li>Struct mapping: \Code{H5L_info_t_vers=1}</li> - </ul> - </td> - </tr> - <tr> - <td>H5Lget_info_by_idx()</td> - <td>H5Lget_info_by_idx2() - <ul> - <li>Function mapping: \Code{H5Lget_info_by_idx_vers=2}</li> - <li>Struct mapping: \Code{H5L_info_t_vers=2}</li> - </ul> - </td> - <td>H5Lget_info_by_idx1() - <ul> - <li>Function mapping: \Code{H5Lget_info_by_idx_vers=1}</li> - <li>Struct mapping: \Code{H5L_info_t_vers=1}</li> - </ul> - </td> - </tr> - <tr> - <td>H5Literate()</td> - <td>H5Literate2() - <ul> - <li>Function mapping: \Code{H5Literate_vers=2}</li> - <li>Struct mapping: \Code{H5L_iterate_t_vers=2}</li> - </ul> - </td> - <td>H5Literate1() - <ul> - <li>Function mapping: \Code{H5Literate_vers=1}</li> - <li>Struct mapping: \Code{H5L_iterate_t_vers=1}</li> - </ul> - </td> - </tr> - <tr> - <td>H5Literate_by_name()</td> - <td>H5Literate_by_name2() - <ul> - <li>Function mapping: \Code{H5Literate_by_name_vers=2}</li> - <li>Struct mapping: \Code{H5L_iterate_t_vers=2}</li> - </ul> - </td> - <td>H5Literate_by_name1() - <ul> - <li>Function mapping: \Code{H5Literate_by_name_vers=1}</li> - <li>Struct mapping: \Code{H5L_iterate_t_vers=1}</li> - </ul> - </td> - </tr> - <tr> - <td>H5Lvisit()</td> - <td>H5Lvisit2() - <ul> - <li>Function mapping: \Code{H5Lvisit_vers=2}</li> - <li>Struct mapping: \Code{H5L_iterate_t_vers=2}</li> - </ul> - </td> - <td>H5Lvisit1() - <ul> - <li>Function mapping: \Code{H5Lvisit_vers=1}</li> - <li>Struct mapping: \Code{H5L_iterate_t_vers=1}</li> - </ul> - </td> - </tr> - <tr> - <td>H5Lvisit_by_name()</td> - <td>H5Lvisit_by_name2() - <ul> - <li>Function mapping: \Code{H5Lvisit_by_name_vers=2}</li> - <li>Struct mapping: \Code{H5L_iterate_t_vers=2}</li> - </ul> - </td> - <td>H5Lvisit_by_name1() - <ul> - <li>Function mapping: \Code{H5Lvisit_by_name_vers=1}</li> - <li>Struct mapping: \Code{H5L_iterate_t_vers=1}</li> - </ul> - </td> - </tr> - <tr> - <td>H5Oget_info()</td> - <td>H5Oget_info3() - <ul> - <li>Function mapping: \Code{H5Oget_info_vers=3}</li> - <li>Struct mapping: \Code{H5O_info_t_vers=2}</li> - </ul> - </td> - <td>H5Oget_info1() - <ul> - <li>Function mapping: \Code{H5Oget_info_vers=1}</li> - <li>Struct mapping: \Code{H5O_info_t_vers=1}</li> - </ul> - </td> - </tr> - <tr> - <td>H5Oget_info_by_idx()</td> - <td>H5Oget_info_by_idx3() - <ul><li>Function mapping: \Code{H5Oget_info_by_idx_vers=3}</li> - <li>Struct mapping: \Code{H5O_info_t_vers=2}</li> - </ul> - </td> - <td>H5Oget_info_by_idx1() - <ul> - <li>Function mapping: \Code{H5Oget_info_by_idx_vers=1}</li> - <li>Struct mapping: \Code{H5O_info_t_vers=1}</li> - </ul> - </td> - </tr> - <tr> - <td>H5Oget_info_by_name()</td> - <td>H5Oget_info_by_name3() - <ul> - <li>Function mapping: \Code{H5O_get_info_by_name_vers=3}</li> - <li>Struct mapping: \Code{H5O_info_t_vers=2}</li> - </ul> - </td> - <td>H5Oget_info_by_name1() - <ul> - <li>Function mapping: \Code{H5O_get_info_by_name_vers=1}</li> - <li>Struct mapping: \Code{H5O_info_t_vers=1}</li> - </ul> - </td> - </tr> - <tr> - <td>H5Ovisit()</td> - <td>H5Ovisit3() - <ul> - <li>Function mapping: \Code{H5Ovisit_vers=3}</li> - <li>Struct mapping: \Code{H5O_iterate_t_vers=2}</li> - </ul> - </td> - <td>H5Ovisit1() - <ul><li>Function mapping: \Code{H5Ovisit_vers=1}</li> - <li>Struct mapping: \Code{H5O_iterate_t_vers=1}</li> - </ul> - </td> - </tr> - <tr> - <td>H5Ovisit_by_name()</td> - <td>H5Ovisit_by_name3() - <ul> - <li>Function mapping: \Code{H5Ovisit_by_name_vers=3}</li> - <li>Struct mapping: \Code{H5O_iterate_t_vers=2}</li> - </ul> - </td> - <td>H5Ovisit_by_name1() - <ul> - <li>Function mapping: \Code{H5Ovisit_by_name_vers=1}</li> - <li>Struct mapping: \Code{H5O_iterate_t_vers=1}</li> - </ul> - </td> - </tr> - <tr> - <td>H5Pencode()</td> - <td>H5Pencode2() - <ul> - <li>Function mapping: \Code{H5Pencode_vers=2}</li> - </ul> - </td> - <td>H5Pencode1() - <ul> - <li>Function mapping: \Code{H5Pencode_vers=1}</li> - </ul> - </td> - </tr> - <tr> - <td>H5Sencode()</td> - <td>H5Sencode2() - <ul> - <li>Function mapping: \Code{H5Sencode_vers=2}</li> - </ul> - </td> - <td>H5Sencode1() - <ul> - <li>Function mapping: \Code{H5Sencode_vers=1}</li> - </ul> - </td> - </tr> - </table> - \subsubsection fun-options-110 Function Mapping Options in Releases 1.10.x <table> <tr> diff --git a/doxygen/examples/DebuggingHDF5Applications.html b/doxygen/examples/DebuggingHDF5Applications.html new file mode 100644 index 0000000..3390887 --- /dev/null +++ b/doxygen/examples/DebuggingHDF5Applications.html @@ -0,0 +1,392 @@ +<html> + <head> + <title>Debugging HDF5 Applications</title> + + <h2>Introduction</h2> + + <p>The HDF5 library contains a number of debugging features to + make programmers' lives easier including the ability to print + detailed error messages, check invariant conditions, display + timings and other statistics, and trace API function calls and + return values. + + </p><dl> + <dt><b>Error Messages</b> + </dt><dd>Error messages are normally displayed automatically on the + standard error stream and include a stack trace of the library + including file names, line numbers, and function names. The + application has complete control over how error messages are + displayed and can disable the display on a permanent or + temporary basis. Refer to the documentation for the H5E error + handling package. + + <br><br> + </dd><dt><b>Invariant Conditions</b> + </dt><dd>Unless <code>NDEBUG</code> is defined during compiling, the + library will include code to verify that invariant conditions + have the expected values. When a problem is detected the + library will display the file and line number within the + library and the invariant condition that failed. A core dump + may be generated for post mortem debugging. The code to + perform these checks can be included on a per-package bases. + + <br><br> + </dd><dt><b>Timings and Statistics</b> + </dt><dd>The library can be configured to accumulate certain + statistics about things like cache performance, datatype + conversion, data space conversion, and data filters. The code + is included on a per-package basis and enabled at runtime by + an environment variable. + + <br><br> + </dd><dt><b>API Tracing</b> + </dt><dd>All API calls made by an application can be displayed and + include formal argument names and actual values and the + function return value. This code is also conditionally + included at compile time and enabled at runtime. + </dd></dl> + + <p>The statistics and tracing can be displayed on any output + stream (including streams opened by the shell) with output from + different packages even going to different streams. + + </p><h2>Error Messages</h2> + + <p>By default any API function that fails will print an error + stack to the standard error stream. + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <tbody><tr> + <td> + <p><code></code></p><pre><code> +HDF5-DIAG: Error detected in thread 0. Back trace follows. + #000: H5F.c line 1245 in H5Fopen(): unable to open file + major(04): File interface + minor(10): Unable to open file + #001: H5F.c line 846 in H5F_open(): file does not exist + major(04): File interface + minor(10): Unable to open file + </code></pre> + </td> + </tr> + </tbody></table> + </center> + + <p>The error handling package (H5E) is described + <a href="./group___h5_e.html">elsewhere</a>. + + </p><h2>Invariant Conditions</h2> + + <p>To include checks for invariant conditions the library should + be configured with <code>--disable-production</code>, the + default for versions before 1.2. The library designers have made + every attempt to handle error conditions gracefully but an + invariant condition assertion may fail in certain cases. The + output from a failure usually looks something like this: + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <tbody><tr> + <td> + <p><code></code></p><pre><code> +Assertion failed: H5.c:123: i<NELMTS(H5_debug_g) +IOT Trap, core dumped. + </code></pre> + </td> + </tr> + </tbody></table> + </center> + + <h2>Timings and Statistics</h2> + + <p>Code to accumulate statistics is included at compile time by + using the <code>--enable-debug</code> configure switch. The + switch can be followed by an equal sign and a comma-separated + list of package names or else a default list is used. + + </p><p> + </p><center> + <table border="" align="center" width="80%"> + <tbody><tr> + <th>Name</th> + <th>Default</th> + <th>Description</th> + </tr> + <tr> + <td align="center">a</td> + <td align="center">No</td> + <td>Attributes</td> + </tr> + <tr> + <td align="center">ac</td> + <td align="center">Yes</td> + <td>Meta data cache</td> + </tr> + <tr> + <td align="center">b</td> + <td align="center">Yes</td> + <td>B-Trees</td> + </tr> + <tr> + <td align="center">d</td> + <td align="center">Yes</td> + <td>Datasets</td> + </tr> + <tr> + <td align="center">e</td> + <td align="center">Yes</td> + <td>Error handling</td> + </tr> + <tr> + <td align="center">f</td> + <td align="center">Yes</td> + <td>Files</td> + </tr> + <tr> + <td align="center">g</td> + <td align="center">Yes</td> + <td>Groups</td> + </tr> + <tr> + <td align="center">hg</td> + <td align="center">Yes</td> + <td>Global heap</td> + </tr> + <tr> + <td align="center">hl</td> + <td align="center">No</td> + <td>Local heaps</td> + </tr> + <tr> + <td align="center">i</td> + <td align="center">Yes</td> + <td>Interface abstraction</td> + </tr> + <tr> + <td align="center">mf</td> + <td align="center">No</td> + <td>File memory management</td> + </tr> + <tr> + <td align="center">mm</td> + <td align="center">Yes</td> + <td>Library memory management</td> + </tr> + <tr> + <td align="center">o</td> + <td align="center">No</td> + <td>Object headers and messages</td> + </tr> + <tr> + <td align="center">p</td> + <td align="center">Yes</td> + <td>Property lists</td> + </tr> + <tr> + <td align="center">s</td> + <td align="center">Yes</td> + <td>Data spaces</td> + </tr> + <tr> + <td align="center">t</td> + <td align="center">Yes</td> + <td>Datatypes</td> + </tr> + <tr> + <td align="center">v</td> + <td align="center">Yes</td> + <td>Vectors</td> + </tr> + <tr> + <td align="center">z</td> + <td align="center">Yes</td> + <td>Raw data filters</td> + </tr> + </tbody></table> + </center> + + <p>In addition to including the code at compile time the + application must enable each package at runtime. This is done + by listing the package names in the <code>HDF5_DEBUG</code> + environment variable. That variable may also contain file + descriptor numbers (the default is `2') which control the output + for all following packages up to the next file number. The + word <code>all</code> refers to all packages. Any word my be + preceded by a minus sign to turn debugging off for the package. + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <caption align="top"><b>Sample debug specifications</b></caption> + <tbody><tr valign="top"> + <td><code>all</code></td> + <td>This causes debugging output from all packages to be + sent to the standard error stream.</td> + </tr> + <tr valign="top"> + <td><code>all -t -s</code></td> + <td>Debugging output for all packages except datatypes + and data spaces will appear on the standard error + stream.</td> + </tr> + <tr valign="top"> + <td><code>-all ac 255 t,s</code></td> + <td>This disables all debugging even if the default was to + debug something, then output from the meta data cache is + send to the standard error stream and output from data + types and spaces is sent to file descriptor 255 which + should be redirected by the shell.</td> + </tr> + </tbody></table> + </center> + + <p>The components of the <code>HDF5_DEBUG</code> value may be + separated by any non-lowercase letter. + + </p><h2>API Tracing</h2> + + <p>The HDF5 library can trace API calls by printing the + function name, the argument names and their values, and the + return value. Some people like to see lots of output during + program execution instead of using a good symbolic debugger, and + this feature is intended for their consumption. For example, + the output from <code>h5ls foo</code> after turning on tracing, + includes: + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <tbody><tr> + <td> + <code><pre> +H5Tcopy(type=184549388) = 184549419 (type); +H5Tcopy(type=184549392) = 184549424 (type); +H5Tlock(type=184549424) = SUCCEED; +H5Tcopy(type=184549393) = 184549425 (type); +H5Tlock(type=184549425) = SUCCEED; +H5Fopen(filename="foo", flags=0, access=H5P_DEFAULT) = FAIL; +HDF5-DIAG: Error detected in thread 0. Back trace follows. + #000: H5F.c line 1245 in H5Fopen(): unable to open file + major(04): File interface + minor(10): Unable to open file + #001: H5F.c line 846 in H5F_open(): file does not exist + major(04): File interface + minor(10): Unable to open file + </pre></code> + </td> + </tr> + </tbody></table> + </center> + + <p>The code that performs the tracing must be included in the + library by specifying the <code>--enable-trace</code> + configuration switch (the default for versions before 1.2). Then + the word <code>trace</code> must appear in the value of the + <code>HDF5_DEBUG</code> variable. The output will appear on the + last file descriptor before the word <code>trace</code> or two + (standard error) by default. + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <tbody><tr> + <td>To display the trace on the standard error stream: + <code><pre>$ env HDF5_DEBUG=trace a.out + </pre></code> + </td> + </tr> + <tr> + <td>To send the trace to a file: + <code><pre>$ env HDF5_DEBUG="55 trace" a.out 55>trace-output + </pre></code> + </td> + </tr> + </tbody></table> + </center> + + <h3>Performance</h3> + + <p>If the library was not configured for tracing then there is no + unnecessary overhead since all tracing code is excluded. + However, if tracing is enabled but not used there is a small + penalty. First, code size is larger because of extra + statically-declared character strings used to store argument + types and names and extra auto variable pointer in each + function. Also, execution is slower because each function sets + and tests a local variable and each API function calls the + <code>H5_trace()</code> function. + + </p><p>If tracing is enabled and turned on then the penalties from the + previous paragraph apply plus the time required to format each + line of tracing information. There is also an extra call to + H5_trace() for each API function to print the return value. + + </p><h3>Safety</h3> + + <p>The tracing mechanism is invoked for each API function before + arguments are checked for validity. If bad arguments are passed + to an API function it could result in a segmentation fault. + However, the tracing output is line-buffered so all previous + output will appear. + + </p><h3>Completeness</h3> + + <p>There are two API functions that don't participate in + tracing. They are <code>H5Eprint()</code> and + <code>H5Eprint_cb()</code> because their participation would + mess up output during automatic error reporting. + + </p><p>On the other hand, a number of API functions are called during + library initialization and they print tracing information. + + </p><h3>Implementation</h3> + + <p>For those interested in the implementation here is a + description. Each API function should have a call to one of the + <code>H5TRACE()</code> macros immediately after the + <code>FUNC_ENTER()</code> macro. The first argument is the + return type encoded as a string. The second argument is the + types of all the function arguments encoded as a string. The + remaining arguments are the function arguments. This macro was + designed to be as terse and unobtrousive as possible. + + </p><p>In order to keep the <code>H5TRACE()</code> calls synchronized + with the source code we've written a perl script which gets + called automatically just before Makefile dependencies are + calculated for the file. However, this only works when one is + using GNU make. To reinstrument the tracing explicitly, invoke + the <code>trace</code> program from the hdf5 bin directory with + the names of the source files that need to be updated. If any + file needs to be modified then a backup is created by appending + a tilde to the file name. + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <caption align="top"><b>Explicit Instrumentation</b></caption> + <tbody><tr> + <td> + <code><pre> +$ ../bin/trace *.c +H5E.c: in function `H5Ewalk_cb': +H5E.c:336: warning: trace info was not inserted + </pre></code> + </td> + </tr> + </tbody></table> + </center> + + <p>Note: The warning message is the result of a comment of the + form <code>/*NO TRACE*/</code> somewhere in the function + body. Tracing information will not be updated or inserted if + such a comment exists. + + </p><p>Error messages have the same format as a compiler so that they + can be parsed from program development environments like + Emacs. Any function which generates an error will not be + modified.</p> + +</body></html> diff --git a/doxygen/examples/FileFormat.html b/doxygen/examples/FileFormat.html new file mode 100644 index 0000000..fc35357 --- /dev/null +++ b/doxygen/examples/FileFormat.html @@ -0,0 +1,1275 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<!-- saved from url=(0072)https://gamma.hdfgroup.org/papers/HISS/030515.FileFormat/FileFormat.html --> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <title>HDF5 File Format Discussion</title> + + <meta name="author" content="Quincey Koziol"> +</head> + +<body text="#000000" bgcolor="#FFFFFF"> + +<style type="text/css"> +OL.loweralpha { list-style-type: lower-alpha } +OL.upperroman { list-style-type: upper-roman } +</style> + +<style type="text/css"> +TD CAPTION EM { color: red } +TD EM { color: blue } +TABLE CAPTION STRONG { font-size: larger } +</style> + +<center><h1>HDF5 File Format Discussion</h1></center> +<center><h3>Quincey Koziol<br> + koziol@ncsa.uiuc.edu<br> + May 15, 2003 +</h3></center> + +<ol class="upperroman"> + +<li><h3><u>Document's Audience:</u></h3> + +<ul> + <li>Current H5 library designers and knowledgable external developers.</li> +</ul> + +</li><li><h3><u>Background Reading:</u></h3> + +<dl> + <dt><a href="https://docs.hdfgroup.org/hdf5/develop/_s_p_e_c.html">HDF5 File Format Specification</a> + </dt><dd>This describes the current HDF5 file format. +</dd></dl> + +</li><li><h3><u>Introduction:</u></h3> + +<dl> + <dt><strong>What is this document about?</strong></dt> + <dd>This document attempts to explain the HDF5 file format + specification with a few examples and describes some potential + improvements to the format specification. + </dd> <br> +</dl> + +</li><li><h3><u>File Format Examples:</u></h3> + +<p>This section has several small programs and describes the format of a file +created with each of them. +</p> + +<p>Example program one - <em>Create an empty file</em>: +</p><pre> <code> +#include "hdf5.h" +#include <assert.h> + +int main() +{ + hid_t fid; /* File ID */ + herr_t ret; /* Generic return value */ + + /* Create the file */ + fid=H5Fcreate("example1.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + assert(fid>=0); + + /* Close the file */ + ret=H5Fclose(fid); + assert(ret>=0); + + return(0); +} +</assert.h></code> </pre> + + <center> + <table border="" align="center" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Super Block</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td>\211</td> + <td>'H'</td> + <td>'D'</td> + <td>'F'</td> + </tr> + + <tr align="center"> + <td>\r</td> + <td>\n</td> + <td>\032</td> + <td>\n</td> + </tr> + + <tr align="center"> + <td>0</td> + <td>0</td> + <td>0</td> + <td>0</td> + </tr> + + <tr align="center"> + <td>0</td> + <td>8</td> + <td>8</td> + <td>0</td> + </tr> + + <tr align="center"> + <td colspan="2">4</td> + <td colspan="2">16</td> + </tr> + + <tr align="center"> + <td colspan="4">0x00000003</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4">?</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>928<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4">H5G_CACHED_STAB (1)</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4"><br>384<br><br></td> + </tr> + <tr align="center"> + <td colspan="4"><br>96<br><br></td> + </tr> + </tbody></table> + </td> + </tr> + </tbody></table> + </td> + </tr> + </tbody></table> + </center> +<br> +<pre> <code> +%h5debug example1.h5 + +Reading signature at address 0 (rel) +File Super Block... +File name: example1.h5 +File access flags 0x00000000 +File open reference count: 1 +Address of super block: 0 (abs) +Size of user block: 0 bytes +Super block version number: 0 +Free list version number: 0 +Root group symbol table entry version number: 0 +Shared header version number: 0 +Size of file offsets (haddr_t type): 8 bytes +Size of file lengths (hsize_t type): 8 bytes +Symbol table leaf node 1/2 rank: 4 +Symbol table internal node 1/2 rank: 16 +File consistency flags: 0x00000003 +Base address: 0 (abs) +Free list address: UNDEF (rel) +Address of driver information block: UNDEF (rel) +Root group symbol table entry: + Name offset into private heap: 0 + Object header address: 928 + Dirty: Yes + Cache info type: Symbol Table + Cached information: + B-tree address: 384 + Heap address: 96 +</code> </pre> + + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group Object Header</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="1" width="25%">1</td> + <td colspan="1" width="25%">0</td> + <td colspan="2" width="50%">2</td> + </tr> + <tr align="center"> + <td colspan="4">1</td> + </tr> + <tr align="center"> + <td colspan="4">32</td> + </tr> + <tr align="center"> + <td colspan="2">0x0011</td> + <td colspan="2">16</td> + </tr> + <tr align="center"> + <td>0x01</td> + <td colspan="3">0</td> + </tr> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4"><br>384<br><br></td> + </tr> + <tr align="center"> + <td colspan="4"><br>96<br><br></td> + </tr> + </tbody></table> + </td> + </tr> + <tr align="center"> + <td colspan="2">0</td> + <td colspan="2">0</td> + </tr> + <tr align="center"> + <td>0x00</td> + <td colspan="3">0</td> + </tr> + </tbody></table> + </center> +<br> +<pre> <code> +%h5debug example1.h5 928 + +New address: 928 +Reading signature at address 928 (rel) +Object Header... +Dirty: 0 +Version: 1 +Header size (in bytes): 16 +Number of links: 1 +Number of messages (allocated): 2 (32) +Number of chunks (allocated): 1 (8) +Chunk 0... + Dirty: 0 + Address: 944 + Size in bytes: 32 +Message 0... + Message ID (sequence number): 0x0011 stab(0) + Shared message: No + Constant: Yes + Raw size in obj header: 16 bytes + Chunk number: 0 + Message Information: + B-tree address: 384 + Name heap address: 96 +Message 1... + Message ID (sequence number): 0x0000 null(0) + Shared message: No + Constant: No + Raw size in obj header: 0 bytes + Chunk number: 0 + Message Information: + <no info="" for="" this="" message=""> +</no></code> </pre> + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group Local Heap</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td>'H'</td> + <td>'E'</td> + <td>'A'</td> + <td>'P'</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4">256</td> + </tr> + + <tr align="center"> + <td colspan="4">8</td> + </tr> + + <tr align="center"> + <td colspan="4">128</td> + </tr> + </tbody></table> + </center> +<br> + +<pre> <code> +%h5debug example1.h5 96 + +New address: 96 +Reading signature at address 96 (rel) +Local Heap... +Dirty: 0 +Header size (in bytes): 32 +Address of heap data: 128 +Data bytes allocated on disk: 256 +Data bytes allocated in core: 256 +Free Blocks (offset, size): + Block #0: 8, 248 +Percent of heap used: 3.12% +Data follows (`__' indicates free region)... + 0: 00 00 00 00 00 00 00 00 __ __ __ __ __ __ __ __ ........ + 16: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 32: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 48: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 64: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 80: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 96: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 112: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 128: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 144: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 160: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 176: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 192: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 208: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 224: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 240: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + +</code> </pre> + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group B-tree</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + </tr><tr align="center"> + <td>'T'</td> + <td>'R'</td> + <td>'E'</td> + <td>'E'</td> + + </tr><tr align="center"> + <td>0</td> + <td>0</td> + <td colspan="2">0</td> + + </tr><tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + + </tr><tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + + </tr></tbody></table> + </center> +<br> +<pre> <code> +%h5debug example1.h5 384 96 + +New address: 384 +Reading signature at address 384 (rel) +Tree type ID: H5B_SNODE_ID +Size of node: 544 +Size of raw (disk) key: 8 +Dirty flag: False +Number of initial dirty children: 0 +Level: 0 +Address of left sibling: UNDEF +Address of right sibling: UNDEF +Number of children (max): 0 (32) + +</code> </pre> + +<p></p> + +<p>Example program two - <em>Create a file with a single dataset in it</em>: +</p><pre> <code> +#include "hdf5.h" +#include <assert.h> + +int main() +{ + hid_t fid; /* File ID */ + hid_t sid; /* Dataspace ID */ + hid_t did; /* Dataset ID */ + herr_t ret; /* Generic return value */ + + /* Create the file */ + fid=H5Fcreate("example2.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT); + assert(fid>=0); + + /* Create a scalar dataspace for the dataset */ + sid=H5Screate(H5S_SCALAR); + assert(sid>=0); + + /* Create a trivial dataset */ + did=H5Dcreate(fid, "Dataset", H5T_NATIVE_INT, sid, H5P_DEFAULT); + assert(did>=0); + + /* Close the dataset */ + ret=H5Dclose(did); + assert(ret>=0); + + /* Close the dataspace */ + ret=H5Sclose(sid); + assert(ret>=0); + + /* Close the file */ + ret=H5Fclose(fid); + assert(ret>=0); + + return(0); +} +</assert.h></code> </pre> + + <center> + <table border="" align="center" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Super Block</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td>\211</td> + <td>'H'</td> + <td>'D'</td> + <td>'F'</td> + </tr> + + <tr align="center"> + <td>\r</td> + <td>\n</td> + <td>\032</td> + <td>\n</td> + </tr> + + <tr align="center"> + <td>0</td> + <td>0</td> + <td>0</td> + <td>0</td> + </tr> + + <tr align="center"> + <td>0</td> + <td>8</td> + <td>8</td> + <td>0</td> + </tr> + + <tr align="center"> + <td colspan="2">4</td> + <td colspan="2">16</td> + </tr> + + <tr align="center"> + <td colspan="4">0x00000003</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4">?</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>928<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4">H5G_CACHED_STAB (1)</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4"><br>384<br><br></td> + </tr> + <tr align="center"> + <td colspan="4"><br>96<br><br></td> + </tr> + </tbody></table> + </td> + </tr> + </tbody></table> + </td> + </tr> + </tbody></table> + </center> +<br> +<pre> <code> +%h5debug example2.h5 + +Reading signature at address 0 (rel) +File Super Block... +File name: example2.h5 +File access flags 0x00000000 +File open reference count: 1 +Address of super block: 0 (abs) +Size of user block: 0 bytes +Super block version number: 0 +Free list version number: 0 +Root group symbol table entry version number: 0 +Shared header version number: 0 +Size of file offsets (haddr_t type): 8 bytes +Size of file lengths (hsize_t type): 8 bytes +Symbol table leaf node 1/2 rank: 4 +Symbol table internal node 1/2 rank: 16 +File consistency flags: 0x00000003 +Base address: 0 (abs) +Free list address: UNDEF (rel) +Address of driver information block: UNDEF (rel) +Root group symbol table entry: + Name offset into private heap: 0 + Object header address: 928 + Dirty: Yes + Cache info type: Symbol Table + Cached entry information: + B-tree address: 384 + Heap address: 96 +</code> </pre> + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group Object Header</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="1" width="25%">1</td> + <td colspan="1" width="25%">0</td> + <td colspan="2" width="50%">2</td> + </tr> + <tr align="center"> + <td colspan="4">1</td> + </tr> + <tr align="center"> + <td colspan="4">32</td> + </tr> + <tr align="center"> + <td colspan="2">0x0011</td> + <td colspan="2">16</td> + </tr> + <tr align="center"> + <td>0x01</td> + <td colspan="3">0</td> + </tr> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4"><br>384<br><br></td> + </tr> + <tr align="center"> + <td colspan="4"><br>96<br><br></td> + </tr> + </tbody></table> + </td> + </tr> + <tr align="center"> + <td colspan="2">0</td> + <td colspan="2">0</td> + </tr> + <tr align="center"> + <td>0x00</td> + <td colspan="3">0</td> + </tr> + </tbody></table> + </center> +<br> +<pre> <code> +%h5debug example2.h5 928 + +New address: 928 +Reading signature at address 928 (rel) +Object Header... +Dirty: 0 +Version: 1 +Header size (in bytes): 16 +Number of links: 1 +Number of messages (allocated): 2 (32) +Number of chunks (allocated): 1 (8) +Chunk 0... + Dirty: 0 + Address: 944 + Size in bytes: 32 +Message 0... + Message ID: 0x0011 stab(0) + Shared message: No + Constant: Yes + Raw size in obj header: 16 bytes + Chunk number: 0 + Message Information: + B-tree address: 384 + Name heap address: 96 +Message 1... + Message ID: 0x0000 null(0) + Shared message: No + Constant: No + Raw size in obj header: 0 bytes + Chunk number: 0 + Message Information: + <no info="" for="" this="" message=""> +</no></code> </pre> + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group Local Heap</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td>'H'</td> + <td>'E'</td> + <td>'A'</td> + <td>'P'</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4">256</td> + </tr> + + <tr align="center"> + <td colspan="4">16</td> + </tr> + + <tr align="center"> + <td colspan="4">128</td> + </tr> + </tbody></table> + </center> +<br> + +<pre> <code> +%h5debug example2.h5 96 + +New address: 96 +Reading signature at address 96 (rel) +Local Heap... +Dirty: 0 +Header size (in bytes): 32 +Address of heap data: 128 +Data bytes allocated on disk: 256 +Data bytes allocated in core: 256 +Free Blocks (offset, size): + Block #0: 16, 240 +Percent of heap used: 6.25% +Data follows (`__' indicates free region)... + 0: 00 00 00 00 00 00 00 00 44 61 74 61 73 65 74 00 ........Dataset. + 16: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 32: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 48: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 64: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 80: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 96: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 112: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 128: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 144: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 160: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 176: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 192: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 208: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 224: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ + 240: __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ __ +</code> </pre> + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group B-tree</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + </tr><tr align="center"> + <td>'T'</td> + <td>'R'</td> + <td>'E'</td> + <td>'E'</td> + + </tr><tr align="center"> + <td>0</td> + <td>0</td> + <td colspan="2">1</td> + + </tr><tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + + </tr><tr align="center"> + <td colspan="4"><br>0xffffffffffffffff<br><br></td> + + </tr><tr align="center"> + <td colspan="4"><br>0<br><br></td> + + </tr><tr align="center"> + <td colspan="4"><br>1248<br><br></td> + + </tr><tr align="center"> + <td colspan="4"><br>8<br><br></td> + + </tr></tbody></table> + </center> +<br> +<pre> <code> +%h5debug example2.h5 384 96 + +New address: 384 +Reading signature at address 384 (rel) +Tree type ID: H5B_SNODE_ID +Size of node: 544 +Size of raw (disk) key: 8 +Dirty flag: False +Number of initial dirty children: 0 +Level: 0 +Address of left sibling: UNDEF +Address of right sibling: UNDEF +Number of children (max): 1 (32) +Child 0... + Address: 1248 + Left Key: + Heap offset: 0 + Name : + Right Key: + Heap offset: 8 + Name : Dataset +</code> </pre> + + <center> + <table border="" cellpadding="4" width="80%"> + <caption align="top"> + <strong>Root Group B-tree Symbol Table Node</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + + </tr><tr align="center"> + <td>'S'</td> + <td>'N'</td> + <td>'O'</td> + <td>'D'</td> + + </tr><tr align="center"> + <td>1</td> + <td>0</td> + <td colspan="2">1</td> + + </tr><tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td colspan="4">8</td> + </tr> + + <tr align="center"> + <td colspan="4"><br>976<br><br></td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4">0</td> + </tr> + + <tr align="center"> + <td colspan="4"><br><br>0<br><br><br></td> + </tr> + </tbody></table> + </td> + + </tr></tbody></table> + </center> +<br> +<pre> <code> +%h5debug example2.h5 1248 96 + +New address: 1248 +Reading signature at address 1248 (rel) +Symbol Table Node... +Dirty: No +Size of Node (in bytes): 328 +Number of Symbols: 1 of 8 +Symbol 0: + Name: `Dataset' + Name offset into private heap: 8 + Object header address: 976 + Dirty: No + Cache info type: Nothing Cached +</code> </pre> + + <center> + <table border="" cellpadding="4" width="90%"> + <caption align="top"> + <strong>'/Dataset' Object Header</strong> + </caption> + + <tbody><tr align="center"> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + <th width="25%">byte</th> + </tr> + + <tr align="center"> + <td colspan="1"><em>Version:</em> 1</td> + <td colspan="1"><em>Reserved:</em> 0</td> + <td colspan="2"><em>Number of Header Messages:</em> 6</td> + </tr> + <tr align="center"> + <td colspan="4"><em>Object Reference Count:</em> 1</td> + </tr> + <tr align="center"> + <td colspan="4"><em>Total Object Header Size:</em> 256</td> + </tr> +<!-- Fill Value Header Message --> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <caption align="top" color="#80FFFF"> + <em>Fill Value Header Message</em> + </caption> + <tbody><tr align="center"> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + </tr> + + <tr align="center"> + <!-- Object Header Message Type --> + <td colspan="2"><em>Message Type:</em> 0x0005</td> + <!-- Object Header Message Length --> + <td colspan="2"><em>Message Data Size:</em> 8</td> + </tr> + <tr align="center"> + <!-- Object Header Message Flags --> + <td colspan="1"><em>Flags:</em> 0x01</td> + <!-- Reserved --> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Version --> + <td colspan="1"><em>Version:</em> 1</td> + <!-- Space Allocation Time --> + <td colspan="1"><em>Space Allocation Time:</em> 2 (Late)</td> + <!-- Fill Value Writing Time --> + <td colspan="1"><em>Fill Value Writing Time:</em> 0 (At allocation)</td> + <!-- Fill Value Defined --> + <td colspan="1"><em>Fill Value Defined:</em> 0 (Undefined)</td> + </tr> + <tr align="center"> + <!-- Fill Value Datatype Size --> + <td colspan="4"><em>Fill Value Datatype Size:</em> 0 (Use dataset's datatype for fill-value datatype)</td> + </tr> + </tbody></table> + </td> + </tr> +<!-- Datatype Header Message --> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <caption align="top"> + <em>Datatype Header Message</em> + </caption> + <tbody><tr align="center"> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + </tr> + + <tr align="center"> + <!-- Object Header Message Type --> + <td colspan="2"><em>Message Type:</em> 0x0003</td> + <!-- Object Header Message Length --> + <td colspan="2"><em>Message Data Size:</em> 16</td> + </tr> + <tr align="center"> + <!-- Object Header Message Flags --> + <td colspan="1"><em>Flags:</em> 0x01</td> + <!-- Reserved --> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Type Class and Version --> + <td colspan="1"> + <table border="" width="100%"> + <tbody><tr align="center"> + <td width="50%"><em>Version:</em> 0x1</td> + <td><em>Class:</em> 0x0 (Fixed-Point)</td> + </tr> + </tbody></table> + </td> + <!-- Class Bit Field --> + <td colspan="3"><em>Fixed-Point Bit-Field:</em> 0x08 (Little-endian, No padding, Signed)</td> + </tr> + <tr align="center"> + <!-- Type Size (in bytes) --> + <td colspan="4"><em>Size:</em> 4</td> + </tr> + <tr align="center"> + <!-- Bit Offset --> + <td colspan="2"><em>Bit Offset:</em> 0</td> + <!-- Bit Precision --> + <td colspan="2"><em>Bit Precision:</em> 32</td> + </tr> + <tr align="center"> + <!-- Message alignment filler --> + <td colspan="4"><em>Message Alignment Filler:</em> -</td> + </tr> + </tbody></table> + </td> + </tr> +<!-- Dataspace Header Message --> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <caption align="top"> + <em>Dataspace Header Message</em> + </caption> + <tbody><tr align="center"> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + </tr> + + <tr align="center"> + <!-- Object Header Message Type --> + <td colspan="2"><em>Message Type:</em> 0x0001</td> + <!-- Object Header Message Length --> + <td colspan="2"><em>Message Data Size:</em> 8</td> + </tr> + <tr align="center"> + <!-- Object Header Message Flags --> + <td colspan="1"><em>Flags:</em> 0x00</td> + <!-- Reserved --> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Version --> + <td colspan="1"><em>Version:</em> 1</td> + <!-- Rank --> + <td colspan="1"><em>Rank:</em> 0 (Scalar)</td> + <!-- Flags --> + <td colspan="1"><em>Flags:</em> 0x00 (No maximum dimensions, no permutation information)</td> + <!-- Reserved --> + <td colspan="1"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Reserved --> + <td colspan="4"><em>Reserved:</em> 0</td> + </tr> + </tbody></table> + </td> + </tr> +<!-- Layout Header Message --> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <caption align="top"> + <em>Layout Header Message</em> + </caption> + <tbody><tr align="center"> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + </tr> + + <tr align="center"> + <!-- Object Header Message Type --> + <td colspan="2"><em>Message Type:</em> 0x0008</td> + <!-- Object Header Message Length --> + <td colspan="2"><em>Message Data Size:</em> 24</td> + </tr> + <tr align="center"> + <!-- Object Header Message Flags --> + <td colspan="1"><em>Flags:</em> 0x00</td> + <!-- Reserved --> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Version --> + <td colspan="1"><em>Version:</em> 1</td> + <!-- Rank --> + <td colspan="1"><em>Rank:</em> 1 (Dataspace rank+1)</td> + <!-- Class --> + <td colspan="1"><em>Class:</em> 1 (Contiguous)</td> + <!-- Reserved --> + <td colspan="1"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Reserved --> + <td colspan="4"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Address --> + <td colspan="4"><br><em>Address:</em> 0xffffffffffffffff (Undefined)<br><br></td> + </tr> + <tr align="center"> + <!-- Layout Dimensions --> + <td colspan="4"><em>Dimension 0 Size:</em> 4 (Datatype size)</td> + </tr> + <tr align="center"> + <!-- Message alignment filler --> + <td colspan="4"><em>Message Alignment Filler:</em> -</td> + </tr> + </tbody></table> + </td> + </tr> +<!-- Modification Date & Time Header Message --> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <caption align="top"> + <em>Modification Date & Time Header Message</em> + </caption> + <tbody><tr align="center"> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + </tr> + + <tr align="center"> + <!-- Object Header Message Type --> + <td colspan="2"><em>Message Type:</em> 0x0012</td> + <!-- Object Header Message Length --> + <td colspan="2"><em>Message Data Size:</em> 8</td> + </tr> + <tr align="center"> + <!-- Object Header Message Flags --> + <td colspan="1"><em>Flags:</em> 0x00</td> + <!-- Reserved --> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Version --> + <td colspan="1"><em>Version:</em> 1</td> + <!-- Reserved --> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + <tr align="center"> + <!-- Modification time --> + <td colspan="4"><em>Seconds Since Epoch:</em> 1052401700 (2003-05-08 08:48:20 CDT)</td> + </tr> + </tbody></table> + </td> + </tr> +<!-- Null Header Message --> + <tr align="center"> + <td colspan="4"> + <table border="" width="100%"> + <caption align="top"> + <em>Null Header Message</em> + </caption> + <tbody><tr align="center"> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + <th width="25%"></th> + </tr> + + <tr align="center"> + <td colspan="2"><em>Message Type:</em> 0x0000</td> + <td colspan="2"><em>Message Data Size:</em> 144</td> + </tr> + <tr align="center"> + <td colspan="1"><em>Flags:</em> 0x00</td> + <td colspan="3"><em>Reserved:</em> 0</td> + </tr> + </tbody></table> + </td> + </tr> + </tbody></table> + </center> +<br> +<pre> <code> +%h5debug example2.h5 976 + +New address: 976 +Reading signature at address 976 (rel) +Object Header... +Dirty: 0 +Version: 1 +Header size (in bytes): 16 +Number of links: 1 +Number of messages (allocated): 6 (32) +Number of chunks (allocated): 1 (8) +Chunk 0... + Dirty: 0 + Address: 992 + Size in bytes: 256 +Message 0... + Message ID (sequence number): 0x0005 `fill_new' (0) + Shared: No + Constant: Yes + Raw size in obj header: 8 bytes + Chunk number: 0 + Message Information: + Version: 1 + Space Allocation Time: Late + Fill Time: On Allocation + Fill Value Defined: Undefined + Size: 0 + Data type: <dataset type=""> +Message 1... + Message ID (sequence number): 0x0003 data_type(0) + Shared message: No + Constant: Yes + Raw size in obj header: 16 bytes + Chunk number: 0 + Message Information: + Type class: integer + Size: 4 bytes + Byte order: little endian + Precision: 32 bits + Offset: 0 bits + Low pad type: zero + High pad type: zero + Sign scheme: 2's comp +Message 2... + Message ID (sequence number): 0x0001 simple_dspace(0) + Shared message: No + Constant: No + Raw size in obj header: 8 bytes + Chunk number: 0 + Message Information: + Rank: 0 +Message 3... + Message ID (sequence number): 0x0008 layout(0) + Shared message: No + Constant: No + Raw size in obj header: 24 bytes + Chunk number: 0 + Message Information: + Data address: UNDEF + Number of dimensions: 1 + Size: {4} +Message 4... + Message ID (sequence number): 0x0012 mtime_new(0) + Shared message: No + Constant: No + Raw size in obj header: 8 bytes + Chunk number: 0 + Message Information: + Time: 2003-03-05 14:52:00 CST +Message 5... + Message ID (sequence number): 0x0000 null(0) + Shared message: No + Constant: No + Raw size in obj header: 144 bytes + Chunk number: 0 + Message Information: + <no info="" for="" this="" message=""> +</no></dataset></code> </pre> + +<p></p> + +</li></ol> + + + +</body></html> diff --git a/doxygen/examples/Filters.html b/doxygen/examples/Filters.html new file mode 100644 index 0000000..7054a3b --- /dev/null +++ b/doxygen/examples/Filters.html @@ -0,0 +1,450 @@ +<html> + <head> + <title>Filters</title> + <h1>Filters in HDF5</h1> + + <b>Note: Transient pipelines described in this document have not + been implemented.</b> + + <h2>Introduction</h2> + + <p>HDF5 allows chunked data to pass through user-defined filters + on the way to or from disk. The filters operate on chunks of an + <code>H5D_CHUNKED</code> dataset can be arranged in a pipeline + so output of one filter becomes the input of the next filter. + + </p><p>Each filter has a two-byte identification number (type + <code>H5Z_filter_t</code>) allocated by The HDF Group and can also be + passed application-defined integer resources to control its + behavior. Each filter also has an optional ASCII comment + string. + + </p> + <table> + <tbody><tr> + <th>Values for <code>H5Z_filter_t</code></th> + <th>Description</th> + </tr> + + <tr valign="top"> + <td><code>0-255</code></td> + <td>These values are reserved for filters predefined and + registered by the HDF5 library and of use to the general + public. They are described in a separate section + below.</td> + </tr> + + <tr valign="top"> + <td><code>256-511</code></td> + <td>Filter numbers in this range are used for testing only + and can be used temporarily by any organization. No + attempt is made to resolve numbering conflicts since all + definitions are by nature temporary.</td> + </tr> + + <tr valign="top"> + <td><code>512-65535</code></td> + <td>Reserved for future assignment. Please contact the + <a href="mailto:help@hdfgroup.org">HDF5 development team</a> + to reserve a value or range of values for + use by your filters.</td> + </tr></tbody></table> + + <h2>Defining and Querying the Filter Pipeline</h2> + + <p>Two types of filters can be applied to raw data I/O: permanent + filters and transient filters. The permanent filter pipeline is + defined when the dataset is created while the transient pipeline + is defined for each I/O operation. During an + <code>H5Dwrite()</code> the transient filters are applied first + in the order defined and then the permanent filters are applied + in the order defined. For an <code>H5Dread()</code> the + opposite order is used: permanent filters in reverse order, then + transient filters in reverse order. An <code>H5Dread()</code> + must result in the same amount of data for a chunk as the + original <code>H5Dwrite()</code>. + + </p><p>The permanent filter pipeline is defined by calling + <code>H5Pset_filter()</code> for a dataset creation property + list while the transient filter pipeline is defined by calling + that function for a dataset transfer property list. + + </p><dl> + <dt><code>herr_t H5Pset_filter (hid_t <em>plist</em>, + H5Z_filter_t <em>filter</em>, unsigned int <em>flags</em>, + size_t <em>cd_nelmts</em>, const unsigned int + <em>cd_values</em>[])</code> + </dt><dd>This function adds the specified <em>filter</em> and + corresponding properties to the end of the transient or + permanent output filter pipeline (depending on whether + <em>plist</em> is a dataset creation or dataset transfer + property list). The <em>flags</em> argument specifies certain + general properties of the filter and is documented below. The + <em>cd_values</em> is an array of <em>cd_nelmts</em> integers + which are auxiliary data for the filter. The integer values + will be stored in the dataset object header as part of the + filter information. + </dd><dt><code>int H5Pget_nfilters (hid_t <em>plist</em>)</code> + </dt><dd>This function returns the number of filters defined in the + permanent or transient filter pipeline depending on whether + <em>plist</em> is a dataset creation or dataset transfer + property list. In each pipeline the filters are numbered from + 0 through <em>N</em>-1 where <em>N</em> is the value returned + by this function. During output to the file the filters of a + pipeline are applied in increasing order (the inverse is true + for input). Zero is returned if there are no filters in the + pipeline and a negative value is returned for errors. + </dd><dt><code>H5Z_filter_t H5Pget_filter (hid_t <em>plist</em>, + int <em>filter_number</em>, unsigned int *<em>flags</em>, + size_t *<em>cd_nelmts</em>, unsigned int + *<em>cd_values</em>, size_t namelen, char name[])</code> + </dt><dd>This is the query counterpart of + <code>H5Pset_filter()</code> and returns information about a + particular filter number in a permanent or transient pipeline + depending on whether <em>plist</em> is a dataset creation or + dataset transfer property list. On input, <em>cd_nelmts</em> + indicates the number of entries in the <em>cd_values</em> + array allocated by the caller while on exit it contains the + number of values defined by the filter. The + <em>filter_number</em> should be a value between zero and + <em>N</em>-1 as described for <code>H5Pget_nfilters()</code> + and the function will return failure (a negative value) if the + filter number is out of range. If <em>name</em> is a pointer + to an array of at least <em>namelen</em> bytes then the filter + name will be copied into that array. The name will be null + terminated if the <em>namelen</em> is large enough. The + filter name returned will be the name appearing in the file or + else the name registered for the filter or else an empty string. + </dd></dl> + + <p>The flags argument to the functions above is a bit vector of + the following fields: + + </p> + <table> + <tbody><tr> + <th>Values for <em>flags</em></th> + <th>Description</th> + </tr> + + <tr valign="top"> + <td><code>H5Z_FLAG_OPTIONAL</code></td> + <td>If this bit is set then the filter is optional. If + the filter fails (see below) during an + <code>H5Dwrite()</code> operation then the filter is + just excluded from the pipeline for the chunk for which + it failed; the filter will not participate in the + pipeline during an <code>H5Dread()</code> of the chunk. + This is commonly used for compression filters: if the + compression result would be larger than the input then + the compression filter returns failure and the + uncompressed data is stored in the file. If this bit is + clear and a filter fails then the + <code>H5Dwrite()</code> or <code>H5Dread()</code> also + fails.</td> + </tr> + </tbody></table> + + <h2>Defining Filters</h2> + + <p>Each filter is bidirectional, handling both input and output to + the file, and a flag is passed to the filter to indicate the + direction. In either case the filter reads a chunk of data from + a buffer, usually performs some sort of transformation on the + data, places the result in the same or new buffer, and returns + the buffer pointer and size to the caller. If something goes + wrong the filter should return zero to indicate a failure. + + </p><p>During output, a filter that fails or isn't defined and is + marked as optional is silently excluded from the pipeline and + will not be used when reading that chunk of data. A required + filter that fails or isn't defined causes the entire output + operation to fail. During input, any filter that has not been + excluded from the pipeline during output and fails or is not + defined will cause the entire input operation to fail. + + </p><p>Filters are defined in two phases. The first phase is to + define a function to act as the filter and link the function + into the application. The second phase is to register the + function, associating the function with an + <code>H5Z_filter_t</code> identification number and a comment. + + </p><dl> + <dt><code>typedef size_t (*H5Z_func_t)(unsigned int + <em>flags</em>, size_t <em>cd_nelmts</em>, const unsigned int + <em>cd_values</em>[], size_t <em>nbytes</em>, size_t + *<em>buf_size</em>, void **<em>buf</em>)</code> + </dt><dd>The <em>flags</em>, <em>cd_nelmts</em>, and + <em>cd_values</em> are the same as for the + <code>H5Pset_filter()</code> function with the additional flag + <code>H5Z_FLAG_REVERSE</code> which is set when the filter is + called as part of the input pipeline. The input buffer is + pointed to by <em>*buf</em> and has a total size of + <em>*buf_size</em> bytes but only <em>nbytes</em> are valid + data. The filter should perform the transformation in place if + possible and return the number of valid bytes or zero for + failure. If the transformation cannot be done in place then + the filter should allocate a new buffer with + <code>malloc()</code> and assign it to <em>*buf</em>, + assigning the allocated size of that buffer to + <em>*buf_size</em>. The old buffer should be freed + by calling <code>free()</code>. + + <br><br> + </dd><dt><code>herr_t H5Zregister (H5Z_filter_t <em>filter_id</em>, + const char *<em>comment</em>, H5Z_func_t + <em>filter</em>)</code> + </dt><dd>The <em>filter</em> function is associated with a filter + number and a short ASCII comment which will be stored in the + hdf5 file if the filter is used as part of a permanent + pipeline during dataset creation. + </dd></dl> + + <h2>Predefined Filters</h2> + + <p>If <code>zlib</code> version 1.1.2 or later was found + during configuration then the library will define a filter whose + <code>H5Z_filter_t</code> number is + <code>H5Z_FILTER_DEFLATE</code>. Since this compression method + has the potential for generating compressed data which is larger + than the original, the <code>H5Z_FLAG_OPTIONAL</code> flag + should be turned on so such cases can be handled gracefully by + storing the original data instead of the compressed data. The + <em>cd_nvalues</em> should be one with <em>cd_value[0]</em> + being a compression aggression level between zero and nine, + inclusive (zero is the fastest compression while nine results in + the best compression ratio). + + </p><p>A convenience function for adding the + <code>H5Z_FILTER_DEFLATE</code> filter to a pipeline is: + + </p><dl> + <dt><code>herr_t H5Pset_deflate (hid_t <em>plist</em>, unsigned + <em>aggression</em>)</code> + </dt><dd>The deflate compression method is added to the end of the + permanent or transient filter pipeline depending on whether + <em>plist</em> is a dataset creation or dataset transfer + property list. The <em>aggression</em> is a number between + zero and nine (inclusive) to indicate the tradeoff between + speed and compression ratio (zero is fastest, nine is best + ratio). + </dd></dl> + + <p>Even if the <code>zlib</code> isn't detected during + configuration the application can define + <code>H5Z_FILTER_DEFLATE</code> as a permanent filter. If the + filter is marked as optional (as with + <code>H5Pset_deflate()</code>) then it will always fail and be + automatically removed from the pipeline. Applications that read + data will fail only if the data is actually compressed; they + won't fail if <code>H5Z_FILTER_DEFLATE</code> was part of the + permanent output pipeline but was automatically excluded because + it didn't exist when the data was written. + + </p><p><code>zlib</code> can be acquired from + <code><a href="http://www.cdrom.com/pub/infozip/zlib/"> + http://www.cdrom.com/pub/infozip/zlib/</a></code>. + + </p><h2>Example</h2> + + <p>This example shows how to define and register a simple filter + that adds a checksum capability to the data stream. + + </p><p>The function that acts as the filter always returns zero + (failure) if the <code>md5()</code> function was not detected at + configuration time (left as an exercise for the reader). + Otherwise the function is broken down to an input and output + half. The output half calculates a checksum, increases the size + of the output buffer if necessary, and appends the checksum to + the end of the buffer. The input half calculates the checksum + on the first part of the buffer and compares it to the checksum + already stored at the end of the buffer. If the two differ then + zero (failure) is returned, otherwise the buffer size is reduced + to exclude the checksum. + + </p> + <table> + <tbody><tr> + <td> + <p><code></code></p><pre><code> + size_t + md5_filter(unsigned int flags, size_t cd_nelmts, + const unsigned int cd_values[], size_t nbytes, + size_t *buf_size, void **buf) + { + #ifdef HAVE_MD5 + unsigned char cksum[16]; + + if (flags & H5Z_REVERSE) { + /* Input */ + assert(nbytes>=16); + md5(nbytes-16, *buf, cksum); + + /* Compare */ + if (memcmp(cksum, (char*)(*buf)+nbytes-16, 16)) { + return 0; /*fail*/ + } + + /* Strip off checksum */ + return nbytes-16; + + } else { + /* Output */ + md5(nbytes, *buf, cksum); + + /* Increase buffer size if necessary */ + if (nbytes+16>*buf_size) { + *buf_size = nbytes + 16; + *buf = realloc(*buf, *buf_size); + } + + /* Append checksum */ + memcpy((char*)(*buf)+nbytes, cksum, 16); + return nbytes+16; + } + #else + return 0; /*fail*/ + #endif + } + </code></pre> + </td> + </tr> + </tbody></table> + + <p>Once the filter function is defined it must be registered so + the HDF5 library knows about it. Since we're testing this + filter we choose one of the <code>H5Z_filter_t</code> numbers + from the reserved range. We'll randomly choose 305. + + </p><p> + </p> + <table> + <tbody><tr> + <td> + <p><code></code></p><pre><code> + #define FILTER_MD5 305 + herr_t status = H5Zregister(FILTER_MD5, "md5 checksum", md5_filter); + </code></pre> + </td> + </tr> + </tbody></table> + + <p>Now we can use the filter in a pipeline. We could have added + the filter to the pipeline before defining or registering the + filter as long as the filter was defined and registered by time + we tried to use it (if the filter is marked as optional then we + could have used it without defining it and the library would + have automatically removed it from the pipeline for each chunk + written before the filter was defined and registered). + + </p><p> + </p> + <table> + <tbody><tr> + <td> + <p><code></code></p><pre><code> + hid_t dcpl = H5Pcreate(H5P_DATASET_CREATE); + hsize_t chunk_size[3] = {10,10,10}; + H5Pset_chunk(dcpl, 3, chunk_size); + H5Pset_filter(dcpl, FILTER_MD5, 0, 0, NULL); + hid_t dset = H5Dcreate(file, "dset", H5T_NATIVE_DOUBLE, space, dcpl); + </code></pre> + </td> + </tr> + </tbody></table> + + <h2>6. Filter Diagnostics</h2> + + <p>If the library is compiled with debugging turned on for the H5Z + layer (usually as a result of <code>configure + --enable-debug=z</code>) then filter statistics are printed when + the application exits normally or the library is closed. The + statistics are written to the standard error stream and include + two lines for each filter that was used: one for input and one + for output. The following fields are displayed: + + </p><p> + </p> + <table> + <tbody><tr> + <th>Field Name</th> + <th>Description</th> + </tr> + + <tr valign="top"> + <td>Method</td> + <td>This is the name of the method as defined with + <code>H5Zregister()</code> with the characters + "< or ">" prepended to indicate + input or output.</td> + </tr> + + <tr valign="top"> + <td>Total</td> + <td>The total number of bytes processed by the filter + including errors. This is the maximum of the + <em>nbytes</em> argument or the return value. + </td></tr> + + <tr valign="top"> + <td>Errors</td> + <td>This field shows the number of bytes of the Total + column which can be attributed to errors.</td> + </tr> + + <tr valign="top"> + <td>User, System, Elapsed</td> + <td>These are the amount of user time, system time, and + elapsed time in seconds spent in the filter function. + Elapsed time is sensitive to system load. These times + may be zero on operating systems that don't support the + required operations.</td> + </tr> + + <tr valign="top"> + <td>Bandwidth</td> + <td>This is the filter bandwidth which is the total + number of bytes processed divided by elapsed time. + Since elapsed time is subject to system load the + bandwidth numbers cannot always be trusted. + Furthermore, the bandwidth includes bytes attributed to + errors which may significanly taint the value if the + function is able to detect errors without much + expense.</td> + </tr> + </tbody></table> + + <p> + </p> + <table> + <caption align="bottom"> + <b>Example: Filter Statistics</b> + </caption> + <tbody><tr> + <td> + <p><code></code></p><pre><code>H5Z: filter statistics accumulated ov= + er life of library: + Method Total Errors User System Elapsed Bandwidth + ------ ----- ------ ---- ------ ------- --------- + >deflate 160000 40000 0.62 0.74 1.33 117.5 kBs + <deflate 120000 0 0.11 0.00 0.12 1.000 MBs + </code></pre> + </td> + </tr> + </tbody></table> + + <hr> + + + <p><a name="fn1">Footnote 1:</a> Dataset chunks can be compressed + through the use of filters. Developers should be aware that + reading and rewriting compressed chunked data can result in holes + in an HDF5 file. In time, enough such holes can increase the + file size enough to impair application or library performance + when working with that file. See + <a href="https://support.hdfgroup.org/HDF5/doc1.6/Performance.html#Freespace"> + Freespace Management</a> + in the chapter + <a href="https://support.hdfgroup.org/HDF5/doc1.6/Performance.html"> + Performance Analysis and Issues</a>.</p> +</html> diff --git a/doxygen/examples/H5.format.1.0.html b/doxygen/examples/H5.format.1.0.html index 2d3ffbe..d2b6610 100644 --- a/doxygen/examples/H5.format.1.0.html +++ b/doxygen/examples/H5.format.1.0.html @@ -10,12 +10,12 @@ <table border=0 width=90%> <tr> <td valign=top> - <ol type=I> + <ol type="I"> <li><a href="#Intro">Introduction</a> <li><a href="#BootBlock">Disk Format Level 0 - File Signature and Super Block</a> <li><a href="#Group">Disk Format Level 1 - File Infrastructure</a> <font size=-2> - <ol type=A> + <ol type="A"> <li><a href="#Btrees">Disk Format Level 1A - B-link Trees and B-tree Nodes</a> <li><a href="#SymbolTable">Disk Format Level 1B - Group</a> <li><a href="#SymbolTableEntry">Disk Format Level 1C - Group Entry</a> @@ -26,9 +26,9 @@ </font> <li><a href="#DataObject">Disk Format Level 2 - Data Objects</a> <font size=-2> - <ol type=A> + <ol type="A"> <li><a href="#ObjectHeader">Disk Format Level 2a - Data Object Headers</a> - <ol type=1> + <ol type="1"> <li><a href="#NILMessage">Name: NIL</a> <!-- 0x0000 --> <li><a href="#SimpleDataSpace">Name: Simple Dataspace</a> <!-- 0x0001 --> <!-- @@ -41,13 +41,13 @@ </font> </ol> </td><td> </td><td valign=top> - <ol type=I> + <ol type="I" start="4"> <li><a href="#DataObject">Disk Format Level 2 - Data Objects</a> <font size=-2><i>(Continued)</i> - <ol type=A> + <ol type="A"> <li><a href="#ObjectHeader">Disk Format Level 2a - Data Object Headers</a><i>(Continued)</i> - <ol type=1> + <ol type="1" start="6"> <li><a href="#CompactDataStorageMessage">Name: Data Storage - Compact</a> <!-- 0x0006 --> <li><a href="#ExternalFileListMessage">Name: Data Storage - External Data Files</a> <!-- 0x0007 --> <li><a href="#LayoutMessage">Name: Data Storage - Layout</a> <!-- 0x0008 --> @@ -495,7 +495,7 @@ Elena> "Free-space object" <td>End of File Address</td> <td>This is the relative file address of the first byte past the end of all HDF5 data. It is used to determine whether a - file has been accidently truncated and as an address where + file has been accidentally truncated and as an address where file data allocation can occur if the free list is not used.</td> </tr> @@ -2414,7 +2414,7 @@ Elena> "Free-space object" <td><b>Normalization.</b> The value can be 0 if there is no normalization, 1 if the most significant bit of the mantissa is always set (except for 0.0), and 2 if the most - signficant bit of the mantissa is not stored but is + significant bit of the mantissa is not stored but is implied to be set. The value 3 is reserved and will not appear in this field.</td> </tr> @@ -2916,7 +2916,7 @@ Elena> "Free-space object" <p>The fill value message stores a single data point value which is returned to the application when an uninitialized data point - is read from the dataset. The fill value is interpretted with + is read from the dataset. The fill value is interpreted with the same datatype as the dataset. If no fill value message is present then a fill value of all zero is assumed. @@ -3327,7 +3327,7 @@ Elena> "Free-space object" <p> <center> - <table border align=center cellpadding=4 witdh="80%"> + <table border align=center cellpadding=4 width="80%"> <caption align=top> <b>Filter Pipeline Message</b> </caption> @@ -3386,7 +3386,7 @@ Elena> "Free-space object" <p> <center> - <table border align=center cellpadding=4 witdh="80%"> + <table border align=center cellpadding=4 width="80%"> <caption align=top> <b>Filter Pipeline Message</b> </caption> diff --git a/doxygen/examples/H5.format.1.1.html b/doxygen/examples/H5.format.1.1.html index ebbbe8e..b91ac90 100644 --- a/doxygen/examples/H5.format.1.1.html +++ b/doxygen/examples/H5.format.1.1.html @@ -36,18 +36,18 @@ TABLE.list TD { border:none; } <table border=0 width=90%> <tr> <td valign=top> - <ol type=I> + <ol type="I"> <li><a href="#Intro">Introduction</a> <li><a href="#FileMetaData">Disk Format Level 0 - File Metadata</a> <font size=-2> - <ol type=A> + <ol type="A"> <li><a href="#SuperBlock">Disk Format Level 0A - File Signature and Super Block</a> <li><a href="#DriverInfo">Disk Format Level 0B - File Driver Info</a> </ol> </font> <li><a href="#FileInfra">Disk Format Level 1 - File Infrastructure</a> <font size=-2> - <ol type=A> + <ol type="A"> <li><a href="#Btrees">Disk Format Level 1A - B-link Trees and B-tree Nodes</a> <li><a href="#SymbolTable">Disk Format Level 1B - Group</a> <li><a href="#SymbolTableEntry">Disk Format Level 1C - Group Entry</a> @@ -58,9 +58,9 @@ TABLE.list TD { border:none; } </font> <li><a href="#DataObject">Disk Format Level 2 - Data Objects</a> <font size=-2> - <ol type=A> + <ol type="A"> <li><a href="#ObjectHeader">Disk Format Level 2a - Data Object Headers</a> - <ol type=1> + <ol type="1"> <li><a href="#NILMessage">Name: NIL</a> <!-- 0x0000 --> <li><a href="#SimpleDataSpace">Name: Simple Dataspace</a> <!-- 0x0001 --> <!-- <li><a href="#DataSpaceMessage">Name: Complex Dataspace</a> --> <!-- 0x0002 --> @@ -73,13 +73,13 @@ TABLE.list TD { border:none; } </font> </ol> </td><td> </td><td valign=top> - <ol type=I start=4> + <ol type="I" start="4"> <li><a href="#DataObject">Disk Format Level 2 - Data Objects</a> <font size=-2><i>(Continued)</i> <ol type=A> <li><a href="#ObjectHeader">Disk Format Level 2a - Data Object Headers</a><i>(Continued)</i> - <ol type=1 start=6> + <ol type="1" start="7"> <!-- <li><a href="#CompactDataStorageMessage">Name: Data Storage - Compact</a> --> <!-- 0x0006 --> <li><a href="#ReservedMessage_0006">Name: Reserved - not assigned yet</a> <!-- 0x0006 --> <li><a href="#ExternalFileListMessage">Name: Data Storage - External Data Files</a> <!-- 0x0007 --> @@ -616,7 +616,7 @@ TABLE.list TD { border:none; } <td> <P>This is the absolute file address of the first byte past the end of all HDF5 data. It is used to determine whether a - file has been accidently truncated and as an address where + file has been accidentally truncated and as an address where file data allocation can occur if space from the free list is not used. </P> @@ -3184,7 +3184,7 @@ TABLE.list TD { border:none; } <td><b>Normalization.</b> The value can be 0 if there is no normalization, 1 if the most significant bit of the mantissa is always set (except for 0.0), and 2 if the most - signficant bit of the mantissa is not stored but is + significant bit of the mantissa is not stored but is implied to be set. The value 3 is reserved and will not appear in this field.</td> </tr> diff --git a/doxygen/examples/H5.format.2.0.html b/doxygen/examples/H5.format.2.0.html index 3653489..4a5fe37 100644 --- a/doxygen/examples/H5.format.2.0.html +++ b/doxygen/examples/H5.format.2.0.html @@ -821,7 +821,7 @@ II.A. Disk Format: Level 0A - Format Signature and Superblock</a></h3> <td> <p>This is the absolute file address of the first byte past the end of all HDF5 data. It is used to determine whether a - file has been accidently truncated and as an address where + file has been accidentally truncated and as an address where file data allocation can occur if space from the free list is not used. </p> @@ -4910,7 +4910,7 @@ III.F. Disk Format: Level 1F - Fractal Heap</a></h3> enough to store objects greater than 16 bytes or not. If the heap ID length is 18 bytes or smaller, the ‘normal’ tiny heap ID form is used. If the heap ID length is greater than 18 bytes in - length, the “extented” form is used. See format description below + length, the “extended” form is used. See format description below for both sub-types. </p> </td> @@ -7884,7 +7884,7 @@ IV.A.2. Disk Format: Level 2A2 - Data Object Header Messages</a></h3> <tr> <td align="center"><code>3</code></td> - <td>Message stored is not shared, but is sharable. + <td>Message stored is not shared, but is shareable. </td> </tr> diff --git a/doxygen/examples/H5.format.html b/doxygen/examples/H5.format.html index e16805f..cbcb387 100644 --- a/doxygen/examples/H5.format.html +++ b/doxygen/examples/H5.format.html @@ -936,7 +936,7 @@ <td> <p>This is the absolute file address of the first byte past the end of all HDF5 data. It is used to determine whether a - file has been accidently truncated and as an address where + file has been accidentally truncated and as an address where file data allocation can occur if space from the free list is not used. </p> @@ -8691,7 +8691,7 @@ three rows are needed. <tr> <td align="center"><code>3</code></td> - <td>Message stored is not shared, but is sharable. + <td>Message stored is not shared, but is shareable. </td> </tr> @@ -20202,7 +20202,7 @@ disk address for the chunk.</p> </tr> <tr> - <td><p>Length fo External File Name</p></td> + <td><p>Length of External File Name</p></td> <td><p>This is the length for the external file name. <p>This field exists if bit 0 of <em>flags</em> is set.</p> </p> diff --git a/doxygen/examples/IOFlow.html b/doxygen/examples/IOFlow.html new file mode 100644 index 0000000..6b2c27e --- /dev/null +++ b/doxygen/examples/IOFlow.html @@ -0,0 +1,137 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<!-- saved from url=(0064)https://gamma.hdfgroup.org/papers/HISS/030821.IOFlow/IOFlow.html --> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> + <title>HDF5 Raw I/O Flow Notes</title> + + <meta name="author" content="Quincey Koziol"> +</head> + +<body text="#000000" bgcolor="#FFFFFF"> + +<style type="text/css"> +OL.loweralpha { list-style-type: lower-alpha } +OL.upperroman { list-style-type: upper-roman } +</style> + +<center><h1>HDF5 Raw I/O Flow Notes</h1></center> +<center><h3>Quincey Koziol<br> + koziol@ncsa.uiuc.edu<br> + August 20, 2003 +</h3></center> + +<ol class="upperroman"> + +<li><h3><u>Document's Audience:</u></h3> + +<ul> + <li>Current H5 library designers and knowledgable external developers.</li> +</ul> + +</li><li><h3><u>Background Reading:</u></h3> + +</li><li><h3><u>Introduction:</u></h3> + +<dl> + <dt><strong>What is this document about?</strong></dt> + <dd>This document attempts to supplement the flow charts describing + the flow of control for raw data I/O in the library. + </dd> <br> +</dl> + +</li><li><h3><u>Figures:</u></h3> +<p>The following figures provide the main information:</p> + <table> + <tr><td><img src="IOFlow.gif" alt="High-Level View of Writing Raw Data" style="height:50%;"></td></tr> + <tr><td><img src="IOFlow2.gif" alt="Perform Serial or Parallel I/O" style="height:50%;"></td></tr> + <tr><td><img src="IOFlow3.gif" alt="Gather/Convert/Scatter" style="height:50%;"></td></tr> + </table> + +</li><li><h3><u>Notes From Accompanying Figures:</u></h3> + +<p>This section provides notes to augment the information in the accompanying + figures. +</p> + +<ol> + <li><b>Validate Parameters</b> - Resolve any H5S_ALL parameters + for dataspace selections to actual dataspaces, allocate + conversion buffers, etc. + </li> + + <li><b>Space Allocated in File?</b> - Space may not have been allocated + in the file to store the dataset data, if "late allocation" was chosen + for the allocation time when the dataset was created. + </li> + + <li><b>Allocate & Fill Space</b> - These operations allocate both contiguous + and chunked dataset's space in the file. The chunked dataset space + allocation iterates through all the chunks in the file and allocates + both the B-tree information and the raw data in the file. Because of + the way filters work, fill-values are written out for chunked datasets + as they are allocated, instead of as a separate step. + In parallel + I/O, the chunked dataset allocation can potentially be time-consuming, + since all the raw data in the dataset is allocated from one process. + </li> + + <li><b>Datatype Conversion Needed?</b> - This currently is the deciding + factor between doing "direct I/O" (in serial or parallel) and needing + to perform gather/convert/scatter operations. I believe that MPI + is capable of performing a limited range of type conversions and if so, + we should add support to detect when they can be used. This will + allow more I/O operations to be performed collectively. + </li> + + <li><b>Collective I/O Requested/Allowed?</b> - A user has to both request + that collective I/O occur and also their I/O operation must meet the + requirements that the library sets for supporting collective parallel + I/O: + <ul> + <li>The dataspace must be scalar or simple (which is a no-op really, + since we don't support "complex" dataspaces in the library + currently). + </li> + <li>The selection must be regular. "all" selections + and hyperslab selections that were + made with only one call to H5Sselect_hyperslab() (i.e. not a + hyperslab selection that has been aggregated over multiple + selection calls) are regular. Supporting point and + irregular hyperslab selections are on the "to do" list. + </li> + <li>The dataset must be stored contiguously on disk (as shown in the + figure also). Supporting chunked dataset storage is also + on the "to do" list. + </li> + </ul> + </li> + + <li><b>Build "chunk map"</b> - This step still has some scalability issues + as it creates a data structure that is proportional to the number of + chunks which will be written to, which could potentially be very large. + Building the "chunk map" information incrementally is on the "to do" + list also. + </li> + + <li><b>Perform Chunked I/O</b> - As the figure shows, there is no support + for collective parallel I/O on chunked datasets currently. As noted + earlier, this is on the "to do" list. + </li> + + <li><b>Perform "Direct" Serial I/O</b> - "Direct" serial I/O writes data + from the application's buffer, without any intervening buffer or memory + copies. For maximum efficiency and performance, the elements in the + selections should be adjoining. + </li> + + <li><b>Perform Collective Parallel I/O</b> - This step also writes data + directly from an application buffer, but additionally uses collective + MPI I/O operations to combine the data from each process in the parallel + application in an efficient manner. + </li> +</ol> + +</li></ol> + + + +</body></html> diff --git a/doxygen/examples/ThreadSafeLibrary.html b/doxygen/examples/ThreadSafeLibrary.html index 8daf386..ebb193e 100644 --- a/doxygen/examples/ThreadSafeLibrary.html +++ b/doxygen/examples/ThreadSafeLibrary.html @@ -165,7 +165,7 @@ The structure is defined in <code>H5private.h</code> as: <blockquote> <pre> - /* cancelability structure */ + /* cancellability structure */ typedef struct H5_cancel_struct { int previous_state; unsigned int cancel_count; diff --git a/doxygen/examples/VFL.html b/doxygen/examples/VFL.html index 9776f96..624d942 100644 --- a/doxygen/examples/VFL.html +++ b/doxygen/examples/VFL.html @@ -306,7 +306,7 @@ H5Dread(dataset, type, mspace, fspace, buffer, dxpl); </PRE> <P> -The transfer propery list can be queried in a manner similar to the file +The transfer property list can be queried in a manner similar to the file access property list: the driver provides a function (or functions) to return various information about the transfer property list: @@ -1210,7 +1210,7 @@ Flush all data for file <VAR>file</VAR> to storage. </P> <P> <STRONG>Example:</STRONG> The sec2 driver doesn't cache any data but it also doesn't -extend the Unix file as agressively as it should. Therefore, when finalizing a +extend the Unix file as aggressively as it should. Therefore, when finalizing a file it should write a zero to the last byte of the allocated region so that when reopening the file later the EOF marker will be at least as large as the EOA marker saved in the superblock (otherwise HDF5 will refuse to open the diff --git a/doxygen/hdf5_navtree_hacks.js b/doxygen/hdf5_navtree_hacks.js index 942970c..dda8984 100644 --- a/doxygen/hdf5_navtree_hacks.js +++ b/doxygen/hdf5_navtree_hacks.js @@ -223,7 +223,7 @@ $(document).ready(function() { (function (){ // wait until the first "selected" element has been created try { - // this line will triger an exception if there is no #selected element, i.e., before the tree structure is complete. + // this line will trigger an exception if there is no #selected element, i.e., before the tree structure is complete. document.getElementById("selected").className = "item selected"; // ok, the default tree has been created, we can keep going... diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml index fc20aa1..24642b5 100644 --- a/doxygen/hdf5doxy_layout.xml +++ b/doxygen/hdf5doxy_layout.xml @@ -7,11 +7,12 @@ <tab type="user" url="@ref Cookbook" title="Cookbook" /> <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+User+Guides" title="User Guides" /> <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+Application+Developer%27s+Guide" title="Application Developer's Guide" /> - <tab type="user" url="https://portal.hdfgroup.org/display/HDF5/HDF5+Glossary" title="Glossary" /> + <tab type="user" url="@ref GLS" title="Glossary" /> <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 FTS" title="Full-Text Search" /> <tab type="user" url="@ref About" title="About" /> </navindex> diff --git a/doxygen/img/HDF5.png b/doxygen/img/HDF5.png Binary files differnew file mode 100644 index 0000000..0458fa8 --- /dev/null +++ b/doxygen/img/HDF5.png diff --git a/hl/src/H5LTpublic.h b/hl/src/H5LTpublic.h index 2af9b07..47bb334 100644 --- a/hl/src/H5LTpublic.h +++ b/hl/src/H5LTpublic.h @@ -19,7 +19,7 @@ #define H5LT_FILE_IMAGE_DONT_COPY 0x0002 /* The HDF5 lib won't copy */ /* user supplied image buffer. The same image is open with the core driver. */ #define H5LT_FILE_IMAGE_DONT_RELEASE 0x0004 /* The HDF5 lib won't */ -/* deallocate user supplied image buffer. The user application is reponsible */ +/* deallocate user supplied image buffer. The user application is responsible */ /* for doing so. */ #define H5LT_FILE_IMAGE_ALL 0x0007 diff --git a/src/H5ACpkg.h b/src/H5ACpkg.h index 7da46a0..5289e3a 100644 --- a/src/H5ACpkg.h +++ b/src/H5ACpkg.h @@ -346,7 +346,7 @@ H5FL_EXTERN(H5AC_aux_t); * * The following field supports the metadata cache image feature. * - * p0_image_len: unsiged integer containing the length of the metadata cache + * p0_image_len: unsigned integer containing the length of the metadata cache * image constructed by MPI process 0. This field should be 0 * if the value is unknown, or if cache image is not enabled. * diff --git a/src/H5ACpublic.h b/src/H5ACpublic.h index f8f4f28..c853794 100644 --- a/src/H5ACpublic.h +++ b/src/H5ACpublic.h @@ -76,7 +76,7 @@ extern "C" { * * *** DEPRECATED *** Use H5Fstart/stop logging functions instead * - * The trace file is a debuging feature that allow the capture of + * The trace file is a debugging feature that allow the capture of * top level metadata cache requests for purposes of debugging and/or * optimization. This field should normally be set to FALSE, as * trace file collection imposes considerable overhead. @@ -123,7 +123,7 @@ extern "C" { * H5C_incr__off ) && ( decr_mode == H5C_decr__off )). There * is no logical reason why this should be so, but it simplifies * implementation and testing, and I can't think of any reason - * why it would be desireable. If you can think of one, I'll + * why it would be desirable. If you can think of one, I'll * revisit the issue. * * set_initial_size: Boolean flag indicating whether the size of the @@ -396,7 +396,7 @@ extern "C" { * * When the sync point is reached (or when there is a user generated * flush), process zero flushes sufficient entries to bring it into - * complience with its min clean size (or flushes all dirty entries in + * compliance with its min clean size (or flushes all dirty entries in * the case of a user generated flush), broad casts the list of * entries just cleaned to all the other processes, and then exits * the sync point. @@ -576,7 +576,7 @@ typedef struct H5AC_cache_config_t { size_t min_size; /**< Lower bound (in bytes) on the range of values that the - * adaptive cache resize code can select as the mininum cache * size. */ + * adaptive cache resize code can select as the minimum cache * size. */ long int epoch_length; /**< Number of cache accesses between runs of the adaptive cache resize @@ -708,13 +708,13 @@ typedef struct H5AC_cache_config_t { * of bytes of dirty metadata created since the last synchronization exceeds * this limit.\n This field only applies to the parallel case. While it is * ignored elsewhere, it can still draw a value out of bounds error.\n It - * must be consistant across all caches on any given file.\n By default, + * must be consistent across all caches on any given file.\n By default, * this field is set to 256 KB. It shouldn't be more than half the current * max cache size times the min clean fraction. */ int metadata_write_strategy; /**< Desired metadata write strategy. The valid values for this field - * are:\n #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: Specifies tha only + * are:\n #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: Specifies the only * process zero is allowed to write dirty metadata to disk.\n * #H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED: Specifies that process zero * still makes the decisions as to what entries should be flushed, but the diff --git a/src/H5Apublic.h b/src/H5Apublic.h index 410eb1e..fd6b61e 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -583,7 +583,7 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); * For example, if \p idx_type, \p order, and \p idx are set to * #H5_INDEX_NAME, #H5_ITER_INC, and 5, respectively, the attribute * in question is the fifth attribute from the beginning of the - * alpha-numeric index of attribute names. If \p order were set to + * alphanumeric index of attribute names. If \p order were set to * #H5_ITER_DEC, it would be the fifth attribute from the end of * the index. * @@ -638,7 +638,7 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord * For example, if \p idx_type, \p order, and \p idx are set to * #H5_INDEX_NAME, #H5_ITER_INC, and 5, respectively, the attribute * in question is the fifth attribute from the beginning of the - * alpha-numeric index of attribute names. If \p order were set to + * alphanumeric index of attribute names. If \p order were set to * #H5_ITER_DEC, it would be the fifth attribute from the end of * the index. * diff --git a/src/H5Cpkg.h b/src/H5Cpkg.h index 98ae523..75b39d1 100644 --- a/src/H5Cpkg.h +++ b/src/H5Cpkg.h @@ -1011,7 +1011,7 @@ if ( ( (cache_ptr) == NULL ) || \ ( H5C__HASH_FCN((entry_ptr)->addr) >= H5C__HASH_TABLE_LEN ) || \ ( (cache_ptr)->index_size != \ ((cache_ptr)->clean_index_size + \ - (cache_ptr)->dirty_index_size) ) || \ + (cache_ptr)->dirty_index_size) ) || \ ( (cache_ptr)->index_size < ((cache_ptr)->clean_index_size) ) || \ ( (cache_ptr)->index_size < ((cache_ptr)->dirty_index_size) ) || \ ( (entry_ptr)->ring <= H5C_RING_UNDEFINED ) || \ @@ -1034,7 +1034,7 @@ if ( ( (cache_ptr) == NULL ) || \ ( (cache_ptr)->magic != H5C__H5C_T_MAGIC ) || \ ( (cache_ptr)->index_size != \ ((cache_ptr)->clean_index_size + \ - (cache_ptr)->dirty_index_size) ) || \ + (cache_ptr)->dirty_index_size) ) || \ ( (cache_ptr)->index_size < ((cache_ptr)->clean_index_size) ) || \ ( (cache_ptr)->index_size < ((cache_ptr)->dirty_index_size) ) || \ ( (cache_ptr)->index_ring_len[(entry_ptr)->ring] == 0 ) || \ @@ -1071,7 +1071,7 @@ if ( ( (cache_ptr) == NULL ) || \ ( (entry_ptr)->ht_prev != NULL ) ) || \ ( (cache_ptr)->index_size != \ ((cache_ptr)->clean_index_size + \ - (cache_ptr)->dirty_index_size) ) || \ + (cache_ptr)->dirty_index_size) ) || \ ( (cache_ptr)->index_size < ((cache_ptr)->clean_index_size) ) || \ ( (cache_ptr)->index_size < ((cache_ptr)->dirty_index_size) ) || \ ( (entry_ptr)->ring <= H5C_RING_UNDEFINED ) || \ @@ -1102,7 +1102,7 @@ if ( ( (cache_ptr) == NULL ) || \ ( (entry_ptr)->ht_prev != NULL ) || \ ( (cache_ptr)->index_size != \ ((cache_ptr)->clean_index_size + \ - (cache_ptr)->dirty_index_size) ) || \ + (cache_ptr)->dirty_index_size) ) || \ ( (cache_ptr)->index_size < ((cache_ptr)->clean_index_size) ) || \ ( (cache_ptr)->index_size < ((cache_ptr)->dirty_index_size) ) || \ ( (cache_ptr)->index_ring_len[(entry_ptr)->ring] > \ @@ -1161,7 +1161,7 @@ if ( ( (cache_ptr) == NULL ) || \ } #define H5C__PRE_HT_ENTRY_SIZE_CHANGE_SC(cache_ptr, old_size, new_size, \ - entry_ptr, was_clean) \ + entry_ptr, was_clean) \ if ( ( (cache_ptr) == NULL ) || \ ( (cache_ptr)->index_len <= 0 ) || \ ( (cache_ptr)->index_size <= 0 ) || \ @@ -1175,9 +1175,9 @@ if ( ( (cache_ptr) == NULL ) || \ ( (cache_ptr)->index_size < ((cache_ptr)->clean_index_size) ) || \ ( (cache_ptr)->index_size < ((cache_ptr)->dirty_index_size) ) || \ ( ( !( was_clean ) || \ - ( (cache_ptr)->clean_index_size < (old_size) ) ) && \ - ( ( (was_clean) ) || \ - ( (cache_ptr)->dirty_index_size < (old_size) ) ) ) || \ + ( (cache_ptr)->clean_index_size < (old_size) ) ) && \ + ( ( (was_clean) ) || \ + ( (cache_ptr)->dirty_index_size < (old_size) ) ) ) || \ ( (entry_ptr) == NULL ) || \ ( (entry_ptr)->ring <= H5C_RING_UNDEFINED ) || \ ( (entry_ptr)->ring >= H5C_RING_NTYPES ) || \ @@ -1196,20 +1196,20 @@ if ( ( (cache_ptr) == NULL ) || \ } #define H5C__POST_HT_ENTRY_SIZE_CHANGE_SC(cache_ptr, old_size, new_size, \ - entry_ptr) \ + entry_ptr) \ if ( ( (cache_ptr) == NULL ) || \ ( (cache_ptr)->index_len <= 0 ) || \ ( (cache_ptr)->index_size <= 0 ) || \ ( (new_size) > (cache_ptr)->index_size ) || \ ( (cache_ptr)->index_size != \ - ((cache_ptr)->clean_index_size + \ + ((cache_ptr)->clean_index_size + \ (cache_ptr)->dirty_index_size) ) || \ ( (cache_ptr)->index_size < ((cache_ptr)->clean_index_size) ) || \ ( (cache_ptr)->index_size < ((cache_ptr)->dirty_index_size) ) || \ ( ( !((entry_ptr)->is_dirty ) || \ - ( (cache_ptr)->dirty_index_size < (new_size) ) ) && \ - ( ( ((entry_ptr)->is_dirty) ) || \ - ( (cache_ptr)->clean_index_size < (new_size) ) ) ) || \ + ( (cache_ptr)->dirty_index_size < (new_size) ) ) && \ + ( ( ((entry_ptr)->is_dirty) ) || \ + ( (cache_ptr)->clean_index_size < (new_size) ) ) ) || \ ( ( (cache_ptr)->index_len == 1 ) && \ ( (cache_ptr)->index_size != (new_size) ) ) || \ ( (cache_ptr)->index_ring_len[(entry_ptr)->ring] > \ @@ -1465,10 +1465,10 @@ if ( ( (cache_ptr)->index_size != \ H5C__PRE_HT_UPDATE_FOR_ENTRY_CLEAN_SC(cache_ptr, entry_ptr); \ (cache_ptr)->dirty_index_size -= (entry_ptr)->size; \ ((cache_ptr)->dirty_index_ring_size[entry_ptr->ring]) \ - -= (entry_ptr)->size; \ + -= (entry_ptr)->size; \ (cache_ptr)->clean_index_size += (entry_ptr)->size; \ ((cache_ptr)->clean_index_ring_size[entry_ptr->ring]) \ - += (entry_ptr)->size; \ + += (entry_ptr)->size; \ H5C__POST_HT_UPDATE_FOR_ENTRY_CLEAN_SC(cache_ptr, entry_ptr); \ } @@ -1477,18 +1477,18 @@ if ( ( (cache_ptr)->index_size != \ H5C__PRE_HT_UPDATE_FOR_ENTRY_DIRTY_SC(cache_ptr, entry_ptr); \ (cache_ptr)->clean_index_size -= (entry_ptr)->size; \ ((cache_ptr)->clean_index_ring_size[entry_ptr->ring]) \ - -= (entry_ptr)->size; \ + -= (entry_ptr)->size; \ (cache_ptr)->dirty_index_size += (entry_ptr)->size; \ ((cache_ptr)->dirty_index_ring_size[entry_ptr->ring]) \ - += (entry_ptr)->size; \ + += (entry_ptr)->size; \ H5C__POST_HT_UPDATE_FOR_ENTRY_DIRTY_SC(cache_ptr, entry_ptr); \ } #define H5C__UPDATE_INDEX_FOR_SIZE_CHANGE(cache_ptr, old_size, new_size, \ - entry_ptr, was_clean) \ + entry_ptr, was_clean) \ { \ H5C__PRE_HT_ENTRY_SIZE_CHANGE_SC(cache_ptr, old_size, new_size, \ - entry_ptr, was_clean) \ + entry_ptr, was_clean) \ (cache_ptr)->index_size -= (old_size); \ (cache_ptr)->index_size += (new_size); \ ((cache_ptr)->index_ring_size[entry_ptr->ring]) -= (old_size); \ @@ -1497,14 +1497,14 @@ if ( ( (cache_ptr)->index_size != \ (cache_ptr)->clean_index_size -= (old_size); \ ((cache_ptr)->clean_index_ring_size[entry_ptr->ring])-= (old_size); \ } else { \ - (cache_ptr)->dirty_index_size -= (old_size); \ + (cache_ptr)->dirty_index_size -= (old_size); \ ((cache_ptr)->dirty_index_ring_size[entry_ptr->ring])-= (old_size); \ } \ if((entry_ptr)->is_dirty) { \ (cache_ptr)->dirty_index_size += (new_size); \ ((cache_ptr)->dirty_index_ring_size[entry_ptr->ring])+= (new_size); \ } else { \ - (cache_ptr)->clean_index_size += (new_size); \ + (cache_ptr)->clean_index_size += (new_size); \ ((cache_ptr)->clean_index_ring_size[entry_ptr->ring])+= (new_size); \ } \ H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->il_len, \ @@ -1597,7 +1597,7 @@ if ( ( (cache_ptr)->index_size != \ * * H5C_DO_SLIST_SANITY_CHECKS * - * can be selected independantly. This is easy to miss as the + * can be selected independently. This is easy to miss as the * two #defines are easy to confuse. */ @@ -1791,7 +1791,7 @@ if ( ( (cache_ptr)->index_size != \ } else { /* slist disabled */ \ \ HDassert( (cache_ptr)->slist_len == 0 ); \ - HDassert( (cache_ptr)->slist_size == 0 ); \ + HDassert( (cache_ptr)->slist_size == 0 ); \ } \ } /* H5C__REMOVE_ENTRY_FROM_SLIST */ @@ -2033,16 +2033,16 @@ if ( ( (cache_ptr)->index_size != \ /* modified LRU specific code */ \ \ /* remove the entry from the LRU list, and re-insert it at the head.\ - */ \ + */ \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* Use the dirty flag to infer whether the entry is on the clean or \ @@ -2096,16 +2096,16 @@ if ( ( (cache_ptr)->index_size != \ /* modified LRU specific code */ \ \ /* remove the entry from the LRU list, and re-insert it at the head \ - */ \ + */ \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* End modified LRU specific code. */ \ @@ -2288,28 +2288,28 @@ if ( ( (cache_ptr)->index_size != \ /* modified LRU specific code */ \ \ /* remove the entry from the LRU list, and re-insert it at the \ - * head. \ - */ \ + * head. \ + */ \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* since the entry is being flushed or cleared, one would think \ - * that it must be dirty -- but that need not be the case. Use the \ - * dirty flag to infer whether the entry is on the clean or dirty \ - * LRU list, and remove it. Then insert it at the head of the \ - * clean LRU list. \ + * that it must be dirty -- but that need not be the case. Use the \ + * dirty flag to infer whether the entry is on the clean or dirty \ + * LRU list, and remove it. Then insert it at the head of the \ + * clean LRU list. \ * \ * The function presumes that a dirty entry will be either cleared \ - * or flushed shortly, so it is OK if we put a dirty entry on the \ - * clean LRU list. \ + * or flushed shortly, so it is OK if we put a dirty entry on the \ + * clean LRU list. \ */ \ \ if ( (entry_ptr)->is_dirty ) { \ @@ -2350,17 +2350,17 @@ if ( ( (cache_ptr)->index_size != \ /* modified LRU specific code */ \ \ /* remove the entry from the LRU list, and re-insert it at the \ - * head. \ - */ \ + * head. \ + */ \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* End modified LRU specific code. */ \ @@ -2424,7 +2424,7 @@ if ( ( (cache_ptr)->index_size != \ \ H5C__DLL_APPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* insert the entry at the tail of the clean or dirty LRU list as \ @@ -2465,7 +2465,7 @@ if ( ( (cache_ptr)->index_size != \ (cache_ptr)->pel_tail_ptr, \ (cache_ptr)->pel_len, \ (cache_ptr)->pel_size, (fail_val)) \ - \ + \ } else { \ \ /* modified LRU specific code */ \ @@ -2474,7 +2474,7 @@ if ( ( (cache_ptr)->index_size != \ \ H5C__DLL_APPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* End modified LRU specific code. */ \ @@ -2558,7 +2558,7 @@ if ( ( (cache_ptr)->index_size != \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* insert the entry at the head of the clean or dirty LRU list as \ @@ -2599,7 +2599,7 @@ if ( ( (cache_ptr)->index_size != \ (cache_ptr)->pel_tail_ptr, \ (cache_ptr)->pel_len, \ (cache_ptr)->pel_size, (fail_val)) \ - \ + \ } else { \ \ /* modified LRU specific code */ \ @@ -2608,7 +2608,7 @@ if ( ( (cache_ptr)->index_size != \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* End modified LRU specific code. */ \ @@ -2677,12 +2677,12 @@ if ( ( (cache_ptr)->index_size != \ HDassert( !((entry_ptr)->is_read_only) ); \ HDassert( ((entry_ptr)->ro_ref_count) == 0 ); \ HDassert( (entry_ptr)->size > 0 ); \ - \ + \ if ( (entry_ptr)->is_pinned ) { \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->pel_head_ptr, \ - (cache_ptr)->pel_tail_ptr, \ - (cache_ptr)->pel_len, \ + (cache_ptr)->pel_tail_ptr, \ + (cache_ptr)->pel_len, \ (cache_ptr)->pel_size, (fail_val)) \ \ } else { \ @@ -2693,7 +2693,7 @@ if ( ( (cache_ptr)->index_size != \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* Similarly, remove the entry from the clean or dirty LRU list \ @@ -2739,12 +2739,12 @@ if ( ( (cache_ptr)->index_size != \ HDassert( !((entry_ptr)->is_read_only) ); \ HDassert( ((entry_ptr)->ro_ref_count) == 0 ); \ HDassert( (entry_ptr)->size > 0 ); \ - \ + \ if ( (entry_ptr)->is_pinned ) { \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->pel_head_ptr, \ - (cache_ptr)->pel_tail_ptr, \ - (cache_ptr)->pel_len, \ + (cache_ptr)->pel_tail_ptr, \ + (cache_ptr)->pel_len, \ (cache_ptr)->pel_size, (fail_val)) \ \ } else { \ @@ -2755,7 +2755,7 @@ if ( ( (cache_ptr)->index_size != \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* End modified LRU specific code. */ \ @@ -2804,21 +2804,21 @@ if ( ( (cache_ptr)->index_size != \ HDassert( ((entry_ptr)->ro_ref_count) == 0 ); \ HDassert( (entry_ptr)->size > 0 ); \ \ - if ( ! ( (entry_ptr)->is_pinned ) && ! ( (entry_ptr->is_protected ) ) ) { \ - \ + if ( ! ( (entry_ptr)->is_pinned ) && ! ( (entry_ptr->is_protected ) ) ) {\ + \ /* modified LRU specific code */ \ \ /* remove the entry from the LRU list, and re-insert it at the head. \ - */ \ + */ \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* remove the entry from either the clean or dirty LUR list as \ @@ -2827,7 +2827,7 @@ if ( ( (cache_ptr)->index_size != \ if ( was_dirty ) { \ \ H5C__AUX_DLL_REMOVE((entry_ptr), \ - (cache_ptr)->dLRU_head_ptr, \ + (cache_ptr)->dLRU_head_ptr, \ (cache_ptr)->dLRU_tail_ptr, \ (cache_ptr)->dLRU_list_len, \ (cache_ptr)->dLRU_list_size, \ @@ -2836,34 +2836,34 @@ if ( ( (cache_ptr)->index_size != \ } else { \ \ H5C__AUX_DLL_REMOVE((entry_ptr), \ - (cache_ptr)->cLRU_head_ptr, \ + (cache_ptr)->cLRU_head_ptr, \ (cache_ptr)->cLRU_tail_ptr, \ (cache_ptr)->cLRU_list_len, \ (cache_ptr)->cLRU_list_size, \ - (fail_val)) \ + (fail_val)) \ } \ \ /* insert the entry at the head of either the clean or dirty \ - * LRU list as appropriate. \ + * LRU list as appropriate. \ */ \ \ if ( (entry_ptr)->is_dirty ) { \ \ H5C__AUX_DLL_PREPEND((entry_ptr), \ - (cache_ptr)->dLRU_head_ptr, \ + (cache_ptr)->dLRU_head_ptr, \ (cache_ptr)->dLRU_tail_ptr, \ (cache_ptr)->dLRU_list_len, \ (cache_ptr)->dLRU_list_size, \ - (fail_val)) \ + (fail_val)) \ \ } else { \ \ H5C__AUX_DLL_PREPEND((entry_ptr), \ - (cache_ptr)->cLRU_head_ptr, \ + (cache_ptr)->cLRU_head_ptr, \ (cache_ptr)->cLRU_tail_ptr, \ (cache_ptr)->cLRU_list_len, \ (cache_ptr)->cLRU_list_size, \ - (fail_val)) \ + (fail_val)) \ } \ \ /* End modified LRU specific code. */ \ @@ -2872,7 +2872,7 @@ if ( ( (cache_ptr)->index_size != \ #else /* H5C_MAINTAIN_CLEAN_AND_DIRTY_LRU_LISTS */ -#define H5C__UPDATE_RP_FOR_MOVE(cache_ptr, entry_ptr, was_dirty, fail_val) \ +#define H5C__UPDATE_RP_FOR_MOVE(cache_ptr, entry_ptr, was_dirty, fail_val) \ { \ HDassert( (cache_ptr) ); \ HDassert( (cache_ptr)->magic == H5C__H5C_T_MAGIC ); \ @@ -2881,21 +2881,21 @@ if ( ( (cache_ptr)->index_size != \ HDassert( ((entry_ptr)->ro_ref_count) == 0 ); \ HDassert( (entry_ptr)->size > 0 ); \ \ - if ( ! ( (entry_ptr)->is_pinned ) && ! ( (entry_ptr->is_protected ) ) ) { \ - \ + if ( ! ( (entry_ptr)->is_pinned ) && ! ( (entry_ptr->is_protected ) ) ) {\ + \ /* modified LRU specific code */ \ \ /* remove the entry from the LRU list, and re-insert it at the head. \ - */ \ + */ \ \ H5C__DLL_REMOVE((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ H5C__DLL_PREPEND((entry_ptr), (cache_ptr)->LRU_head_ptr, \ (cache_ptr)->LRU_tail_ptr, \ - (cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_len, \ (cache_ptr)->LRU_list_size, (fail_val)) \ \ /* End modified LRU specific code. */ \ @@ -2952,49 +2952,49 @@ if ( ( (cache_ptr)->index_size != \ \ if ( (entry_ptr)->coll_access ) { \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->coll_list_len, \ - (cache_ptr)->coll_list_size, \ - (entry_ptr)->size, \ - (new_size)); \ - \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->coll_list_len, \ + (cache_ptr)->coll_list_size, \ + (entry_ptr)->size, \ + (new_size)); \ + \ } \ \ if ( (entry_ptr)->is_pinned ) { \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->pel_len, \ - (cache_ptr)->pel_size, \ - (entry_ptr)->size, \ - (new_size)); \ - \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->pel_len, \ + (cache_ptr)->pel_size, \ + (entry_ptr)->size, \ + (new_size)); \ + \ } else { \ \ /* modified LRU specific code */ \ \ - /* Update the size of the LRU list */ \ + /* Update the size of the LRU list */ \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->LRU_list_len, \ - (cache_ptr)->LRU_list_size, \ - (entry_ptr)->size, \ - (new_size)); \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_size, \ + (entry_ptr)->size, \ + (new_size)); \ \ /* Similarly, update the size of the clean or dirty LRU list as \ - * appropriate. At present, the entry must be clean, but that \ - * could change. \ + * appropriate. At present, the entry must be clean, but that \ + * could change. \ */ \ \ if ( (entry_ptr)->is_dirty ) { \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->dLRU_list_len, \ - (cache_ptr)->dLRU_list_size, \ - (entry_ptr)->size, \ - (new_size)); \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->dLRU_list_len, \ + (cache_ptr)->dLRU_list_size, \ + (entry_ptr)->size, \ + (new_size)); \ \ } else { \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->cLRU_list_len, \ - (cache_ptr)->cLRU_list_size, \ - (entry_ptr)->size, \ - (new_size)); \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->cLRU_list_len, \ + (cache_ptr)->cLRU_list_size, \ + (entry_ptr)->size, \ + (new_size)); \ } \ \ /* End modified LRU specific code. */ \ @@ -3017,21 +3017,21 @@ if ( ( (cache_ptr)->index_size != \ \ if ( (entry_ptr)->is_pinned ) { \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->pel_len, \ - (cache_ptr)->pel_size, \ - (entry_ptr)->size, \ - (new_size)); \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->pel_len, \ + (cache_ptr)->pel_size, \ + (entry_ptr)->size, \ + (new_size)); \ \ } else { \ \ /* modified LRU specific code */ \ \ - /* Update the size of the LRU list */ \ + /* Update the size of the LRU list */ \ \ - H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->LRU_list_len, \ - (cache_ptr)->LRU_list_size, \ - (entry_ptr)->size, \ - (new_size)); \ + H5C__DLL_UPDATE_FOR_SIZE_CHANGE((cache_ptr)->LRU_list_len, \ + (cache_ptr)->LRU_list_size, \ + (entry_ptr)->size, \ + (new_size)); \ \ /* End modified LRU specific code. */ \ } \ @@ -3318,7 +3318,7 @@ if ( ( (hd_ptr) == NULL ) || \ ( (Size) < (entry_ptr)->size ) || \ ( ( (Size) == (entry_ptr)->size ) && ( ! ( (len) == 1 ) ) ) || \ ( ( (entry_ptr)->coll_prev == NULL ) && ( (hd_ptr) != (entry_ptr) ) ) || \ - ( ( (entry_ptr)->coll_next == NULL ) && ( (tail_ptr) != (entry_ptr) ) ) || \ + ( ( (entry_ptr)->coll_next == NULL ) && ( (tail_ptr) != (entry_ptr) ) ) ||\ ( ( (len) == 1 ) && \ ( ! ( ( (hd_ptr) == (entry_ptr) ) && ( (tail_ptr) == (entry_ptr) ) && \ ( (entry_ptr)->coll_next == NULL ) && \ @@ -3350,10 +3350,10 @@ if ( ( ( ( (head_ptr) == NULL ) || ( (tail_ptr) == NULL ) ) && \ ) \ ) { \ HDassert(0 && "COLL DLL sanity check failed"); \ - HGOTO_ERROR(H5E_CACHE, H5E_SYSTEM, (fv), "COLL DLL sanity check failed") \ + HGOTO_ERROR(H5E_CACHE, H5E_SYSTEM, (fv), "COLL DLL sanity check failed")\ } -#define H5C__COLL_DLL_PRE_INSERT_SC(entry_ptr, hd_ptr, tail_ptr, len, Size, fv) \ +#define H5C__COLL_DLL_PRE_INSERT_SC(entry_ptr, hd_ptr, tail_ptr, len, Size, fv)\ if ( ( (entry_ptr) == NULL ) || \ ( (entry_ptr)->coll_next != NULL ) || \ ( (entry_ptr)->coll_prev != NULL ) || \ @@ -5074,7 +5074,7 @@ H5_DLL herr_t H5C__generate_cache_image(H5F_t *f, H5C_t *cache_ptr); H5_DLL herr_t H5C__load_cache_image(H5F_t *f); H5_DLL herr_t H5C__mark_flush_dep_serialized(H5C_cache_entry_t * entry_ptr); H5_DLL herr_t H5C__mark_flush_dep_unserialized(H5C_cache_entry_t * entry_ptr); -H5_DLL herr_t H5C__make_space_in_cache(H5F_t * f, size_t space_needed, +H5_DLL herr_t H5C__make_space_in_cache(H5F_t * f, size_t space_needed, hbool_t write_permitted); H5_DLL herr_t H5C__flush_marked_entries(H5F_t * f); H5_DLL herr_t H5C__generate_image(H5F_t *f, H5C_t *cache_ptr, diff --git a/src/H5Cprivate.h b/src/H5Cprivate.h index 102c9bf..f9dfed2 100644 --- a/src/H5Cprivate.h +++ b/src/H5Cprivate.h @@ -213,7 +213,7 @@ #define H5C_DO_TAGGING_SANITY_CHECKS 1 #define H5C_DO_EXTREME_SANITY_CHECKS 0 #else /* NDEBUG */ -/* With rare execptions, the following defines should be set +/* With rare exceptions, the following defines should be set * to 0 if NDEBUG is defined */ #define H5C_DO_SANITY_CHECKS 0 @@ -1428,7 +1428,7 @@ typedef int H5C_ring_t; * with no flush dependency children. * * Since the image_fd_height is used to order entries in the - * cache image so that fd parents preceed fd children, for + * cache image so that fd parents precede fd children, for * purposes of this field, and entry is at flush dependency * level 0 if it either has no children, or if all of its * children are not in the cache image. @@ -1543,7 +1543,7 @@ typedef int H5C_ring_t; * number of times each entry is serialized during cache * serialization. While no entry should be serialized more than * once in any serialization call, throw an assertion if any - * flush depencency parent is serialized more than once during + * flush dependency parent is serialized more than once during * a single cache serialization. * * This is a debugging field, and thus is maintained only if @@ -1734,7 +1734,7 @@ typedef struct H5C_cache_entry_t { * with no flush dependency children. * * Since the image_fd_height is used to order entries in the - * cache image so that fd parents preceed fd children, for + * cache image so that fd parents precede fd children, for * purposes of this field, an entry is at flush dependency * level 0 if it either has no children, or if all of its * children are not in the cache image. @@ -2177,7 +2177,7 @@ typedef struct H5C_auto_size_ctl_t { * equivalent of H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE. * * flags: Unsigned integer containing flags controlling which aspects of the - * cache image functinality is actually executed. The primary impetus + * cache image functionality is actually executed. The primary impetus * behind this field is to allow development of tests for partial * implementations that will require little if any modification to run * with the full implementation. In normal operation, all flags should diff --git a/src/H5Dpkg.h b/src/H5Dpkg.h index 16e101c..53e430a 100644 --- a/src/H5Dpkg.h +++ b/src/H5Dpkg.h @@ -430,7 +430,7 @@ typedef struct H5D_rdcdc_t { /* * A dataset is made of two layers, an H5D_t struct that is unique to - * each instance of an opened datset, and a shared struct that is only + * each instance of an opened dataset, and a shared struct that is only * created once for a given dataset. Thus, if a dataset is opened twice, * there will be two IDs and two H5D_t structs, both sharing one H5D_shared_t. */ diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index 1fdfa3f..9709289 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -77,7 +77,7 @@ typedef enum H5D_chunk_index_t { */ typedef enum H5D_alloc_time_t { H5D_ALLOC_TIME_ERROR = -1, /**< Error */ - H5D_ALLOC_TIME_DEFAULT = 0, /**< \todo Define this! */ + H5D_ALLOC_TIME_DEFAULT = 0, /**< Default (layout dependent) */ 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) */ @@ -91,9 +91,9 @@ typedef enum H5D_alloc_time_t { typedef enum H5D_space_status_t { 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_PART_ALLOCATED = 1, /**< Space has been partially allocated for this dataset. + (Used only for datasets with chunked storage.) */ + H5D_SPACE_STATUS_ALLOCATED = 2 /**< Space has been allocated for this dataset. */ } H5D_space_status_t; //! <!-- [H5D_space_status_t_snip] --> @@ -127,8 +127,8 @@ typedef enum H5D_fill_value_t { */ typedef enum H5D_vds_view_t { H5D_VDS_ERROR = -1, /**< Error */ - H5D_VDS_FIRST_MISSING = 0, /**< \todo Define this! */ - H5D_VDS_LAST_AVAILABLE = 1 /**< \todo Define this! */ + H5D_VDS_FIRST_MISSING = 0, /**< Include all data before the first missing mapped data */ + H5D_VDS_LAST_AVAILABLE = 1 /**< Include all available mapped data */ } H5D_vds_view_t; //! <!-- [H5D_vds_view_t_snip] --> @@ -279,7 +279,7 @@ extern "C" { * caller may derive new datatypes, dataspaces, and creation and * access properties from the old ones and reuse them in calls to * create additional datasets. Once created, the dataset can be - * read from or written to. Reading data from a datatset that was + * read from or written to. Reading data from a dataset that was * not previously written, the HDF5 library will return default * or user-defined fill values. * diff --git a/src/H5EApkg.h b/src/H5EApkg.h index bfa8588..2212ccb 100644 --- a/src/H5EApkg.h +++ b/src/H5EApkg.h @@ -301,7 +301,7 @@ typedef struct H5EA_dblock_t { /* Computed/cached values (not stored) */ size_t nelmts; /* Number of elements in block */ - size_t npages; /* Nummber of pages in a block (zero if not paged) */ + size_t npages; /* Number of pages in a block (zero if not paged) */ } H5EA_dblock_t; /* The extensible array data block page information */ diff --git a/src/H5Epkg.h b/src/H5Epkg.h index 30ff084..b11ee9e 100644 --- a/src/H5Epkg.h +++ b/src/H5Epkg.h @@ -48,7 +48,7 @@ * each thread individually. The association of stacks to threads will * be handled by the pthread library. * - * In order for this macro to work, H5E__get_my_stack() must be preceeded + * In order for this macro to work, H5E__get_my_stack() must be preceded * by "H5E_t *estack =". */ #define H5E__get_my_stack() H5E__get_stack() diff --git a/src/H5FApkg.h b/src/H5FApkg.h index c4bf934..15f6445 100644 --- a/src/H5FApkg.h +++ b/src/H5FApkg.h @@ -179,8 +179,8 @@ typedef struct H5FA_dblock_t { /* Computed/cached values (not stored) */ haddr_t addr; /* Address of this data block on disk */ hsize_t size; /* Size of data block on disk */ - size_t npages; /* Nummber of pages in data block (zero if not paged) */ - size_t last_page_nelmts; /* Nummber of elements in last page, if paged */ + size_t npages; /* Number of pages in data block (zero if not paged) */ + size_t last_page_nelmts; /* Number of elements in last page, if paged */ /* Fixed Array data block information (not stored) */ size_t dblk_page_nelmts; /* # of elements per data block page */ diff --git a/src/H5FDmirror.h b/src/H5FDmirror.h index 49e24c1..0db8b13 100644 --- a/src/H5FDmirror.h +++ b/src/H5FDmirror.h @@ -33,7 +33,7 @@ extern "C" { /* --------------------------------------------------------------------------- * Structure: H5FD_mirror_fapl_t * - * Used to pass configuraiton information to the Mirror VFD. + * Used to pass configuration information to the Mirror VFD. * Populate components as appropriate and pass structure pointer to * `H5Pset_fapl_mirror()`. * diff --git a/src/H5FDmirror_priv.h b/src/H5FDmirror_priv.h index 21de97b..b387f72 100644 --- a/src/H5FDmirror_priv.h +++ b/src/H5FDmirror_priv.h @@ -28,7 +28,7 @@ extern "C" { * = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = */ -/* The maximum allowed size for a receiving buffer when accepting bytes to +/* Define the maximum allowed size for a receiving buffer when accepting bytes to * write. Writes larger than this size are performed by multiple accept-write * steps by the Writer. */ #define H5FD_MIRROR_DATA_BUFFER_MAX H5_GB /* 1 Gigabyte */ @@ -80,7 +80,7 @@ extern "C" { * * `magic` (uint32_t) * A "unique" number identifying the structure and endianness of - * transmitting maching. + * transmitting machine. * Must be set to H5FD_MIRROR_XMIT_MAGIC native to the VFD "sender". * * `version` (uint8_t) @@ -214,13 +214,13 @@ typedef struct H5FD_mirror_xmit_open_t { * * `status` (uint32_t) * Number indicating whether the command was successful or if an - * occured. + * occurred. * Allowed values are H5FD_MIRROR_STATUS_OK and * H5FD_MIRROR_STATUS_ERROR. * * `message` (char[]) * Error message. Populated if and only if there was a problem. - * It is possible that a message may reach the end of the alloted + * It is possible that a message may reach the end of the allotted * space without a NULL terminator -- the onus is on the programmer to * handle this situation. * diff --git a/src/H5FDmpio.h b/src/H5FDmpio.h index 8caf11c..a70f34b 100644 --- a/src/H5FDmpio.h +++ b/src/H5FDmpio.h @@ -223,7 +223,7 @@ H5_DLL herr_t H5Pset_dxpl_mpio_collective_opt(hid_t dxpl_id, H5FD_mpio_collectiv * * Use of this function is optional. * - * \todo Add missing version information + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t opt_mode); @@ -247,7 +247,7 @@ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t op * otherwise, a separate I/O process will be invoked for each chunk * (multi-chunk I/O). * - * \todo Add missing version information + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_per_proc); @@ -272,7 +272,7 @@ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_p * percent_proc_per_chunk, the library will do collective I/O for this * chunk; otherwise, independent I/O will be done for the chunk. * - * \todo Add missing version information + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_ratio(hid_t dxpl_id, unsigned percent_num_proc_per_chunk); diff --git a/src/H5FDs3comms.h b/src/H5FDs3comms.h index da6a62d..b81bfae 100644 --- a/src/H5FDs3comms.h +++ b/src/H5FDs3comms.h @@ -179,7 +179,7 @@ * HTTP header fields, of particular use when composing an * "S3 Canonical Request" for authentication. * - * - The creation of a Canoncial Request involves: + * - The creation of a Canonical Request involves: * - convert field names to lower case * - sort by this lower-case name * - convert ": " name-value separator in HTTP string to ":" @@ -459,7 +459,7 @@ typedef struct { * * Pointer to NULL-terminated string for "secret" access id to S3 resource. * - * Requred to authenticate. + * Required to authenticate. * * `signing_key` (unsigned char *) * @@ -470,7 +470,7 @@ typedef struct { * which may be re-used for several (up to seven (7)) days from creation? * Computed once upon file open. * - * Requred to authenticate. + * Required to authenticate. * *---------------------------------------------------------------------------- */ diff --git a/src/H5FDsplitter.h b/src/H5FDsplitter.h index ee6e7c5..b424582 100644 --- a/src/H5FDsplitter.h +++ b/src/H5FDsplitter.h @@ -34,7 +34,7 @@ * Structure: H5FD_spliiter_vfd_config_t * * One-stop shopping for configuring a Splitter VFD (rather than many - * paramaters passed into H5Pset/get functions). + * parameters passed into H5Pset/get functions). * * magic (int32_t) * Semi-unique number, used to sanity-check that a given pointer is diff --git a/src/H5FLprivate.h b/src/H5FLprivate.h index 42581ac..504c385 100644 --- a/src/H5FLprivate.h +++ b/src/H5FLprivate.h @@ -148,8 +148,8 @@ typedef struct H5FL_reg_head_t { typedef union H5FL_blk_list_t { size_t size; /* Size of the page */ union H5FL_blk_list_t *next; /* Pointer to next block in free list */ - double unused1; /* Unused normally, just here for aligment */ - haddr_t unused2; /* Unused normally, just here for aligment */ + double unused1; /* Unused normally, just here for alignment */ + haddr_t unused2; /* Unused normally, just here for alignment */ } H5FL_blk_list_t; /* Data structure for priority queue node of block free lists */ @@ -223,8 +223,8 @@ typedef struct H5FL_blk_head_t { typedef union H5FL_arr_list_t { union H5FL_arr_list_t *next; /* Pointer to next block in free list */ size_t nelem; /* Number of elements in this array */ - double unused1; /* Unused normally, just here for aligment */ - haddr_t unused2; /* Unused normally, just here for aligment */ + double unused1; /* Unused normally, just here for alignment */ + haddr_t unused2; /* Unused normally, just here for alignment */ } H5FL_arr_list_t; /* Data structure for each size of array element */ diff --git a/src/H5Fpkg.h b/src/H5Fpkg.h index 63c22a1..4a414b2 100644 --- a/src/H5Fpkg.h +++ b/src/H5Fpkg.h @@ -78,7 +78,7 @@ #define H5F_SUPERBLOCK_FIXED_SIZE (H5F_SIGNATURE_LEN + 1) /* superblock version */ /* The H5F_SUPERBLOCK_MINIMAL_VARLEN_SIZE is the minimal amount of super block - * variable length data guarnateed to load the sizeof offsets and the sizeof + * variable length data guaranteed to load the sizeof offsets and the sizeof * lengths fields in all versions of the superblock. * * This is necessary in the V3 cache, as on the initial load, we need to @@ -350,7 +350,7 @@ struct H5F_shared_t { /* Metadata retry info */ unsigned read_attempts; /* The # of reads to try when reading metadata with checksum */ unsigned retries_nbins; /* # of bins for each retries[] */ - uint32_t *retries[H5AC_NTYPES]; /* Track # of read retries for metdata items with checksum */ + uint32_t *retries[H5AC_NTYPES]; /* Track # of read retries for metadata items with checksum */ /* Object flush info */ H5F_object_flush_t object_flush; /* Information for object flush callback */ diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h index 58fa3b8..7531bf4 100644 --- a/src/H5Fpublic.h +++ b/src/H5Fpublic.h @@ -1507,7 +1507,7 @@ H5_DLL herr_t H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], u * \brief Obtains information about a cache image if it exists * * \file_id - * \param[out] image_addr Offset of the cache image if it exists, or \c HADDR_UNDEF if it does not + * \param[out] image_addr Offset of the cache image if it exists, or #HADDR_UNDEF if it does not * \param[out] image_size Length of the cache image if it exists, or 0 if it does not * \returns \herr_t * @@ -1757,6 +1757,7 @@ H5_DLL herr_t H5Fget_info1(hid_t obj_id, H5F_info1_t *file_info); * * \deprecated When? * + * \todo In which version was this function introduced? * \todo In which version was this function deprecated? * */ diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h index 7f1faf8..1d8f8fb 100644 --- a/src/H5Gpublic.h +++ b/src/H5Gpublic.h @@ -1038,7 +1038,7 @@ H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link * actual object name length, the object name is truncated to * \Code{max_size - 1} characters. * - * Note that if the size of the object's name is unkown, a preliminary + * Note that if the size of the object's name is unknown, a preliminary * call to H5Gget_objname_by_idx() with \p name set to \c NULL will * return the length of the object's name. A second call to * H5Gget_objname_by_idx() can then be used to retrieve the actual diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h index d07347b..d52e558 100644 --- a/src/H5Ipublic.h +++ b/src/H5Ipublic.h @@ -496,7 +496,7 @@ H5_DLL int H5Idec_type_ref(H5I_type_t type); * * \brief Retrieves the reference count on an ID type * - * \param[in] type The identifier of the type whose reference count is to be retieved + * \param[in] type The identifier of the type whose reference count is to be retrieved * * \return Returns the current reference count on success, negative on failure. * diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h index 82f5f16..9d06272 100644 --- a/src/H5Lpublic.h +++ b/src/H5Lpublic.h @@ -508,7 +508,7 @@ H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t * * \return \herr_t * - * \details H5Lget_val() returns tha value of link \p name. For smbolic links, + * \details H5Lget_val() returns the value of link \p name. For smbolic links, * this is the path to which the link points, including the null * terminator. For external and user-defined links, it is the link * buffer. @@ -538,7 +538,7 @@ H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t * * This function should be used only after H5Lget_info() has been * called to verify that \p name is a symbolic link. This can be - * deteremined from the \c link_type field of the \ref H5L_info_t + * determined from the \c link_type field of the \ref H5L_info_t * \c struct. * * \note This function will fail if called on a hard link. @@ -626,7 +626,7 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t * name includes either a relative path or an absolute path to the * target link, intermediate steps along the path must be verified * before the existence of the target link can be safely checked. If - * the path is not verified and an intermediate element of the path + * the path is not verified, and an intermediate element of the path * does not exist, H5Lexists() will fail. The example in the next * paragraph illustrates one step-by-step method for verifying the * existence of a link with a relative or absolute path. @@ -671,7 +671,7 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t * root group of an HDF5 file, and let \c lapl denote a valid link * access property list identifier. A call to H5Lexists() with * arguments c root, \c "/", and \c lapl returns a positive value; - * in other words, \Code{H5Lexists(root, "/", lapl)} returns a postive + * in other words, \Code{H5Lexists(root, "/", lapl)} returns a positive * value. In HDF5 version 1.8.16, this function returns 0.</li> * </ol> * Note that the function accepts link names and path names. This is @@ -1130,7 +1130,7 @@ H5_DLL herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, * \p idx_type specifies the index to be used. If the links 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 unnecesary, so the iteration may + * indexed, the sorting step will be unnecessary, so the iteration may * begin more quickly. Valid values include the following: * \indexes * diff --git a/src/H5Oprivate.h b/src/H5Oprivate.h index 3367231..b396cae 100644 --- a/src/H5Oprivate.h +++ b/src/H5Oprivate.h @@ -250,7 +250,7 @@ typedef struct H5O_copy_t { #define H5O_SHARE_TYPE_UNSHARED 0 /* Message is not shared */ #define H5O_SHARE_TYPE_SOHM 1 /* Message is stored in SOHM heap */ #define H5O_SHARE_TYPE_COMMITTED 2 /* Message is stored in another object header */ -#define H5O_SHARE_TYPE_HERE 3 /* Message is stored in this object header, but is sharable */ +#define H5O_SHARE_TYPE_HERE 3 /* Message is stored in this object header, but is shareable */ /* Detect messages that aren't stored in message's object header */ #define H5O_IS_STORED_SHARED(T) \ diff --git a/src/H5Opublic.h b/src/H5Opublic.h index 001ee31..5eddb7e 100644 --- a/src/H5Opublic.h +++ b/src/H5Opublic.h @@ -80,7 +80,7 @@ #define H5O_SHMESG_MAX_LIST_SIZE 5000 /* Flags for H5Oget_info. - * Theses flags determine which fields will be filled in in the H5O_info_t + * These flags determine which fields will be filled in the H5O_info_t * struct. */ #define H5O_INFO_BASIC 0x0001u /**< Fill in the fileno, addr, type, and rc fields */ @@ -497,7 +497,7 @@ H5_DLL herr_t H5Oget_info2(hid_t loc_id, H5O_info_t *oinfo, unsigned fields); * location and relative name * * \fgdta_loc_obj_id{loc_id} - * \param[in] name Name of group, relative to \p loc_id + * \param[in] name Name of object, relative to \p loc_id * \param[out] oinfo Buffer in which to return object information * \param[in] fields Flags specifying the fields to include in \p oinfo * \lapl_id @@ -565,6 +565,7 @@ H5_DLL herr_t H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info_t *o H5_DLL herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5O_info_t *oinfo, unsigned fields, hid_t lapl_id); + /** *------------------------------------------------------------------------- * \ingroup H5O @@ -1027,7 +1028,7 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm * <em>best effort</em> setting. If the application passes in * a value indicating iteration in creation order and a group is * encountered that was not tracked in creation order, that group - * will be iterated over in alpha-numeric order by name, or + * will be iterated over in alphanumeric order by name, or * <em>name order</em>. (<em>Name order</em> is the native order * used by the HDF5 library and is always available.) * @@ -1134,14 +1135,13 @@ 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: + * 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 * encountered that was not tracked in creation order, that group - * will be iterated over in alpha-numeric order by name, or + * will be iterated over in alphanumeric order by name, or * <em>name order</em>. (<em>Name order</em> is the native order * used by the HDF5 library and is always available.) * @@ -1440,7 +1440,7 @@ H5_DLL herr_t H5Oget_info(hid_t loc_id, H5O_info_t *oinfo); * by location and relative name * * \fgdta_loc_obj_id{loc_id} - * \param[in] name Name of group, relative to \p loc_id + * \param[in] name Name of object, relative to \p loc_id * \param[out] oinfo Buffer in which to return object information * \lapl_id * @@ -1618,7 +1618,7 @@ H5_DLL herr_t H5Oget_info_by_name1(hid_t loc_id, const char *name, H5O_info_t *o * \param[in] group_name Name of group in which object is located * \idx_type * \order - * \param[in] n Position within the index + * \param[in] n Position within the index * \param[out] oinfo Buffer in which to return object information * \lapl_id * @@ -1632,7 +1632,7 @@ H5_DLL herr_t H5Oget_info_by_name1(hid_t loc_id, const char *name, H5O_info_t *o * \p n within that index. * * If \p loc_id fully specifies the group in which the object resides, - * \p group_name can be a dot (\c .). + * i\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 @@ -1710,7 +1710,7 @@ H5_DLL herr_t H5Oget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index * <em>best effort</em> setting. If the application passes in * a value indicating iteration in creation order and a group is * encountered that was not tracked in creation order, that group - * will be iterated over in alpha-numeric order by name, or + * will be iterated over in alphanumeric order by name, or * <em>name order</em>. (<em>Name order</em> is the native order * used by the HDF5 library and is always available.) * @@ -1817,7 +1817,7 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * <em>best effort</em> setting. If the application passes in a * value indicating iteration in creation order and a group is * encountered that was not tracked in creation order, that group - * will be iterated over in alpha-numeric order by name, or + * will be iterated over in alphanumeric order by name, or * <em>name order</em>. (<em>Name order</em> is the native order * used by the HDF5 library and is always available.) * diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h index a093096..8076205 100644 --- a/src/H5PLmodule.h +++ b/src/H5PLmodule.h @@ -2,7 +2,7 @@ * Copyright by The HDF Group. * * All rights reserved. * * * - * This file is part of HDF5. The full HDF5 copyright notice, including * + * 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. * diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index 3c28615..8081ee3 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -111,7 +111,8 @@ * * \defgroup GAPL General Access Properties * \ingroup H5P - * \todo Should this be as standalone page? + * The functions in this section can be applied to different kinds of property + * lists. * * \defgroup GCPL Group Creation Properties * \ingroup H5P diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 35ed341..474339f 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -108,21 +108,70 @@ extern "C" { /* Define property list class callback function pointer types */ //! <!-- [H5P_cls_create_func_t_snip] --> /** - * \todo Document me! + * \brief Callback function for H5Pcreate_class() + * + * \param[in] prop_id The identifier of the property list class being created + * \param[in] create_data User pointer to any class creation data required + * \return \herr_t + * + * \details This function is called when a new property list of the class + * with which this function was registered is being created. The + * function is called after any registered parent create function is + * called for each property value. + * + * If the create function returns a negative value, the new list is not + * returned to the user and the property list creation routine returns + * an error value. + * + * \since 1.4.0 + * */ 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! + * \brief Callback function for H5Pcreate_class() + * + * \param[in] new_prop_id The identifier of the property list copy + * \param[in] old_prop_id The identifier of the property list being copied + * \param[in] copy_data User pointer to any copy data required + * \return \herr_t + * + * \details This function is called when an existing property list of this + * class is copied. The copy callback function is called after any + * registered parent copy callback function is called for each property + * value. + * + * If the copy routine returns a negative value, the new list is not + * returned to the user and the property list copy function returns an + * error value. + * + * \since 1.4.0 + * */ 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! + * \brief Callback function for H5Pcreate_class() + * + * \param[in] prop_id The identifier of the property list class being created + * \param[in] close_data User pointer to any close data required + * \return \herr_t + * + * \details This function is called when a property list of the class + * with which this function was registered is being closed. The + * function is called after any registered parent close function is + * called for each property value. + * + * If the close function returns a negative value, the new list is not + * returned to the user and the property list close routine returns + * an error value. + * + * \since 1.4.0 + * */ typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); //! <!-- [H5P_cls_close_func_t_snip] --> @@ -137,8 +186,8 @@ typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); * \param[in,out] value The value for the property * \return \herr_t * - * \details The H5P_prp_cb1_t() describes the parameters used by the - * property create,copy and close callback functions. + * \details The H5P_prp_cb1_t() function describes the parameters used by the + * property create, copy and close callback functions. */ typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value); //! <!-- [H5P_prp_cb1_t_snip] --> @@ -153,8 +202,8 @@ typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value); * \param[in] value The value for the property * \return \herr_t * - * \details The H5P_prp_cb2_t() describes the parameters used by the - * property set ,copy and delete callback functions. + * \details The H5P_prp_cb2_t() function describes the parameters used by the + * property set, copy and delete callback functions. */ typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value); //! <!-- [H5P_prp_cb2_t_snip] --> @@ -167,7 +216,16 @@ typedef H5P_prp_cb1_t H5P_prp_copy_func_t; //! <!-- [H5P_prp_compare_func_t_snip] --> /** - * \todo Document me! + * \brief Callback function for comparing property values + * + * \param[in] value1 A property value + * \param[in] value2 A property value + * \param[in] size The size of the \p value1 and \p value2 buffers + * \return Returns a positive value if \c value1 is greater than \c value2, a + * negative value if \c value2 is greater than \c value1 and zero if + * \c value1 and \c value2 are equal. + * + * \see H5Pregister(), H5Pinsert() */ typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size); //! <!-- [H5P_prp_compare_func_t_snip] --> @@ -177,7 +235,19 @@ typedef H5P_prp_cb1_t H5P_prp_close_func_t; /* Define property list iteration function type */ //! <!-- [H5P_iterate_t_snip] --> /** - * \todo Document me! + * \brief Callback function for H5Piterate() + * + * \param[in] id The identifier of a property list or property list class + * \param[in] name The name of the current property + * \param[in,out] iter_data The user context passed to H5Piterate() + * \return \herr_t_iter + * + * \details This function is called for each property encountered when + * iterating over a property list or property list class + * via H5Piterate(). + * + * \since 1.4.0 + * */ typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data); //! <!-- [H5P_iterate_t_snip] --> @@ -244,15 +314,15 @@ typedef enum H5D_mpio_no_collective_cause_t { H5D_MPIO_DATA_TRANSFORMS = 0x04, /**< Collective I/O was not performed because data transforms needed to be applied */ H5D_MPIO_MPI_OPT_TYPES_ENV_VAR_DISABLED = 0x08, - /**< \todo FIXME! */ + /**< Collective I/O was disabled by environment variable (\Code{HDF5_MPI_OPT_TYPES}) */ H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES = 0x10, /**< Collective I/O was not performed because one of the dataspaces was neither simple nor scalar */ H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET = 0x20, /**< Collective I/O was not performed because the dataset was neither contiguous nor chunked */ H5D_MPIO_PARALLEL_FILTERED_WRITES_DISABLED = 0x40, - /**< \todo FIXME! */ + /**< Collective I/O was not performed because parallel filtered writes are disabled */ H5D_MPIO_ERROR_WHILE_CHECKING_COLLECTIVE_POSSIBLE = 0x80, - /**< \todo FIXME! */ + /**< Error */ H5D_MPIO_NO_COLLECTIVE_MAX_CAUSE = 0x100 /**< Sentinel */ } H5D_mpio_no_collective_cause_t; @@ -543,77 +613,12 @@ H5_DLL hid_t H5Pcreate(hid_t cls_id); * those existing properties, only add or remove their own class * properties. Property list classes defined and supported in the * HDF5 library distribution are listed and briefly described in - * H5Pcreate(). The \p create routine is called when a new property - * list of this class is being created. The #H5P_cls_create_func_t - * callback function is defined as follows: + * H5Pcreate(). The \p create, \p copy, \p close functions are called + * when a property list of the new class is created, copied, or closed, + * respectively. * - * \snippet this H5P_cls_create_func_t_snip - * - * The parameters to this callback function are defined as follows: - * <table> - * <tr> - * <td>\ref hid_t \c prop_id</td> - * <td>IN: The identifier of the property list being created</td> - * </tr> - * <tr> - * <td>\Code{void * create_data}</td> - * <td>IN: User pointer to any class creation data required</td> - * </tr> - * </table> - * - * The \p create routine is called after any registered - * \p create function is called for each property value. If the - * \p create routine returns a negative value, the new list is not - * returned to the user and the property list creation routine returns - * an error value. - * - * The \p copy routine is called when an existing property - * list of this class is copied. The #H5P_cls_copy_func_t callback - * function is defined as follows: - * \snippet this H5P_cls_copy_func_t_snip - * - * The parameters to this callback function are defined as follows: - * <table> - * <tr> - * <td>\ref hid_t \c prop_id</td> - * <td>IN: The identifier of the property list created by copying</td> - * </tr> - * <tr> - * <td>\Code{void * copy_data}</td> - * <td>IN: User pointer to any class copy data required</td> - * </tr> - * </table> - * - * The \p copy routine is called after any registered \p copy function - * is called for each property value. If the \p copy routine returns a - * negative value, the new list is not returned to the user and the - * property list \p copy routine returns an error value. - * - * The \p close routine is called when a property list of this class - * is being closed. The #H5P_cls_close_func_t callback function is - * defined as follows: - * \snippet this H5P_cls_close_func_t_snip - * - * The parameters to this callback function are defined as follows: - * <table> - * <tr> - * <td>\ref hid_t \c prop_id</td> - * <td>IN: The identifier of the property list being closed</td> - * </tr> - * <tr> - * <td>\Code{void * close_data}</td> - * <td>IN: User pointer to any class close data required</td> - * </tr> - * </table> - * - * The \p close routine is called before any registered \p close - * function is called for each property value. If the \p close routine - * returns a negative value, the property list close routine returns - * an error value but the property list is still closed. - * - * H5Pclose_class() can be used to release the property list class - * identifier returned by this function so that resources leaks will - * not develop. + * H5Pclose_class() must be used to release the property list class + * identifier returned by this function. * * \since 1.4.0 * @@ -1327,35 +1332,12 @@ H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id); * returned in this case, the iterator cannot be restarted if * one of the calls to its operator returns non-zero. * - * The prototype for the #H5P_iterate_t operator is as follows: - * \snippet this H5P_iterate_t_snip - * - * The operation receives the property list or class + * The operation \p iter_func receives the property list or class * identifier for the object being iterated over, \p id, the * name of the current property within the object, \p name, * and the pointer to the operator data passed in to H5Piterate(), - * \p iter_data. The valid return values from an operator are - * as follows: + * \p iter_data. * - * <table> - * <tr> - * <td>Zero</td> - * <td>Causes the iterator to continue, returning zero when all - * properties have been processed</td> - * </tr> - * <tr> - * <td>Positive</td> - * <td>Causes the iterator to immediately return that positive - * value, indicating short-circuit success. The iterator - * can be restarted at the index of the next property</td> - * </tr> - * <tr> - * <td>Negative</td> - * <td>Causes the iterator to immediately return that value, - * indicating failure. The iterator can be restarted at the - * index of the next property</td> - * </tr> - * </table> * H5Piterate() assumes that the properties in the object * identified by \p id remain unchanged through the iteration. * If the membership changes during the iteration, the function's @@ -1828,9 +1810,6 @@ H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, un * * \brief Returns information about a filter in a pipeline * - * \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in - * H5Ppublic.h - * * \ocpl_id{plist_id} * \param[in] idx Sequence number within the filter pipeline of the filter * for which information is sought @@ -3835,13 +3814,13 @@ H5_DLL herr_t H5Pget_meta_block_size(hid_t fapl_id, hsize_t *size); * * The second example illustrates the two cases for retrieving the * number of read attempts from the file access property list of a file - * opened with SWMR acccess. + * opened with SWMR access. * * \include H5Pget_metadata_read_attempts.2.c * * The third example illustrates the two cases for retrieving the number * of read attempts from the file access property list of a file opened - * with non-SWMR acccess. + * with non-SWMR access. * * \include H5Pget_metadata_read_attempts.3.c * @@ -4092,17 +4071,14 @@ H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold, hsize_t alignme * * \note Note: Raw dataset chunk caching is not currently * supported when using the MPI I/O and MPI POSIX file drivers - * in read/write mode; see H5Pset_fapl_mpio() and - * H5Pset_fapl_mpiposix(), respectively. When using one of these - * file drivers, all calls to H5Dread() and H5Dwrite() will access + * in read/write mode; see H5Pset_fapl_mpio(). When using this + * file driver, all calls to H5Dread() and H5Dwrite() will access * the disk directly, and H5Pset_cache() will have no effect on * performance. * * \note Raw dataset chunk caching is supported when these drivers are * used in read-only mode. * - * \todo Check on H5Pset_fapl_mpio() and H5Pset_fapl_mpiposix(). - * * \version 1.8.0 The use of the \p mdc_nelmts parameter was discontinued. * Metadata cache configuration is managed with * H5Pset_mdc_config() and H5Pget_mdc_config(). @@ -4210,7 +4186,7 @@ H5_DLL herr_t H5Pset_driver(hid_t plist_id, hid_t driver_id, const void *driver_ * The <em>external link open file cache</em> holds files open after * they have been accessed via an external link. This cache reduces * the number of times such files are opened when external links are - * accessed repeatedly and can siginificantly improves performance in + * accessed repeatedly and can significantly improves performance in * certain heavy-use situations and when low-level file opens or closes * are expensive. * @@ -6249,10 +6225,10 @@ H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); * <td>byte 0</td> * </tr> * <tr> - * <td>????????</td> - * <td>????SPPP</td> - * <td>PPPPPPPP</td> - * <td>PPPP????</td> + * <td> ???????? </td> + * <td> ????SPPP </td> + * <td> PPPPPPPP </td> + * <td> PPPP???? </td> * </tr> * </table> * Note: S - sign bit, P - significant bit, ? - padding bit; For @@ -6878,9 +6854,6 @@ H5_DLL herr_t H5Pget_virtual_printf_gap(hid_t dapl_id, hsize_t *gap_size); * * \dapl_id * \param[out] view The flag specifying the view of the virtual dataset. - * Valid values are: - * \li #H5D_VDS_FIRST_MISSING - * \li #H5D_VDS_LAST_AVAILABLE * * \return \herr_t * @@ -7234,11 +7207,7 @@ H5_DLL herr_t H5Pset_virtual_printf_gap(hid_t dapl_id, hsize_t gap_size); * * \dapl_id * \param[in] view Flag specifying the extent of the data to be included - * in the view. Valid values are: - * \li #H5D_VDS_FIRST_MISSING: View includes all data - * before the first missing mapped data - * \li #H5D_VDS_LAST_AVAILABLE View includes all - * available mapped data + * in the view. * * \return \herr_t * @@ -7406,8 +7375,11 @@ H5_DLL herr_t H5Pget_hyper_vector_size(hid_t fapl_id, size_t *size /*out*/); * \details H5Pget_preserve() checks the status of the dataset transfer * property list. * + * \since 1.0.0 + * * \version 1.6.0 The flag parameter was changed from INTEGER to LOGICAL to * better match the C API. (Fortran 90) + * \version 1.8.2 Deprecated. * */ H5_DLL int H5Pget_preserve(hid_t plist_id); @@ -7435,6 +7407,8 @@ H5_DLL int H5Pget_preserve(hid_t plist_id); * * Please refer to the function H5Pset_type_conv_cb() for more details. * + * \since 1.8.0 + * */ H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void **operate_data); /** @@ -7458,6 +7432,8 @@ H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, voi * H5Pset_vlen_mem_manager(), returning the parameters set by * that function. * + * \since 1.0.0 + * */ H5_DLL herr_t H5Pget_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t *alloc_func, void **alloc_info, H5MM_free_t *free_func, void **free_info); @@ -7701,8 +7677,9 @@ H5_DLL herr_t H5Pset_hyper_vector_size(hid_t plist_id, size_t size); * I/O pipeline treats the destination datapoints as completely * uninitialized. * - * \todo Add missing version information: introduction, deprecation, etc. - * Why is the declaration not in the deprecated section? + * \since 1.0.0 + * + * \version 1.8.2 Deprecated. * */ H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); @@ -7730,7 +7707,7 @@ H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); * function prototype is as follows: * \snippet H5Tpublic.h H5T_conv_except_func_t_snip * - * \todo Add version information. + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void *operate_data); @@ -7780,7 +7757,8 @@ H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void * set to \c NULL and the \p alloc_info and \p free_info parameters are * ignored. * - * \todo Add version information. + * \since 1.0.0 + * */ H5_DLL herr_t H5Pset_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t alloc_func, void *alloc_info, H5MM_free_t free_func, void *free_info); diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h index fe28bb2..32343be 100644 --- a/src/H5Rmodule.h +++ b/src/H5Rmodule.h @@ -32,7 +32,6 @@ * 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"> diff --git a/src/H5Spkg.h b/src/H5Spkg.h index e6c031d..5ad8684 100644 --- a/src/H5Spkg.h +++ b/src/H5Spkg.h @@ -197,7 +197,7 @@ struct H5S_hyper_span_info_t { typedef enum { H5S_DIMINFO_VALID_IMPOSSIBLE, /* 0: diminfo is not valid and can never be valid with the current selection */ - H5S_DIMINFO_VALID_NO, /* 1: diminfo is not valid but may or may not be possible to constuct */ + H5S_DIMINFO_VALID_NO, /* 1: diminfo is not valid but may or may not be possible to construct */ H5S_DIMINFO_VALID_YES /* 2: diminfo is valid */ } H5S_diminfo_valid_t; diff --git a/src/H5TSprivate.h b/src/H5TSprivate.h index 3c81f26..485b173 100644 --- a/src/H5TSprivate.h +++ b/src/H5TSprivate.h @@ -13,11 +13,9 @@ /*------------------------------------------------------------------------- * - * Created: H5TSprivate.h - * May 2 2000 - * Chee Wai LEE + * Created: H5TSprivate.h * - * Purpose: Private non-prototype header. + * Purpose: Thread-safety abstractions used by the library * *------------------------------------------------------------------------- */ @@ -25,6 +23,7 @@ #define H5TSprivate_H_ #ifdef H5_HAVE_THREADSAFE + /* Public headers needed by this file */ #ifdef LATER #include "H5TSpublic.h" /* Public API prototypes */ @@ -134,6 +133,7 @@ H5_DLL H5TS_thread_t H5TS_create_thread(void *(*func)(void *), H5TS_attr_t *attr #else /* H5_HAVE_THREADSAFE */ +/* Non-threadsafe code needs this */ #define H5TS_thread_id() ((uint64_t)0) #endif /* H5_HAVE_THREADSAFE */ diff --git a/src/H5Tpkg.h b/src/H5Tpkg.h index b23b599..7c68de9 100644 --- a/src/H5Tpkg.h +++ b/src/H5Tpkg.h @@ -116,7 +116,7 @@ #endif /* Define an internal macro for converting unsigned long long to long double. SGI compilers give - * some incorect conversion. 64-bit Solaris does different rounding. Windows Visual Studio 6 does + * some incorrect conversion. 64-bit Solaris does different rounding. Windows Visual Studio 6 does * not support unsigned long long. For FreeBSD(sleipnir), the last 2 bytes of mantissa are lost when * compiler tries to do the conversion. For Cygwin, compiler doesn't do rounding correctly. * Mac OS 10.4 gives some incorrect result. */ diff --git a/src/H5Tprivate.h b/src/H5Tprivate.h index 858abcd..aae0774 100644 --- a/src/H5Tprivate.h +++ b/src/H5Tprivate.h @@ -20,11 +20,11 @@ /* Early typedefs to avoid circular dependencies */ typedef struct H5T_t H5T_t; -/* Get package's public header */ +/* Include package's public header */ #include "H5Tpublic.h" /* Other public headers needed by this file */ -#include "H5MMpublic.h" /* Memory management */ +#include "H5MMpublic.h" /* Memory management */ /* Private headers needed by this file */ #include "H5private.h" /* Generic Functions */ diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h index 10a4b06..14faa9b 100644 --- a/src/H5Tpublic.h +++ b/src/H5Tpublic.h @@ -148,7 +148,7 @@ typedef enum H5T_pad_t { H5T_PAD_ONE = 1, /**< always set to one */ H5T_PAD_BACKGROUND = 2, /**< set to background value */ - H5T_NPAD = 3 /**< sentinal: THIS MUST BE LAST */ + H5T_NPAD = 3 /**< sentinel: THIS MUST BE LAST */ } H5T_pad_t; //! <!-- [H5T_pad_t_snip] --> @@ -1198,7 +1198,7 @@ H5_DLL herr_t H5Tlock(hid_t type_id); * the link(s) by which the new committed datatype is accessed and * the creation of any intermediate groups that may be missing. * - * Once commited, this datatype may be used to define the datatype + * Once committed, this datatype may be used to define the datatype * of any other dataset or attribute in the file. * * This function will not accept a datatype that cannot actually hold @@ -1208,7 +1208,7 @@ H5_DLL herr_t H5Tlock(hid_t type_id); * Committed datatypes are sometimes referred to as named datatypes. * * \version 1.8.7 Function modified in this release to reject datatypes that - * will not accomodate actual data, such as a compound datatype + * will not accommodate actual data, such as a compound datatype * with no fields or an enumerated datatype with no members. * * \since 1.8.0 @@ -1286,7 +1286,7 @@ H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id); * fields and enumerated datatypes with no members. * * \version 1.8.7 Function modified in this release to reject datatypes that - * will not accomodate actual data, such as a compound datatype + * will not accommodate actual data, such as a compound datatype * with no fields or an enumerated datatype with no members. * * \since 1.2.0 @@ -2679,7 +2679,6 @@ H5_DLL herr_t H5Tset_cset(hid_t type_id, H5T_cset_t cset); */ H5_DLL herr_t H5Tset_strpad(hid_t type_id, H5T_str_t strpad); -/* Type conversion database */ /** * \ingroup CONV * diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h index 90277cf..78e8543 100644 --- a/src/H5Zpublic.h +++ b/src/H5Zpublic.h @@ -687,4 +687,5 @@ typedef struct H5Z_class1_t { #ifdef __cplusplus } #endif -#endif + +#endif /* _H5Zpublic_H */ diff --git a/src/H5private.h b/src/H5private.h index b84845a..fbc78d2 100644 --- a/src/H5private.h +++ b/src/H5private.h @@ -604,216 +604,218 @@ typedef struct { #ifndef HDabort #define HDabort() abort() -#endif /* HDabort */ +#endif #ifndef HDabs #define HDabs(X) abs(X) -#endif /* HDabs */ +#endif #ifndef HDaccept -#define HDaccept(A, B, C) accept((A), (B), (C)) /* mirror VFD */ -#endif /* HDaccept */ +#define HDaccept(A, B, C) accept((A), (B), (C)) +#endif #ifndef HDaccess #define HDaccess(F, M) access(F, M) -#endif /* HDaccess */ +#endif #ifndef HDacos #define HDacos(X) acos(X) -#endif /* HDacos */ +#endif #ifndef HDalarm #ifdef H5_HAVE_ALARM #define HDalarm(N) alarm(N) -#else /* H5_HAVE_ALARM */ +#else #define HDalarm(N) (0) -#endif /* H5_HAVE_ALARM */ -#endif /* HDalarm */ +#endif +#endif #ifndef HDasctime #define HDasctime(T) asctime(T) -#endif /* HDasctime */ +#endif #ifndef HDasin #define HDasin(X) asin(X) -#endif /* HDasin */ +#endif #ifndef HDasprintf #define HDasprintf asprintf /*varargs*/ -#endif /* HDasprintf */ +#endif #ifndef HDassert #define HDassert(X) assert(X) -#endif /* HDassert */ +#endif #ifndef HDatan #define HDatan(X) atan(X) -#endif /* HDatan */ +#endif #ifndef HDatan2 #define HDatan2(X, Y) atan2(X, Y) -#endif /* HDatan2 */ +#endif #ifndef HDatexit #define HDatexit(F) atexit(F) -#endif /* HDatexit */ +#endif #ifndef HDatof #define HDatof(S) atof(S) -#endif /* HDatof */ +#endif #ifndef HDatoi #define HDatoi(S) atoi(S) -#endif /* HDatoi */ +#endif #ifndef HDatol #define HDatol(S) atol(S) -#endif /* HDatol */ +#endif #ifndef HDatoll #define HDatoll(S) atoll(S) -#endif /* HDatol */ +#endif #ifndef HDbind -#define HDbind(A, B, C) bind((A), (B), (C)) /* mirror VFD */ -#endif /* HDbind */ +#define HDbind(A, B, C) bind((A), (B), (C)) +#endif #ifndef HDbsearch #define HDbsearch(K, B, N, Z, F) bsearch(K, B, N, Z, F) -#endif /* HDbsearch */ +#endif #ifndef HDcalloc #define HDcalloc(N, Z) calloc(N, Z) -#endif /* HDcalloc */ +#endif #ifndef HDceil #define HDceil(X) ceil(X) -#endif /* HDceil */ +#endif #ifndef HDcfgetispeed #define HDcfgetispeed(T) cfgetispeed(T) -#endif /* HDcfgetispeed */ +#endif #ifndef HDcfgetospeed #define HDcfgetospeed(T) cfgetospeed(T) -#endif /* HDcfgetospeed */ +#endif #ifndef HDcfsetispeed #define HDcfsetispeed(T, S) cfsetispeed(T, S) -#endif /* HDcfsetispeed */ +#endif #ifndef HDcfsetospeed #define HDcfsetospeed(T, S) cfsetospeed(T, S) -#endif /* HDcfsetospeed */ +#endif #ifndef HDchdir #define HDchdir(S) chdir(S) -#endif /* HDchdir */ +#endif #ifndef HDchmod #define HDchmod(S, M) chmod(S, M) -#endif /* HDchmod */ +#endif #ifndef HDchown #define HDchown(S, O, G) chown(S, O, G) -#endif /* HDchown */ +#endif #ifndef HDclearerr #define HDclearerr(F) clearerr(F) -#endif /* HDclearerr */ +#endif #ifndef HDclock #define HDclock() clock() -#endif /* HDclock */ +#endif #ifndef HDclock_gettime #define HDclock_gettime(CID, TS) clock_gettime(CID, TS) -#endif /* HDclock_gettime */ +#endif #ifndef HDclose #define HDclose(F) close(F) -#endif /* HDclose */ +#endif #ifndef HDclosedir #define HDclosedir(D) closedir(D) -#endif /* HDclosedir */ +#endif #ifndef HDconnect -#define HDconnect(A, B, C) connect((A), (B), (C)) /* mirror VFD */ -#endif /* HDconnect */ +#define HDconnect(A, B, C) connect((A), (B), (C)) +#endif #ifndef HDcos #define HDcos(X) cos(X) -#endif /* HDcos */ +#endif #ifndef HDcosh #define HDcosh(X) cosh(X) -#endif /* HDcosh */ +#endif #ifndef HDcreat #define HDcreat(S, M) creat(S, M) -#endif /* HDcreat */ +#endif #ifndef HDctermid #define HDctermid(S) ctermid(S) -#endif /* HDctermid */ +#endif #ifndef HDctime #define HDctime(T) ctime(T) -#endif /* HDctime */ +#endif #ifndef HDcuserid #define HDcuserid(S) cuserid(S) -#endif /* HDcuserid */ +#endif #ifndef HDdifftime #ifdef H5_HAVE_DIFFTIME #define HDdifftime(X, Y) difftime(X, Y) -#else /* H5_HAVE_DIFFTIME */ +#else #define HDdifftime(X, Y) ((double)(X) - (double)(Y)) -#endif /* H5_HAVE_DIFFTIME */ -#endif /* HDdifftime */ +#endif +#endif #ifndef HDdiv #define HDdiv(X, Y) div(X, Y) -#endif /* HDdiv */ +#endif #ifndef HDdup #define HDdup(F) dup(F) -#endif /* HDdup */ +#endif #ifndef HDdup2 #define HDdup2(F, I) dup2(F, I) -#endif /* HDdup2 */ +#endif /* execl() variable arguments */ /* execle() variable arguments */ /* execlp() variable arguments */ #ifndef HDexecv #define HDexecv(S, AV) execv(S, AV) -#endif /* HDexecv */ +#endif #ifndef HDexecve #define HDexecve(S, AV, E) execve(S, AV, E) -#endif /* HDexecve */ +#endif #ifndef HDexecvp #define HDexecvp(S, AV) execvp(S, AV) -#endif /* HDexecvp */ +#endif #ifndef HDexit #define HDexit(N) exit(N) -#endif /* HDexit */ +#endif #ifndef HD_exit #define HD_exit(N) _exit(N) -#endif /* HD_exit */ +#endif #ifndef HDexp #define HDexp(X) exp(X) -#endif /* HDexp */ +#endif #ifndef HDexp2 #define HDexp2(X) exp2(X) -#endif /* HDexp2 */ +#endif #ifndef HDfabs #define HDfabs(X) fabs(X) -#endif /* HDfabs */ +#endif #ifndef HDfabsf #define HDfabsf(X) fabsf(X) -#endif /* HDfabsf */ +#endif #ifndef HDfabsl #define HDfabsl(X) fabsl(X) -#endif /* HDfabsl */ +#endif #ifndef HDfclose #define HDfclose(F) fclose(F) -#endif /* HDfclose */ +#endif #ifdef H5_HAVE_FCNTL #ifndef HDfcntl #define HDfcntl(F, C, ...) fcntl(F, C, __VA_ARGS__) -#endif /* HDfcntl */ -#endif /* H5_HAVE_FCNTL */ +#endif +#endif #ifndef HDfdopen #define HDfdopen(N, S) fdopen(N, S) -#endif /* HDfdopen */ +#endif #ifndef HDfeof #define HDfeof(F) feof(F) -#endif /* HDfeof */ +#endif #ifndef HDferror #define HDferror(F) ferror(F) -#endif /* HDferror */ +#endif #ifndef HDfflush #define HDfflush(F) fflush(F) -#endif /* HDfflush */ +#endif #ifndef HDfgetc #define HDfgetc(F) fgetc(F) -#endif /* HDfgetc */ +#endif #ifndef HDfgetpos #define HDfgetpos(F, P) fgetpos(F, P) -#endif /* HDfgetpos */ +#endif #ifndef HDfgets #define HDfgets(S, N, F) fgets(S, N, F) -#endif /* HDfgets */ +#endif #ifndef HDfileno #define HDfileno(F) fileno(F) -#endif /* HDfileno */ +#endif + /* Since flock is so prevalent, always build these functions * when possible to avoid them becoming dead code. */ #ifdef H5_HAVE_FCNTL H5_DLL int Pflock(int fd, int operation); -#endif /* H5_HAVE_FCNTL */ +#endif H5_DLL H5_ATTR_CONST int Nflock(int fd, int operation); + #ifndef HDflock /* NOTE: flock(2) is not present on all POSIX systems. * If it is not present, we try a flock() equivalent based on @@ -827,41 +829,43 @@ H5_DLL H5_ATTR_CONST int Nflock(int fd, int operation); #define HDflock(F, L) Pflock(F, L) #else #define HDflock(F, L) Nflock(F, L) -#endif /* H5_HAVE_FLOCK */ +#endif + #endif /* HDflock */ + #ifndef HDfloor #define HDfloor(X) floor(X) -#endif /* HDfloor */ +#endif #ifndef HDfmod #define HDfmod(X, Y) fmod(X, Y) -#endif /* HDfmod */ +#endif #ifndef HDfopen #define HDfopen(S, M) fopen(S, M) -#endif /* HDfopen */ +#endif #ifndef HDfork #define HDfork() fork() -#endif /* HDfork */ +#endif #ifndef HDfprintf #define HDfprintf fprintf #endif #ifndef HDfpathconf #define HDfpathconf(F, N) fpathconf(F, N) -#endif /* HDfpathconf */ +#endif #ifndef HDfputc #define HDfputc(C, F) fputc(C, F) -#endif /* HDfputc */ +#endif #ifndef HDfputs #define HDfputs(S, F) fputs(S, F) -#endif /* HDfputs */ +#endif #ifndef HDfread #define HDfread(M, Z, N, F) fread(M, Z, N, F) -#endif /* HDfread */ +#endif #ifndef HDfree #define HDfree(M) free(M) -#endif /* HDfree */ +#endif #ifndef HDfreopen #define HDfreopen(S, M, F) freopen(S, M, F) -#endif /* HDfreopen */ +#endif #ifndef HDfrexp #define HDfrexp(X, N) frexp(X, N) #endif @@ -885,19 +889,19 @@ H5_DLL H5_ATTR_CONST int Nflock(int fd, int operation); #endif #ifndef HDfseek #define HDfseek(F, O, W) fseeko(F, O, W) -#endif /* HDfseek */ +#endif #ifndef HDfsetpos #define HDfsetpos(F, P) fsetpos(F, P) -#endif /* HDfsetpos */ +#endif #ifndef HDfstat #define HDfstat(F, B) fstat(F, B) -#endif /* HDfstat */ +#endif #ifndef HDlstat #define HDlstat(S, B) lstat(S, B) -#endif /* HDlstat */ +#endif #ifndef HDstat #define HDstat(S, B) stat(S, B) -#endif /* HDstat */ +#endif #ifndef H5_HAVE_WIN32_API /* These definitions differ in Windows and are defined in @@ -912,532 +916,537 @@ typedef off_t h5_stat_size_t; #ifndef HDftell #define HDftell(F) ftell(F) -#endif /* HDftell */ +#endif #ifndef HDftruncate #define HDftruncate(F, L) ftruncate(F, L) -#endif /* HDftruncate */ +#endif #ifndef HDfwrite #define HDfwrite(M, Z, N, F) fwrite(M, Z, N, F) -#endif /* HDfwrite */ +#endif #ifndef HDgetc #define HDgetc(F) getc(F) -#endif /* HDgetc */ +#endif #ifndef HDgetchar #define HDgetchar() getchar() -#endif /* HDgetchar */ +#endif #ifndef HDgetcwd #define HDgetcwd(S, Z) getcwd(S, Z) -#endif /* HDgetcwd */ +#endif #ifndef HDgetdcwd #define HDgetdcwd(D, S, Z) getcwd(S, Z) -#endif /* HDgetdcwd */ +#endif + +/* Windows only - set to zero on other systems */ #ifndef HDgetdrive #define HDgetdrive() 0 -#endif /* HDgetdrive */ +#endif + #ifndef HDgetegid #define HDgetegid() getegid() -#endif /* HDgetegid() */ +#endif #ifndef HDgetenv #define HDgetenv(S) getenv(S) -#endif /* HDgetenv */ +#endif #ifndef HDgeteuid #define HDgeteuid() geteuid() -#endif /* HDgeteuid */ +#endif #ifndef HDgetgid #define HDgetgid() getgid() -#endif /* HDgetgid */ +#endif #ifndef HDgetgrgid #define HDgetgrgid(G) getgrgid(G) -#endif /* HDgetgrgid */ +#endif #ifndef HDgetgrnam #define HDgetgrnam(S) getgrnam(S) -#endif /* HDgetgrnam */ +#endif #ifndef HDgetgroups #define HDgetgroups(Z, G) getgroups(Z, G) -#endif /* HDgetgroups */ +#endif #ifndef HDgethostbyaddr -#define HDgethostbyaddr(A, B, C) gethostbyaddr((A), (B), (C)) /* mirror VFD */ -#endif /* HDgethostbyaddr */ +#define HDgethostbyaddr(A, B, C) gethostbyaddr((A), (B), (C)) +#endif #ifndef HDgethostname #define HDgethostname(N, L) gethostname(N, L) -#endif /* HDgethostname */ +#endif #ifndef HDgetlogin #define HDgetlogin() getlogin() -#endif /* HDgetlogin */ +#endif #ifndef HDgetpgrp #define HDgetpgrp() getpgrp() -#endif /* HDgetpgrp */ +#endif #ifndef HDgetpid #define HDgetpid() getpid() -#endif /* HDgetpid */ +#endif #ifndef HDgetppid #define HDgetppid() getppid() -#endif /* HDgetppid */ +#endif #ifndef HDgetpwnam #define HDgetpwnam(S) getpwnam(S) -#endif /* HDgetpwnam */ +#endif #ifndef HDgetpwuid #define HDgetpwuid(U) getpwuid(U) -#endif /* HDgetpwuid */ +#endif #ifndef HDgetrusage #define HDgetrusage(X, S) getrusage(X, S) -#endif /* HDgetrusage */ +#endif /* Don't define HDgets - gets() was deprecated in C99 and removed in C11 */ #ifdef HDgets #undef HDgets -#endif /* HDgets */ +#endif #ifndef HDgettimeofday #define HDgettimeofday(S, P) gettimeofday(S, P) -#endif /* HDgettimeofday */ +#endif #ifndef HDgetuid #define HDgetuid() getuid() -#endif /* HDgetuid */ +#endif #ifndef HDgmtime #define HDgmtime(T) gmtime(T) -#endif /* HDgmtime */ +#endif #ifndef HDhtonl -#define HDhtonl(X) htonl((X)) /* mirror VFD */ -#endif /* HDhtonl */ +#define HDhtonl(X) htonl((X)) +#endif #ifndef HDhtons -#define HDhtons(X) htons((X)) /* mirror VFD */ -#endif /* HDhtons */ +#define HDhtons(X) htons((X)) +#endif #ifndef HDinet_addr -#define HDinet_addr(C) inet_addr((C)) /* mirror VFD */ -#endif /* HDinet_addr */ +#define HDinet_addr(C) inet_addr((C)) +#endif #ifndef HDinet_ntoa -#define HDinet_ntoa(C) inet_ntoa((C)) /* mirror VFD */ -#endif /* HDinet_ntoa */ +#define HDinet_ntoa(C) inet_ntoa((C)) +#endif #ifndef HDisalnum -#define HDisalnum(C) isalnum((int)(C)) /*cast for solaris warning*/ -#endif /* HDisalnum */ +#define HDisalnum(C) isalnum((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisalpha -#define HDisalpha(C) isalpha((int)(C)) /*cast for solaris warning*/ -#endif /* HDisalpha */ +#define HDisalpha(C) isalpha((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisatty #define HDisatty(F) isatty(F) -#endif /* HDisatty */ +#endif #ifndef HDiscntrl -#define HDiscntrl(C) iscntrl((int)(C)) /*cast for solaris warning*/ -#endif /* HDiscntrl */ +#define HDiscntrl(C) iscntrl((int)(C)) /* Cast for solaris warning */ +#endif #ifndef HDisdigit -#define HDisdigit(C) isdigit((int)(C)) /*cast for solaris warning*/ -#endif /* HDisdigit */ +#define HDisdigit(C) isdigit((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisgraph -#define HDisgraph(C) isgraph((int)(C)) /*cast for solaris warning*/ -#endif /* HDisgraph */ +#define HDisgraph(C) isgraph((int)(C)) /* Cast for Solaris warning*/ +#endif #ifndef HDislower -#define HDislower(C) islower((int)(C)) /*cast for solaris warning*/ -#endif /* HDislower */ +#define HDislower(C) islower((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisnan #define HDisnan(X) isnan(X) -#endif /* HDisnan */ +#endif #ifndef HDisprint -#define HDisprint(C) isprint((int)(C)) /*cast for solaris warning*/ -#endif /* HDisprint */ +#define HDisprint(C) isprint((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDispunct -#define HDispunct(C) ispunct((int)(C)) /*cast for solaris warning*/ -#endif /* HDispunct */ +#define HDispunct(C) ispunct((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisspace -#define HDisspace(C) isspace((int)(C)) /*cast for solaris warning*/ -#endif /* HDisspace */ +#define HDisspace(C) isspace((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisupper -#define HDisupper(C) isupper((int)(C)) /*cast for solaris warning*/ -#endif /* HDisupper */ +#define HDisupper(C) isupper((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDisxdigit -#define HDisxdigit(C) isxdigit((int)(C)) /*cast for solaris warning*/ -#endif /* HDisxdigit */ +#define HDisxdigit(C) isxdigit((int)(C)) /* Cast for Solaris warning */ +#endif #ifndef HDkill #define HDkill(P, S) kill(P, S) -#endif /* HDkill */ +#endif #ifndef HDlabs #define HDlabs(X) labs(X) -#endif /* HDlabs */ +#endif #ifndef HDldexp #define HDldexp(X, N) ldexp(X, N) -#endif /* HDldexp */ +#endif #ifndef HDldiv #define HDldiv(X, Y) ldiv(X, Y) -#endif /* HDldiv */ +#endif #ifndef HDlink #define HDlink(OLD, NEW) link(OLD, NEW) -#endif /* HDlink */ +#endif #ifndef HDlisten -#define HDlisten(A, B) listen((A), (B)) /* mirror VFD */ -#endif /* HDlisten */ +#define HDlisten(A, B) listen((A), (B)) +#endif #ifndef HDllround #define HDllround(V) llround(V) -#endif /* HDround */ +#endif #ifndef HDllroundf #define HDllroundf(V) llroundf(V) -#endif /* HDllroundf */ +#endif #ifndef HDllroundl #define HDllroundl(V) llroundl(V) -#endif /* HDllroundl */ +#endif #ifndef HDlocaleconv #define HDlocaleconv() localeconv() -#endif /* HDlocaleconv */ +#endif #ifndef HDlocaltime #define HDlocaltime(T) localtime(T) -#endif /* HDlocaltime */ +#endif #ifndef HDlog #define HDlog(X) log(X) -#endif /* HDlog */ +#endif #ifndef HDlog10 #define HDlog10(X) log10(X) -#endif /* HDlog10 */ +#endif #ifndef HDlongjmp #define HDlongjmp(J, N) longjmp(J, N) -#endif /* HDlongjmp */ +#endif #ifndef HDlround #define HDlround(V) lround(V) -#endif /* HDround */ +#endif #ifndef HDlroundf #define HDlroundf(V) lroundf(V) -#endif /* HDlroundf */ +#endif #ifndef HDlroundl #define HDlroundl(V) lroundl(V) -#endif /* HDroundl */ +#endif #ifndef HDlseek #define HDlseek(F, O, W) lseek(F, O, W) -#endif /* HDlseek */ +#endif #ifndef HDmalloc #define HDmalloc(Z) malloc(Z) -#endif /* HDmalloc */ +#endif #ifndef HDposix_memalign #define HDposix_memalign(P, A, Z) posix_memalign(P, A, Z) -#endif /* HDposix_memalign */ +#endif #ifndef HDmblen #define HDmblen(S, N) mblen(S, N) -#endif /* HDmblen */ +#endif #ifndef HDmbstowcs #define HDmbstowcs(P, S, Z) mbstowcs(P, S, Z) -#endif /* HDmbstowcs */ +#endif #ifndef HDmbtowc #define HDmbtowc(P, S, Z) mbtowc(P, S, Z) -#endif /* HDmbtowc */ +#endif #ifndef HDmemchr #define HDmemchr(S, C, Z) memchr(S, C, Z) -#endif /* HDmemchr */ +#endif #ifndef HDmemcmp #define HDmemcmp(X, Y, Z) memcmp(X, Y, Z) -#endif /* HDmemcmp */ +#endif #ifndef HDmemcpy #define HDmemcpy(X, Y, Z) memcpy(X, Y, Z) -#endif /* HDmemcpy */ +#endif #ifndef HDmemmove #define HDmemmove(X, Y, Z) memmove((char *)(X), (const char *)(Y), Z) -#endif /* HDmemmove */ +#endif #ifndef HDmemset #define HDmemset(X, C, Z) memset(X, C, Z) -#endif /* HDmemset */ +#endif #ifndef HDmkdir #define HDmkdir(S, M) mkdir(S, M) -#endif /* HDmkdir */ +#endif #ifndef HDmkfifo #define HDmkfifo(S, M) mkfifo(S, M) -#endif /* HDmkfifo */ +#endif #ifndef HDmktime #define HDmktime(T) mktime(T) -#endif /* HDmktime */ +#endif #ifndef HDmodf #define HDmodf(X, Y) modf(X, Y) -#endif /* HDmodf */ +#endif #ifndef HDnanosleep #define HDnanosleep(N, O) nanosleep(N, O) -#endif /* HDnanosleep */ +#endif #ifndef HDntohl -#define HDntohl(A) ntohl((A)) /* mirror VFD */ -#endif /* HDntohl */ +#define HDntohl(A) ntohl((A)) +#endif #ifndef HDntohs -#define HDntohs(A) ntohs((A)) /* mirror VFD */ -#endif /* HDntohs */ +#define HDntohs(A) ntohs((A)) +#endif #ifndef HDopen #define HDopen(F, ...) open(F, __VA_ARGS__) -#endif /* HDopen */ +#endif #ifndef HDopendir #define HDopendir(S) opendir(S) -#endif /* HDopendir */ +#endif #ifndef HDpathconf #define HDpathconf(S, N) pathconf(S, N) -#endif /* HDpathconf */ +#endif #ifndef HDpause #define HDpause() pause() -#endif /* HDpause */ +#endif #ifndef HDperror #define HDperror(S) perror(S) -#endif /* HDperror */ +#endif #ifndef HDpipe #define HDpipe(F) pipe(F) -#endif /* HDpipe */ +#endif #ifndef HDpow #define HDpow(X, Y) pow(X, Y) -#endif /* HDpow */ +#endif #ifndef HDpowf #define HDpowf(X, Y) powf(X, Y) -#endif /* HDpowf */ +#endif #ifndef HDpread #define HDpread(F, B, C, O) pread(F, B, C, O) -#endif /* HDpread */ +#endif #ifndef HDprintf -#define HDprintf printf -#endif /* HDprintf */ +#define HDprintf printf /*varargs*/ +#endif #ifndef HDputc #define HDputc(C, F) putc(C, F) -#endif /* HDputc*/ +#endif #ifndef HDputchar #define HDputchar(C) putchar(C) -#endif /* HDputchar */ +#endif #ifndef HDputs #define HDputs(S) puts(S) -#endif /* HDputs */ +#endif #ifndef HDpwrite #define HDpwrite(F, B, C, O) pwrite(F, B, C, O) -#endif /* HDpwrite */ +#endif #ifndef HDqsort #define HDqsort(M, N, Z, F) qsort(M, N, Z, F) -#endif /* HDqsort*/ +#endif #ifndef HDraise #define HDraise(N) raise(N) -#endif /* HDraise */ +#endif +/* clang-format off */ #ifdef H5_HAVE_RAND_R -#ifndef HDrandom -#define HDrandom() HDrand() -#endif /* HDrandom */ -H5_DLL int HDrand(void); -#ifndef HDsrandom -#define HDsrandom(S) HDsrand(S) -#endif /* HDsrandom */ -H5_DLL void HDsrand(unsigned int seed); +# ifndef HDrandom +# define HDrandom() HDrand() +# endif + H5_DLL int HDrand(void); +# ifndef HDsrandom +# define HDsrandom(S) HDsrand(S) +# endif + H5_DLL void HDsrand(unsigned int seed); #elif defined(H5_HAVE_RANDOM) -#ifndef HDrand -#define HDrand() random() -#endif /* HDrand */ -#ifndef HDrandom -#define HDrandom() random() -#endif /* HDrandom */ -#ifndef HDsrand -#define HDsrand(S) srandom(S) -#endif /* HDsrand */ -#ifndef HDsrandom -#define HDsrandom(S) srandom(S) -#endif /* HDsrandom */ -#else /* H5_HAVE_RANDOM */ -#ifndef HDrand -#define HDrand() rand() -#endif /* HDrand */ -#ifndef HDrandom -#define HDrandom() rand() -#endif /* HDrandom */ -#ifndef HDsrand -#define HDsrand(S) srand(S) -#endif /* HDsrand */ -#ifndef HDsrandom -#define HDsrandom(S) srand(S) -#endif /* HDsrandom */ -#endif /* H5_HAVE_RANDOM */ +# ifndef HDrand +# define HDrand() random() +# endif +# ifndef HDrandom +# define HDrandom() random() +# endif +# ifndef HDsrand +# define HDsrand(S) srandom(S) +# endif +# ifndef HDsrandom +# define HDsrandom(S) srandom(S) +# endif +#else +# ifndef HDrand +# define HDrand() rand() +# endif +# ifndef HDrandom +# define HDrandom() rand() +# endif +# ifndef HDsrand +# define HDsrand(S) srand(S) +# endif +# ifndef HDsrandom +# define HDsrandom(S) srand(S) +# endif +#endif +/* clang-format on */ #ifndef HDread #define HDread(F, M, Z) read(F, M, Z) -#endif /* HDread */ +#endif #ifndef HDreaddir #define HDreaddir(D) readdir(D) -#endif /* HDreaddir */ +#endif #ifndef HDrealloc #define HDrealloc(M, Z) realloc(M, Z) -#endif /* HDrealloc */ +#endif #ifndef HDrealpath #define HDrealpath(F1, F2) realpath(F1, F2) -#endif /* HDrealloc */ +#endif #ifndef HDremove #define HDremove(S) remove(S) -#endif /* HDremove */ +#endif #ifndef HDrename #define HDrename(OLD, NEW) rename(OLD, NEW) -#endif /* HDrename */ +#endif #ifndef HDrewind #define HDrewind(F) rewind(F) -#endif /* HDrewind */ +#endif #ifndef HDrewinddir #define HDrewinddir(D) rewinddir(D) -#endif /* HDrewinddir */ +#endif #ifndef HDround #define HDround(V) round(V) -#endif /* HDround */ +#endif #ifndef HDroundf #define HDroundf(V) roundf(V) -#endif /* HDroundf */ +#endif #ifndef HDroundl #define HDroundl(V) roundl(V) -#endif /* HDroundl */ +#endif #ifndef HDrmdir #define HDrmdir(S) rmdir(S) -#endif /* HDrmdir */ +#endif /* scanf() variable arguments */ #ifndef HDselect #define HDselect(N, RD, WR, ER, T) select(N, RD, WR, ER, T) -#endif /* HDsetbuf */ +#endif #ifndef HDsetbuf #define HDsetbuf(F, S) setbuf(F, S) -#endif /* HDsetbuf */ +#endif #ifndef HDsetenv #define HDsetenv(N, V, O) setenv(N, V, O) -#endif /* HDsetenv */ +#endif #ifndef HDsetgid #define HDsetgid(G) setgid(G) -#endif /* HDsetgid */ +#endif #ifndef HDsetjmp #define HDsetjmp(J) setjmp(J) -#endif /* HDsetjmp */ +#endif #ifndef HDsetlocale #define HDsetlocale(N, S) setlocale(N, S) -#endif /* HDsetlocale */ +#endif #ifndef HDsetpgid #define HDsetpgid(P, PG) setpgid(P, PG) -#endif /* HDsetpgid */ +#endif #ifndef HDsetsid #define HDsetsid() setsid() -#endif /* HDsetsid */ +#endif #ifndef HDsetsockopt -#define HDsetsockopt(A, B, C, D, E) setsockopt((A), (B), (C), (D), (E)) /* mirror VFD */ -#endif /* HDsetsockopt */ +#define HDsetsockopt(A, B, C, D, E) setsockopt((A), (B), (C), (D), (E)) +#endif #ifndef HDsetuid #define HDsetuid(U) setuid(U) -#endif /* HDsetuid */ +#endif #ifndef HDsetvbuf #define HDsetvbuf(F, S, M, Z) setvbuf(F, S, M, Z) -#endif /* HDsetvbuf */ +#endif #ifndef HDshutdown -#define HDshutdown(A, B) shutdown((A), (B)) /* mirror VFD */ -#endif /* HDshutdown */ +#define HDshutdown(A, B) shutdown((A), (B)) +#endif #ifndef HDsigaction #define HDsigaction(S, A, O) sigaction((S), (A), (O)) -#endif /* HDsigaction */ +#endif #ifndef HDsigaddset #define HDsigaddset(S, N) sigaddset(S, N) -#endif /* HDsigaddset */ +#endif #ifndef HDsigdelset #define HDsigdelset(S, N) sigdelset(S, N) -#endif /* HDsigdelset */ +#endif #ifndef HDsigemptyset #define HDsigemptyset(S) sigemptyset(S) -#endif /* HDsigemptyset */ +#endif #ifndef HDsigfillset #define HDsigfillset(S) sigfillset(S) -#endif /* HDsigfillset */ +#endif #ifndef HDsigismember #define HDsigismember(S, N) sigismember(S, N) -#endif /* HDsigismember */ +#endif #ifndef HDsiglongjmp #define HDsiglongjmp(J, N) siglongjmp(J, N) -#endif /* HDsiglongjmp */ +#endif #ifndef HDsignal #define HDsignal(N, F) signal(N, F) -#endif /* HDsignal */ +#endif #ifndef HDsigpending #define HDsigpending(S) sigpending(S) -#endif /* HDsigpending */ +#endif #ifndef HDsigprocmask #define HDsigprocmask(H, S, O) sigprocmask(H, S, O) -#endif /* HDsigprocmask */ +#endif #ifndef HDsigsetjmp #define HDsigsetjmp(J, N) sigsetjmp(J, N) -#endif /* HDsigsetjmp */ +#endif #ifndef HDsigsuspend #define HDsigsuspend(S) sigsuspend(S) -#endif /* HDsigsuspend */ +#endif #ifndef HDsin #define HDsin(X) sin(X) -#endif /* HDsin */ +#endif #ifndef HDsinh #define HDsinh(X) sinh(X) -#endif /* HDsinh */ +#endif #ifndef HDsleep #define HDsleep(N) sleep(N) -#endif /* HDsleep */ +#endif #ifndef HDsnprintf #define HDsnprintf snprintf /*varargs*/ -#endif /* HDsnprintf */ +#endif #ifndef HDsocket -#define HDsocket(A, B, C) socket((A), (B), (C)) /* mirror VFD */ -#endif /* HDsocket */ +#define HDsocket(A, B, C) socket((A), (B), (C)) +#endif #ifndef HDsprintf #define HDsprintf sprintf /*varargs*/ -#endif /* HDsprintf */ +#endif #ifndef HDsqrt #define HDsqrt(X) sqrt(X) -#endif /* HDsqrt */ +#endif #ifndef HDsscanf #define HDsscanf(S, FMT, ...) sscanf(S, FMT, __VA_ARGS__) -#endif /* HDsscanf */ +#endif #ifndef HDstrcat #define HDstrcat(X, Y) strcat(X, Y) -#endif /* HDstrcat */ +#endif #ifndef HDstrchr #define HDstrchr(S, C) strchr(S, C) -#endif /* HDstrchr */ +#endif #ifndef HDstrcmp #define HDstrcmp(X, Y) strcmp(X, Y) -#endif /* HDstrcmp */ +#endif #ifndef HDstrcasecmp #define HDstrcasecmp(X, Y) strcasecmp(X, Y) -#endif /* HDstrcasecmp */ +#endif #ifndef HDstrcoll #define HDstrcoll(X, Y) strcoll(X, Y) -#endif /* HDstrcoll */ +#endif #ifndef HDstrcpy #define HDstrcpy(X, Y) strcpy(X, Y) -#endif /* HDstrcpy */ +#endif #ifndef HDstrcspn #define HDstrcspn(X, Y) strcspn(X, Y) -#endif /* HDstrcspn */ +#endif #ifndef HDstrdup #define HDstrdup(S) strdup(S) -#endif /* HDstrdup */ +#endif #ifndef HDstrerror #define HDstrerror(N) strerror(N) -#endif /* HDstrerror */ +#endif #ifndef HDstrftime #define HDstrftime(S, Z, F, T) strftime(S, Z, F, T) -#endif /* HDstrftime */ +#endif #ifndef HDstrlen #define HDstrlen(S) strlen(S) -#endif /* HDstrlen */ +#endif #ifndef HDstrncat #define HDstrncat(X, Y, Z) strncat(X, Y, Z) -#endif /* HDstrncat */ +#endif #ifndef HDstrncmp #define HDstrncmp(X, Y, Z) strncmp(X, Y, Z) -#endif /* HDstrncmp */ +#endif #ifndef HDstrncpy #define HDstrncpy(X, Y, Z) strncpy(X, Y, Z) -#endif /* HDstrncpy */ +#endif #ifndef HDstrpbrk #define HDstrpbrk(X, Y) strpbrk(X, Y) -#endif /* HDstrpbrk */ +#endif #ifndef HDstrrchr #define HDstrrchr(S, C) strrchr(S, C) -#endif /* HDstrrchr */ +#endif #ifndef HDstrspn #define HDstrspn(X, Y) strspn(X, Y) -#endif /* HDstrspn */ +#endif #ifndef HDstrstr #define HDstrstr(X, Y) strstr(X, Y) -#endif /* HDstrstr */ +#endif #ifndef HDstrtod #define HDstrtod(S, R) strtod(S, R) -#endif /* HDstrtod */ +#endif #ifndef HDstrtok #define HDstrtok(X, Y) strtok(X, Y) -#endif /* HDstrtok */ +#endif #ifndef HDstrtok_r #define HDstrtok_r(X, Y, Z) strtok_r(X, Y, Z) -#endif /* HDstrtok */ +#endif #ifndef HDstrtol #define HDstrtol(S, R, N) strtol(S, R, N) -#endif /* HDstrtol */ +#endif #ifndef HDstrtoll #ifdef H5_HAVE_STRTOLL #define HDstrtoll(S, R, N) strtoll(S, R, N) @@ -1447,96 +1456,97 @@ H5_DLL int64_t HDstrtoll(const char *s, const char **rest, int base); #endif #ifndef HDstrtoul #define HDstrtoul(S, R, N) strtoul(S, R, N) -#endif /* HDstrtoul */ +#endif #ifndef HDstrtoull #define HDstrtoull(S, R, N) strtoull(S, R, N) -#endif /* HDstrtoul */ +#endif #ifndef HDstrtoumax #define HDstrtoumax(S, R, N) strtoumax(S, R, N) -#endif /* HDstrtoumax */ +#endif #ifndef HDstrxfrm #define HDstrxfrm(X, Y, Z) strxfrm(X, Y, Z) -#endif /* HDstrxfrm */ +#endif #ifdef H5_HAVE_SYMLINK #ifndef HDsymlink #define HDsymlink(F1, F2) symlink(F1, F2) -#endif /* HDsymlink */ -#endif /* H5_HAVE_SYMLINK */ +#endif +#endif #ifndef HDsysconf #define HDsysconf(N) sysconf(N) -#endif /* HDsysconf */ +#endif #ifndef HDsystem #define HDsystem(S) system(S) -#endif /* HDsystem */ +#endif #ifndef HDtan #define HDtan(X) tan(X) -#endif /* HDtan */ +#endif #ifndef HDtanh #define HDtanh(X) tanh(X) -#endif /* HDtanh */ +#endif #ifndef HDtcdrain #define HDtcdrain(F) tcdrain(F) -#endif /* HDtcdrain */ +#endif #ifndef HDtcflow #define HDtcflow(F, A) tcflow(F, A) -#endif /* HDtcflow */ +#endif #ifndef HDtcflush #define HDtcflush(F, N) tcflush(F, N) -#endif /* HDtcflush */ +#endif #ifndef HDtcgetattr #define HDtcgetattr(F, T) tcgetattr(F, T) -#endif /* HDtcgetattr */ +#endif #ifndef HDtcgetpgrp #define HDtcgetpgrp(F) tcgetpgrp(F) -#endif /* HDtcgetpgrp */ +#endif #ifndef HDtcsendbreak #define HDtcsendbreak(F, N) tcsendbreak(F, N) -#endif /* HDtcsendbreak */ +#endif #ifndef HDtcsetattr #define HDtcsetattr(F, O, T) tcsetattr(F, O, T) -#endif /* HDtcsetattr */ +#endif #ifndef HDtcsetpgrp #define HDtcsetpgrp(F, N) tcsetpgrp(F, N) -#endif /* HDtcsetpgrp */ +#endif #ifndef HDtime #define HDtime(T) time(T) -#endif /* HDtime */ +#endif #ifndef HDtimes #define HDtimes(T) times(T) -#endif /* HDtimes*/ +#endif #ifndef HDtmpfile #define HDtmpfile() tmpfile() -#endif /* HDtmpfile */ +#endif #ifndef HDtmpnam #define HDtmpnam(S) tmpnam(S) -#endif /* HDtmpnam */ +#endif #ifndef HDtolower #define HDtolower(C) tolower(C) -#endif /* HDtolower */ +#endif #ifndef HDtoupper #define HDtoupper(C) toupper(C) -#endif /* HDtoupper */ +#endif #ifndef HDttyname #define HDttyname(F) ttyname(F) -#endif /* HDttyname */ +#endif #ifndef HDtzset #define HDtzset() tzset() -#endif /* HDtzset */ +#endif #ifndef HDumask #define HDumask(N) umask(N) -#endif /* HDumask */ +#endif #ifndef HDuname #define HDuname(S) uname(S) -#endif /* HDuname */ +#endif #ifndef HDungetc #define HDungetc(C, F) ungetc(C, F) -#endif /* HDungetc */ +#endif #ifndef HDunlink #define HDunlink(S) unlink(S) -#endif /* HDunlink */ +#endif #ifndef HDutime #define HDutime(S, T) utime(S, T) #endif + #ifndef HDvasprintf #ifdef H5_HAVE_VASPRINTF #define HDvasprintf(RET, FMT, A) vasprintf(RET, FMT, A) @@ -1544,45 +1554,46 @@ H5_DLL int64_t HDstrtoll(const char *s, const char **rest, int base); H5_DLL int HDvasprintf(char **bufp, const char *fmt, va_list _ap); #endif #endif + #ifndef HDva_arg #define HDva_arg(A, T) va_arg(A, T) -#endif /* HDva_arg */ +#endif #ifndef HDva_copy #define HDva_copy(D, S) va_copy(D, S) -#endif /* HDva_copy */ +#endif #ifndef HDva_end #define HDva_end(A) va_end(A) -#endif /* HDva_end */ +#endif #ifndef HDva_start #define HDva_start(A, P) va_start(A, P) -#endif /* HDva_start */ +#endif #ifndef HDvfprintf #define HDvfprintf(F, FMT, A) vfprintf(F, FMT, A) -#endif /* HDvfprintf */ +#endif #ifndef HDvprintf #define HDvprintf(FMT, A) vprintf(FMT, A) -#endif /* HDvprintf */ +#endif #ifndef HDvsprintf #define HDvsprintf(S, FMT, A) vsprintf(S, FMT, A) -#endif /* HDvsprintf */ +#endif #ifndef HDvsnprintf #define HDvsnprintf(S, N, FMT, A) vsnprintf(S, N, FMT, A) -#endif /* HDvsnprintf */ +#endif #ifndef HDwait #define HDwait(W) wait(W) -#endif /* HDwait */ +#endif #ifndef HDwaitpid #define HDwaitpid(P, W, O) waitpid(P, W, O) -#endif /* HDwaitpid */ +#endif #ifndef HDwcstombs #define HDwcstombs(S, P, Z) wcstombs(S, P, Z) -#endif /* HDwcstombs */ +#endif #ifndef HDwctomb #define HDwctomb(S, C) wctomb(S, C) -#endif /* HDwctomb */ +#endif #ifndef HDwrite #define HDwrite(F, M, Z) write(F, M, Z) -#endif /* HDwrite */ +#endif /* Macro for "stringizing" an integer in the C preprocessor (use H5_TOSTRING) */ /* (use H5_TOSTRING, H5_STRINGIZE is just part of the implementation) */ @@ -1970,7 +1981,7 @@ extern H5_api_t H5_g; #define H5_API_LOCK #define H5_API_UNLOCK -/* disable cancelability (sequential version) */ +/* disable cancellability (sequential version) */ #define H5_API_UNSET_CANCEL #define H5_API_SET_CANCEL diff --git a/src/H5win32defs.h b/src/H5win32defs.h index 0617643..068b3f5 100644 --- a/src/H5win32defs.h +++ b/src/H5win32defs.h @@ -55,6 +55,7 @@ typedef __int64 h5_stat_size_t; #else #define HDopen(S, F, ...) Wopen_utf8(S, F, ##__VA_ARGS__) #endif + #define HDread(F, M, Z) _read(F, M, Z) #define HDremove(S) Wremove_utf8(S) #define HDrmdir(S) _rmdir(S) diff --git a/test/cache_common.h b/test/cache_common.h index f184ebf..b8ca2e1 100644 --- a/test/cache_common.h +++ b/test/cache_common.h @@ -345,7 +345,7 @@ typedef struct test_entry_t { int pin_type[MAX_PINS]; /* array of the types of entries * pinned by this entry. */ - int pin_idx[MAX_PINS]; /* array of the indicies of + int pin_idx[MAX_PINS]; /* array of the indices of * entries pinned by this entry. */ int num_flush_ops; /* integer field containing the @@ -391,7 +391,7 @@ typedef struct test_entry_t { unsigned flush_dep_npar; /* Number of flush dependency parents */ unsigned flush_dep_nchd; /* Number of flush dependency children */ unsigned - flush_dep_ndirty_chd; /* Number of dirty flush dependency children (including granchildren, etc.) */ + flush_dep_ndirty_chd; /* Number of dirty flush dependency children (including grandchildren, etc.) */ hbool_t pinned_from_client; /* entry was pinned by client call */ hbool_t pinned_from_cache; /* entry was pinned by cache internally */ unsigned flush_order; /* Order that entry was flushed in */ diff --git a/tools/lib/h5diff.h b/tools/lib/h5diff.h index f14bcda..e811041 100644 --- a/tools/lib/h5diff.h +++ b/tools/lib/h5diff.h @@ -74,7 +74,7 @@ typedef struct { struct exclude_path_list *exclude_attr; /* keep exclude attribute list */ int count_bool; /* count, compare up to count */ hsize_t count; /* count value */ - diff_err_t err_stat; /* an error ocurred (2, error, 1, differences, 0, no error) */ + diff_err_t err_stat; /* an error occurred (2, error, 1, differences, 0, no error) */ hsize_t nelmts; /* total number of elements */ hsize_t hs_nelmts; /* number of elements to read at a time*/ int rank; /* dimensionality */ diff --git a/tools/lib/h5tools.h b/tools/lib/h5tools.h index d75506d..8d2b865 100644 --- a/tools/lib/h5tools.h +++ b/tools/lib/h5tools.h @@ -240,7 +240,7 @@ typedef struct h5tool_format_t { * * fmt_schar: The printf() format to use when rendering data which is * typed `signed char'. The default is `%d'. This format is - * used ony if the `ascii' field is zero. + * used only if the `ascii' field is zero. * * fmt_uchar: The printf() format to use when rendering data which is * typed `unsigned char'. The default is `%u'. This format @@ -411,9 +411,9 @@ typedef struct h5tool_format_t { * sep: Each integer in the index list will be separated from the * others by this string, which defaults to a comma. * - * fmt: After the index values are formated individually and + * fmt: After the index values are formatted individually and * separated from one another by some string, the entire - * resulting string will be formated according to this + * resulting string will be formatted according to this * printf(3c) format which should include a format for a * character string. The default is "%s". */ @@ -483,7 +483,7 @@ typedef struct h5tool_format_t { const char *line_suf; /*string to append to each line */ const char *line_sep; /*separates lines */ int line_multi_new; /*split multi-line outputs? */ - const char *line_indent; /*for extra identation if we need it*/ + const char *line_indent; /*for extra indentation if we need it*/ /*used to skip the first set of checks for line length*/ int skip_first; @@ -579,7 +579,7 @@ typedef enum { } driver_idx; /* The following include, h5tools_str.h, must be after the - * above stucts are defined. There is a dependency in the following + * above structs are defined. There is a dependency in the following * include that hasn't been identified yet. */ #include "h5tools_str.h" diff --git a/tools/lib/h5tools_utils.h b/tools/lib/h5tools_utils.h index b54ed85..4656acf 100644 --- a/tools/lib/h5tools_utils.h +++ b/tools/lib/h5tools_utils.h @@ -146,7 +146,7 @@ typedef enum toolname_t { TOOL__H5DUMP /* add as necessary */ } h5tool_toolname_t; -/* this struct can be used to differntiate among tools */ +/* this struct can be used to differentiate among tools */ typedef struct { h5tool_toolname_t toolname; int msg_mode; diff --git a/tools/lib/h5trav.h b/tools/lib/h5trav.h index 8708bc9..8e76d23 100644 --- a/tools/lib/h5trav.h +++ b/tools/lib/h5trav.h @@ -87,7 +87,7 @@ typedef struct trav_link_t { } trav_link_t; /*------------------------------------------------------------------------- - * struct to store basic info needed for the h5trav table traversal algorythm + * struct to store basic info needed for the h5trav table traversal algorithm *------------------------------------------------------------------------- */ |
