From 393410babb8ad1586968db27725b5d002ca87d20 Mon Sep 17 00:00:00 2001
From: vchoi-hdfgroup <55293060+vchoi-hdfgroup@users.noreply.github.com>
Date: Wed, 19 Aug 2026 00:22:44 -0700
Subject: [PATCH] Fix issue #6605: (#6615)
--Fix overloaded N and inconsistent # indexing in V2 B-tree section
--Clean up Global Heap section as well.
---
docs/doxygen/dox/H5.format.4.0.dox | 122 ++++++++++++++++-------------
1 file changed, 69 insertions(+), 53 deletions(-)
diff --git a/docs/doxygen/dox/H5.format.4.0.dox b/docs/doxygen/dox/H5.format.4.0.dox
index b4558211976..8a404c8f149 100644
--- a/docs/doxygen/dox/H5.format.4.0.dox
+++ b/docs/doxygen/dox/H5.format.4.0.dox
@@ -1221,37 +1221,37 @@ the header).
| Version |
Type |
- Records 0, 1, 2...N-1 (variable size) |
+ Record \#0, Record \#1, ... Record \#(R-1) (variable size) |
-
Child Node Pointer 0O
|
+
Child Node Pointer \#0O
|
-
Number of Records N0 for Child Node 0 (variable size) |
+
Number of Records for Child Node \#0 (variable size) |
-
Total Number of Records for Child Node 0 (optional, variable size) |
+
Total Number of Records for Child Node \#0 (optional, variable size) |
-
Child Node Pointer 1O
|
+
Child Node Pointer \#1O
|
-
Number of Records N1 for Child Node 1 (variable size) |
+
Number of Records for Child Node \#1 (variable size) |
-
Total Number of Records for Child Node 1 (optional, variable size) |
+
Total Number of Records for Child Node \#1 (optional, variable size) |
| ... |
-
Child Node Pointer NO
|
+
Child Node Pointer \#RO
|
-
Number of Records Nn for Child Node N (variable size) |
+
Number of Records for Child Node \#R (variable size) |
-
Total Number of Records for Child Node N (optional, variable size) |
+
Total Number of Records for Child Node \#R (optional, variable size) |
| Checksum |
@@ -1281,35 +1281,45 @@ the header).
the header.
- | Records |
- The size of this field is determined by the number of records for this node and the record size
- (from the header). The format of records depends on the type of B-tree. |
+ Record \#i (i = 0 to (R-1)) |
+ Let R be the number of records for this node: for the root node, R is given
+ by the B-tree Header's Number of Records in Root Node field; for any other node,
+ R is given by the Number of Records for Child Node \#j field in this node's
+ parent, specifically the pointer triplet whose Child Node Pointer \#j gave this
+ node's address. The size of this field is
+ determined by R and the Record Size (the latter always from the header); the
+ format of records depends on the type of B-tree. Because each internal node has one more child
+ pointer triplet than it has records, this node has R+1 child node pointers, indexed
+ \#0 through \#R (see below). |
- | Child Node Pointer |
- This field is the address of the child node pointed to by the internal node. |
+ Child Node Pointer \#j (j = 0 to R) |
+ This field is the address of child \#j pointed to by this internal node. Together with the
+ following field, Number of Records for Child Node \#j, and (where present) the field
+ after that, Total Number of Records for Child Node \#j, this forms what the rest of
+ this table calls a pointer triplet — the repeating group of per-child fields
+ between Child Node Pointer \#j and Child Node Pointer \#(j+1). |
- | Number of Records in Child Node |
- This is the number of records in the child node pointed to by the corresponding Node Pointer.
+ | Number of Records for Child Node \#j (j = 0 to R) |
+ This is the number of records in child \#j (see the Child Node Pointer field above).
The number of bytes used to store this field is determined by the maximum possible number of records able
to be stored in the child node.
The maximum number of records in a child node is computed in the following way:
- Subtract the fixed size overhead for the child node (for example, its signature, version,
- checksum, and so on and one pointer triplet of information for the child node
- (because there is one more pointer triplet than records in each internal node)) from the size
- of nodes for the B-tree.
- - Divide that result by the size of a record plus the pointer triplet of information stored to
- reach each child node from this node.
+ checksum, and so on, and one pointer triplet of information for the child node, per the
+ R+1 child pointers noted above) from the Node Size (see the header).
+ - Divide that result by the sum of the Record Size and the pointer triplet of information
+ stored to reach each child node from this node.
Note that leaf nodes do not encode any child pointer triplets, so the maximum number of records in a
- leaf node is just the node size minus the leaf node overhead, divided by the record size.
- Also note that the first level of internal nodes above the leaf nodes do not encode the Total
- Number of Records in Child Node value in the child pointer triplets (since it is the same as
- the Number of Records in Child Node), so the maximum number of records in these nodes is
- computed with the equation above, but using (Child Pointer, Number of Records in Child
- Node) pairs instead of triplets.
+ leaf node is just the Node Size minus the leaf node overhead, divided by the Record Size.
+ Also note that the first level of internal nodes above the leaf nodes — the “twig”
+ internal nodes — do not encode a Total Number of Records for Child Node \#j value
+ (since it would be the same as Number of Records for Child Node \#j), so the maximum number
+ of records in these nodes is computed with the equation above, but using (Child Node Pointer
+ \#j, Number of Records for Child Node \#j) pairs instead of full triplets.
The number of bytes used to encode this field is the least number of bytes required to encode the
maximum number of records in a child node value for the child nodes below this level in the B-tree.
For example, if the maximum number of child records is 123, one byte will be used to encode these
@@ -1318,11 +1328,10 @@ the header).
is 8 (in other words, an unsigned 64-bit integer). |
- | Total Number of Records in Child Node |
- This is the total number of records for the node pointed to by the corresponding Node Pointer
- and all its children. This field exists only in nodes whose depth in the B-tree node is greater than 1
- (in other words, the “twig” internal nodes, just above leaf nodes, do not store this field
- in their child node pointers).
+ | Total Number of Records for Child Node \#j (j = 0 to R) |
+ This is the total number of records for child \#j and all its descendants. This field exists
+ only in nodes whose depth in the B-tree node is greater than 1; see the note about
+ “twig” internal nodes under Number of Records for Child Node \#j above.
The number of bytes used to store this field is determined by the maximum possible number of records
able to be stored in the child node and its descendants.
The maximum possible number of records able to be stored in a child node and its descendants is
@@ -1332,7 +1341,7 @@ the header).
maximum possible number of records in child node pointers for the level of nodes two levels above
leaf nodes. This process is continued up to any level in the B-tree.
The number of bytes used to encode this value is computed in the same way as for the Number
- of Records in Child Node field. |
+ of Records for Child Node \#j field.
| Checksum |
@@ -1354,7 +1363,7 @@ the header).
| Version |
Type |
- Record 0, 1, 2...N-1 (variable size) |
+ Record \#0, Record \#1, ... Record \#(R-1) (variable size) |
| Checksum |
@@ -1382,9 +1391,13 @@ the header).
the header.
- | Records |
- The size of this field is determined by the number of records for this node and the record size
- (from the header). The format of records depends on the type of B-tree. |
+ Record \#i (i = 0 to (R-1)) |
+ Let R be the number of records for this node: for the root node, R is given
+ by the B-tree Header's Number of Records in Root Node field; for any other node,
+ R is given by the Number of Records for Child Node \#j field in this leaf's
+ parent (always a “twig” internal node, so this is one of a pointer pair, not a full
+ triplet). The size of this field is determined by R and the Record Size (the
+ latter always from the header); the format of records depends on the type of B-tree. |
| Checksum |
@@ -2386,10 +2399,10 @@ as an atomic object, addressing goal A.
When a global heap object is deleted from a collection (which occurs when its reference count falls to zero),
objects located after the deleted object in the collection are packed down toward the beginning of the
-collection and the collection’s global heap object 0 is created (if possible) or its size is increased
+collection and the collection’s global heap object \#0 is created (if possible) or its size is increased
to account for the recently freed space. There are no gaps between objects in each collection, with the possible
exception of the final space in the collection, if it is not large enough to hold the header for the
-collection’s global heap object 0. These features address goal C.
+collection’s global heap object \#0. These features address goal C.
The HDF5 library creates global heap collections as needed, so there may be multiple collections throughout
the file. The set of all of them is abstractly called the “global heap”, although they do not
@@ -2417,19 +2430,19 @@ global heap ID. The format for global heap IDs is described at the end of this s
Collection SizeL
|
-
Global Heap Object 1
|
+
Global Heap Object \#1
|
-
Global Heap Object 2
|
+
Global Heap Object \#2
|
...
|
-
Global Heap Object N
|
+
Global Heap Object \#N
|
-
Global Heap Object 0 (free space)
|
+
Global Heap Object \#0 (free space)
|
\li Items marked with an ‘L’ in the above table are of the size specified in
@@ -2459,16 +2472,19 @@ global heap ID. The format for global heap IDs is described at the end of this s
about each heap object).
- | Global Heap Object 1 through N |
- The objects are stored in any order with no intervening unused space. |
+ Global Heap Object \#1 through \#N |
+ Let N be the number of real (non-free-space) objects in this collection. N is not
+ stored explicitly; a reader determines it by parsing objects sequentially, in the order stored, until
+ either the free-space object (Global Heap Object \#0, Heap Object Index 0) is reached or the
+ Collection Size is exhausted. The objects are stored in any order with no intervening unused space. |
- | Global Heap Object 0 |
- Global Heap Object 0 (zero), when present, represents the free space in the collection. Free space always
- appears at the end of the collection. If the free space is too small to store the header for Object 0
- (described below) then the header is implied and is not written.
- The field Object Size for Object 0 indicates the amount of possible free space in the collection
- including the 16-byte header size of Object 0. |
+ Global Heap Object \#0 |
+ Global Heap Object \#0 (zero), when present, represents the free space in the collection. Free space
+ always appears at the end of the collection. If the free space is too small to store the header for
+ Object \#0 (described below) then the header is implied and is not written.
+ The field Object Size for Object \#0 indicates the amount of possible free space in the
+ collection including the 16-byte header size of Object \#0. |
@@ -2512,7 +2528,7 @@ global heap ID. The format for global heap IDs is described at the end of this s
| Reference Count |
All heap objects have a reference count field. An object which is referenced from some other part of the
- file will have a positive reference count. The reference count for Object 0 is always zero. |
+ file will have a positive reference count. The reference count for Object \#0 is always zero.
| Reserved |