[filter-config 5/8] Add h5dump --filter-params to show filter configuration strings by brtnfld · Pull Request #6702 · HDFGroup/hdf5

brtnfld · 2026-09-26T08:12:46Z

Describe your changes

Part of the string-based filter configuration work, RFC-HDFG-2026-001 (#6153), split into stacked PRs that merge into the integration branch feature/filter-config-3.0. That branch merges into develop as a unit once the stack is complete, which moves develop to 3.0; nothing here targets the 2.3 release. Review only the top commit; the base branch is the previous PR in the stack.

The new --filter-params option implies -p/--properties and also prints a PARAMS_STRING line inside each filter's entry: the stored string, else the get_config form, else cd_values=.... It's single-quoted because the value is TOML that often contains double-quoted values. A float that is a small multiple of a power of two gets a following # key = <hex float> line with its exact value, outside the quotes. A DESCRIPTION line shows the filter's registered description when the filter is available, so it can differ between machines.

-p output is unchanged. The new lines depend on which filters and plugins are available where h5dump runs, and h5import and scripts parse -p output, so they are opt-in. With --filter-params, filters that print on one line under -p (e.g. COMPRESSION DEFLATE { LEVEL 9 }, PREPROCESSING SHUFFLE) print as blocks holding the new lines.
New tfilter_params_* tests cover each filter with --filter-params. tfilter_params_deflate_noavail/tfilter_params_szip_noavail hold the cd_values= form printed when those filters are unavailable and run only against the native connector. tfilter_params_all runs only when both filters are available. The existing filter tests are unchanged.
New DDLBNF300 page documents the grammar (and corrects the NBIT rule to COMPRESSION NBIT); reference links point to it. The tools library links LINK_LIBS (libm) for the annotation code.

This follows RFC resolved item R27 (a separate flag so default output is unchanged); the RFC body, which said -p, is being updated to match.

Tested locally before the switch to --filter-params: 1,688/1,688 (h5dump, h5repack, h5ls, h5diff, tfilter2); CI covers the current version.

Issue ticket number (GitHub or JIRA)

#6153

Checklist before requesting a review

My code conforms to the guidelines in CONTRIBUTING.md
I made an entry in release_docs/CHANGELOG.md (bug fixes, new features)
I added a test (bug fixes, new features)

Stack

Merges into feature/filter-config-3.0, in order:

#	PR	Contents
1	#6698	TOML parser + H5Zconfig_* accessors
2	#6699	H5Z_class3_t
3	#6700	H5Pappend_filter & DCPL API
4	#6701	Pipeline message v3 on disk
5	#6702	h5dump -p ← this PR
6	#6703	h5repack UD=
7	#6704	Fortran wrappers
8	#6705	Java wrappers

Prerequisite, merging into feature/filter-config-3.0 on its own rather than as part of the stack: #6727 (H5F_LIBVER_V300 bound and the 3.0.0 version bump).

Related standalone fixes against develop: #6693, #6694, #6695, #6696.

The new --filter-params option implies -p/--properties and also prints a PARAMS_STRING line inside each filter's entry in the FILTERS block. It shows the value H5Pget_filter_params_by_idx() returns: the string stored in the file, else the filter's get_config form, else a cd_values= listing. The value is single-quoted because it is TOML text that often contains double-quoted values. When the string contains a decimal float that is a small multiple of a power of two (at most three hexadecimal fraction digits), a following "# key = <hex float>" line gives its exact value. The line is outside the quotes, so extracting the quoted span still recovers the string exactly. A DESCRIPTION line gives the filter's registered description from H5Zget_filter_class_info() when the filter is available. -p output is unchanged. The new lines depend on which filters are available on the machine running h5dump, and scripts and tools such as h5import parse -p output, so they are shown only on request. With --filter-params, filters that print on one line under -p print as blocks holding the new lines. New tfilter_params_* tests cover each filter with --filter-params. tfilter_params_deflate_noavail and tfilter_params_szip_noavail hold the cd_values= form printed when those filters are not available and run only against the native connector, like tszip and tdeflate in that configuration. The hex annotation uses floor() and isfinite(), so the tools library now links LINK_LIBS (libm). The new DDLBNF300 page documents the PARAMS_STRING, annotation and DESCRIPTION grammar and corrects the NBIT filter rule to COMPRESSION NBIT. The reference-manual links point to it.

jhendersonHDF · 2026-10-06T01:56:45Z

+
+<filter_user> :: = USER_DEFINED_FILTER
+
+<filter_deflate> :: = COMPRESSION DEFLATE { LEVEL <int_value> <filter_extra>opt }


I'm a bit on the fence about this one, but considering we have already been printing out the filter parameters for predefined filters previously, I'm thinking it somewhat makes sense to just always print out the parameter string and maybe even the description too without needing to specify a new option (only -p). The description is not really a filter parameter either so I think it's kind of unrelated to a --filter-params option, but I think it would also be a bit of a hassle to have yet another option just for that piece of information. The main concerns would be the increased amount of information displayed and whether the DDL format should be changed by default.

jhendersonHDF · 2026-10-06T02:15:26Z


+# --filter-params: -p plus each filter's PARAMS_STRING and DESCRIPTION. PARAMS_STRING
+# is the filter's get_config form when the filter is available and the raw cd_values
+# form otherwise, and DESCRIPTION appears only for available filters, so SZIP and


Just from a user perspective, I wonder if it makes more sense to have something like "Filter description unavailable" or similar so at least the DESCRIPTION field doesn't come and go depending on whether the filter is available.

jhendersonHDF · 2026-10-06T02:18:43Z

+    double f;
+    int    e;
+
+    /* Reject zero, inf and nan on the bit pattern: fast-math builds can fold


Similar to my comment in the other PR, this seems like something we probably shouldn't be concerning ourselves with

jhendersonHDF · 2026-10-06T02:25:09Z

+ *-------------------------------------------------------------------------
+ */
+static void
+h5tools_format_hexfloat(double v, char *out, size_t out_size)


I do think this hex float literal formatting is something that shouldn't necessarily be the default behavior

jhendersonHDF · 2026-10-06T02:27:00Z

+                /* Too large for the stack */
+                const size_t params_buf_size = H5Z_CONFIG_STRING_MAX + 1;
+                char        *params_str_buf  = (char *)malloc(params_buf_size);
+                char        *params_annot    = (char *)malloc(params_buf_size);


Error checking should be included on these

brtnfld requested review from gheber, glennsong09, hyoklee, jhendersonHDF, lrknox and vchoi-hdfgroup as code owners September 26, 2026 08:12

github-project-automation Bot added this to HDF5 - TRIAGE & TRACK Sep 26, 2026

brtnfld requested review from bmribler, fortnern and mattjala as code owners September 26, 2026 08:12

github-project-automation Bot moved this to To be triaged in HDF5 - TRIAGE & TRACK Sep 26, 2026

brtnfld force-pushed the filter-config/06-h5dump branch from 0a6cacf to 71dc173 Compare September 26, 2026 09:06

brtnfld force-pushed the filter-config/05-pline-v3 branch from d769f42 to 4a763ce Compare September 26, 2026 09:06

brtnfld mentioned this pull request Sep 26, 2026

✨ RFC-HDFG-2026-001: String-based filter configuration API #6663

Closed

brtnfld force-pushed the filter-config/05-pline-v3 branch from 4a763ce to ebbde92 Compare September 26, 2026 11:19

brtnfld force-pushed the filter-config/06-h5dump branch 2 times, most recently from a54a779 to fa0739c Compare September 26, 2026 21:46

brtnfld changed the title ~~[filter-config 6/9] Show filter configuration strings in h5dump -p output~~ [filter-config 6/9] Add h5dump --filter-params to show filter configuration strings Sep 26, 2026

brtnfld force-pushed the filter-config/06-h5dump branch from fa0739c to ad2c581 Compare September 26, 2026 21:54

brtnfld force-pushed the filter-config/05-pline-v3 branch from ebbde92 to 70b7f8a Compare September 27, 2026 06:34

brtnfld force-pushed the filter-config/06-h5dump branch from ad2c581 to 04902f0 Compare September 27, 2026 06:34

brtnfld mentioned this pull request Sep 27, 2026

✨ [Feature Request] String-Based Configuration Interface for Filters #6153

Open

brtnfld added 2 commits October 5, 2026 09:58

Trim comments in the h5dump --filter-params code

c4c317f

brtnfld force-pushed the filter-config/06-h5dump branch from 04902f0 to c4c317f Compare October 5, 2026 08:19

brtnfld force-pushed the filter-config/05-pline-v3 branch from 70b7f8a to a6b230c Compare October 5, 2026 08:19

brtnfld added 2 commits October 5, 2026 14:27

Merge branch 'filter-config/05-pline-v3' into filter-config/06-h5dump

6559cb1

Merge branch 'filter-config/05-pline-v3' into filter-config/06-h5dump

da278b6

jhendersonHDF reviewed Oct 6, 2026

View reviewed changes

nbagha1 added this to the HDF5 3.0.0 milestone Oct 13, 2026

nbagha1 assigned brtnfld Oct 13, 2026

brtnfld changed the title ~~[filter-config 6/9] Add h5dump --filter-params to show filter configuration strings~~ [filter-config 5/8] Add h5dump --filter-params to show filter configuration strings Oct 13, 2026

brtnfld and others added 3 commits October 13, 2026 15:19

Merge branch 'filter-config/05-pline-v3' into filter-config/06-h5dump

6221357

Merge branch 'filter-config/05-pline-v3' into filter-config/06-h5dump

3e52339

Committing clang-format changes

2e779cc

Navigation Menu

Repository navigation

[filter-config 5/8] Add h5dump --filter-params to show filter configuration strings - #6702

[filter-config 5/8] Add h5dump --filter-params to show filter configuration strings#6702
brtnfld wants to merge 7 commits into
filter-config/05-pline-v3from
filter-config/06-h5dump

brtnfld commented Sep 26, 2026 •

edited

Loading

Uh oh!

jhendersonHDF Oct 6, 2026

Uh oh!

jhendersonHDF Oct 6, 2026

Uh oh!

jhendersonHDF Oct 6, 2026

Uh oh!

jhendersonHDF Oct 6, 2026

Uh oh!

jhendersonHDF Oct 6, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		<filter_user> :: = USER_DEFINED_FILTER

		<filter_deflate> :: = COMPRESSION DEFLATE { LEVEL <int_value> <filter_extra>opt }

Conversation

brtnfld commented Sep 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Describe your changes

Issue ticket number (GitHub or JIRA)

Checklist before requesting a review

Stack

Uh oh!

jhendersonHDF Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

jhendersonHDF Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

jhendersonHDF Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

jhendersonHDF Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

jhendersonHDF Oct 6, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

brtnfld commented Sep 26, 2026 •

edited

Loading