h5unjam(1)

💅 h5unjam — ok so bestie, let me put you on

Welcome to the h5unjam page, straight out of your General Commands Manual 💖 (yes, section 1, we're in the big leagues).

✨ NAME ✨

h5unjam — extract the user block from a HDF5 file 🦋

Like, it takes the lil' mystery chunk off the front of your HDF5 file and hands it to you separately. Iconic behaviour honestly.

🌸 SYNOPSIS 🌸

h5unjam -i in_file.h5 [-u user_block | --delete] [-o out_file.h5]

🎀 DESCRIPTION 🎀

Okay so here's the tea, bestie ☕ — h5unjam splits an HDF5 file. It writes the user block out to a file or to stdout, and it writes the HDF5 file out to an HDF5 file with a header at byte 0 (i.e., with no user block). Two halves, one glow-up. ✨

• If out_file.h5 is given, a new file is created with the contents of in_file.h5 minus the user block. In this case, infile.h5 is unchanged — your original stays untouched, we're respectful like that 💖
• If out_file.h5 is not specified, the user_block gets removed and in_file.h5 is rewritten, starting at byte 0. So yeah, that one edits in place, no cap 👀
• If user_block is set, the user block will be written to user_block. If user_block is not set, the user block (if there is any) will be written to stdout. And if --delete is selected, the user block will not be not written. (Read that twice, it's a double negative and it's lowkey a vibe 😭)

🌈 EXAMPLE USAGE 🌈

Say you've got an HDF5 file, with_ub.h5, that has a user block. You wanna extract that user block into user_block.txt and the HDF5 file into wo_ub.h5. So you do:

h5unjam -i with_ub.h5 -u user_block.txt -i wo_ub.h5

There it is. Slay. 👑

⭐ RETURN VALUE ⭐

h5unjam returns the size of the output file, or -1 if an error occurs. That's it, that's the whole report card. 💯

💀 CAVEATS 💀

Okay now the serious part, and I need you to listen bestie, because this is where people get got:

• 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. Go touch grass. It's coming back when it's coming back 🐌
• 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. Do it right the first time, fr fr.
• 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 mean and how to process them. Nobody here is reading your diary, we just move the bytes 💅
• When the user block is extracted, all the data is written to the output, including any padding or unwritten data. Yeah. All of it. Even the weird empty parts. 🙈
• This tool moves the HDF5 file through byte copies, i.e., it does not read or interpret the HDF5 objects. It's not analyzing anything, it's just shoving bytes around, main character energy only 🧚

⚠️ Lowkey important: those in-place rewrites and long byte-copy runs are exactly as slow and exactly as destructive as they sound. Plan accordingly, babes.

🫶 SEE ALSO 🫶

Go check out the whole friend group:

• h5dump(1)
• h5ls(1)
• h5diff(1)
• h5import(1)
• gif2h5(1)
• h52gif(1)
• h5perf(1)
• h5jam(1)

and that's the whole page, bestie ✨ This was h5unjam(1) from the General Commands Manual — the very same title line we opened with, now closing us out. Go forth, unjam your user blocks, and hydrate. 💖🎀🦋🌸💜