th_read(3)

📦 version 1.2.20, in arch rolling, debian bookworm, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu jammy, ubuntu noble

💖 th_read — bestie we're reading AND writing tar header blocks 💖

ok so this is a libtar man page, the th_read(3) one, and honestly? it's giving short and iconic. two little functions, one big vibe. let's get into it 🫶

✨ NAME ✨

th_read, th_write — read and write a file header block from a tar archive

like. that's the whole job description. reading a header, writing a header. no cap. 🎀

✨ SYNOPSIS ✨

#include <libtar.h>

int th_read(TAR *t);

int th_write(TAR *t);

see how clean that is?? one header file, two functions, both taking a TAR *t and both handing you back an int. we love a symmetrical moment 💅

✨ VERSION ✨

this man page is documenting version 1.2 of libtar. yes bestie, 1.2, write it down, don't be out here reading docs for the wrong version 😭

✨ DESCRIPTION ✨

ok so, story time 🌸

th_read() reads the next block from the tar archive that's associated with the TAR handle t. and then — this is the main character part — it sets the current tar header associated with t to the contents of that block it just read. so like, the handle now knows what the header is. it's informed. it's in the know. periodt ✨

th_write() does the reverse glow-up: it takes the contents of the current tar header associated with t and writes them out to the tar archive associated with t. header goes in, header comes out. balanced. symmetrical. beautiful. 🦋

✨ RETURN VALUE ✨

  • on successful completion, th_read() and th_write() both return 0. zero. the good number. slay 💚
  • on failure, they return -1 and set errno to an appropriate value. so like, if it goes wrong, check errno, she'll tell you what happened 👀
  • and on EOF, th_read() returns 1. yes, 1, not 0, not -1. that's its own little special signal and you gotta handle it, bestie, or you'll be confused for hours fr fr 😭
lowkey important: EOF is not an error here. it's a 1. don't conflate them or the vibes will be off 💀

✨ ERRORS ✨

th_read() and th_write() will fail if:

  • EINVAL — less than T_BLOCKSIZE blocks were read or written. like, you didn't get a full block?? that's an EINVAL, sorry babe 🙈

✨ SEE ALSO ✨

the block-level besties. go read those too, iykyk 💜

and that's the whole page, babes ✨ this one came to us from the University of Illinois, dated Jan 2001 — yeah, 2001, she's been serving tar headers since before some of us were born and she still ate 💅👑

📦 where this page comes from