h5jam(1)

✨ h5jam — the manual page, but make it cute ✨

okay so bestie, welcome to h5jam(1), a classic from the General Commands Manual lineup 💅 this is the little tool that glues a user block onto your HDF5 file, and honestly? it's giving main character energy.

🎀 NAME 🎀

h5jam — add a user block to a HDF5 file. that's it, that's the job, and it does it flawlessly.

🦋 SYNOPSIS 🦋

h5jam -u user_block -i in_file.h5 [-o out_file.h5] [--clobber]

🌸 DESCRIPTION 🌸

so here's the tea, bestie 🍓 h5jam concatenates a user_block file and an HDF5 file together to make an HDF5 file with a user block. and ngl, that user block can be either binary or text — no judgment either way, both are valid, both are iconic. the output file gets padded so that the HDF5 header starts on byte 512, 1024, etc.. (see the HDF5 File Format for the deets 💖)

now, the two vibes of running this:

• if out_file.h5 is given, a new file is created with the user_block followed by the contents of in_file.h5. and in this case? infile.h5 stays unchanged 🫶 it's fine, it's safe, it's untouched.
• if out_file.h5 is not specified, then the user_block is just added to in_file.h5 directly. no new file, we're editing in place, periodt.

and here's the plot twist 😭 if in_file.h5 already has a user block, then the contents of user_block will be added to the end of the existing user block, and the file gets shifted to the next boundary. but if --clobber is set, any existing user block will be overwritten — gone, deleted, not coming back, rip to that old block 💀

🔥 EXAMPLE USAGE 🔥

1. create a new file, newfile.h5, with the text in file mytext.txt as the user block for the HDF5 file file.h5.

h5jam -u mytext.txt -i file.h5 -o newfile.h5

2. add text in file mytext.txt to the front of HDF5 dataset, file.h5.

h5jam -u mytext.txt -i file.h5

3. overwrite the user block (if any) in file.h5 with the contents of mytext.txt.

h5jam -u mytext.txt -i file.h5 --clobber

💜 RETURN VALUE 💜

h5jam returns the size of the output file, or -1 if an error occurs. so like, big number = slay, -1 = we're crying in the club 😭

⭐ CAVEATS ⭐

okay bestie, listen, this is the part where we get real 🫶

• this tool copies all the data (sequentially) in the file(s) to new offsets. for a large file, this copy will take a long time. like, go make a snack, watch a whole show, it's not fast. 🙈
• the most efficient way to create a user block is to create the file with a user block (see H5Pset_user_block), and write the user block data into that space from a program. that's the speedrun route 🔥
• the user block is completely opaque to the HDF5 library and to the h5jam and h5unjam tools. it's simply read or written as a string of bytes, which could be text or any kind of binary data. it is up to the user to know what the contents of the user block means and how to process it. no cap, that's on you 💅
• when the user block is extracted, all the data is written to the output, including any padding or unwritten data. yes, even the weird empty parts. all of it. 🌈
• this tool moves the HDF5 file through byte copies, i.e., it does not read or interpret the HDF5 objects. it's just moving bytes around, it doesn't care what's inside, it's not nosy, it's just strong 💪

👑 SEE ALSO 👑

h5dump(1), h5ls(1), h5diff(1), h5import(1), gif2h5(1), h52gif(1), h5perf(1), h5unjam(1).

go read those too, they're all part of the fam 🧚

and that's the whole page, bestie ✨ this one's from the General Commands Manual, page h5jam(1) — go forth and jam those user blocks on, you absolute icon 👑💖