tar_extract_file(3)

💅 tar_extract_file(3) — C Library Calls, but make it make sense

okay bestie, buckle up, because this is the <libtar.h> glow-up you didn't know you needed. this whole page is about pulling files out of a tar archive, and there are like a million little functions doing it. no cap. 🎀

---

✨ NAME ✨

tar_extract_file, tar_extract_regfile, tar_extract_hardlink, tar_extract_symlink, tar_extract_chardev, tar_extract_blockdev, tar_extract_dir, tar_extract_fifo, tar_skip_regfile, tar_set_file_perms — the whole squad that extracts files from a tar archive 💖

---

🌸 SYNOPSIS 🌸

#include <libtar.h>

int tar_extract_file(TAR *t, char *realname);

int tar_extract_regfile(TAR *t, char *realname);

int tar_skip_regfile(TAR *t);

int tar_extract_dir(TAR *t, char *realname);

int tar_extract_hardlink(TAR *t, char *realname);

int tar_extract_symlink(TAR *t, char *realname);

int tar_extract_blockdev(TAR *t, char *realname);

int tar_extract_chardev(TAR *t, char *realname);

int tar_extract_fifo(TAR *t, char *realname);

int tar_set_file_perms(TAR *t, char *realname);

---

🦋 VERSION 🦋

this little man page is documenting version 1.2 of libtar. periodt.

---

👑 DESCRIPTION 👑

so here's the tea ☕. tar_extract_file() is basically the main character of this whole page — it's the front-end that runs the show for all the other tar_extract_*() girlies. what it does is peek at the current tar header hanging out with the TAR handle t (and heads up: that handle has to be initialized first by calling th_read() — don't skip that step bestie) to figure out what kind of file that header is actually talking about. then it calls the right tar_extract_*() function to extract that specific type of file. it's giving delegator energy. 💅

tar_skip_regfile() is the "we're not doing that today" function — it skips right over the file content blocks and parks the file pointer exactly where the next tar header block is supposed to be. lowkey iconic. ⭐

tar_set_file_perms() is the glow-up artist ✨ — it sets the attributes of the extracted file so they match the encoded values. that means the file's modification time, mode, owner, and group. and the thing is, tar_extract_file() calls this automatically for you, but if your app is out here calling the other tar_extract_*() functions directly, then you have to call tar_set_file_perms() manually if you want that behavior. yes, manually. i know. 🙈

---

💖 RETURN VALUES 💖

on a successful completion, all the functions documented here return 0. yay! 🎉

on failure, they return -1 and set errno to an appropriate value. sad girl hours. 😭

and the special one: tar_extract_dir() will return 1 if the directory already exists. (not an error, just a lil "been there, done that" 💅)

---

🔥 ERRORS 🔥

heads up bestie, error time. read carefully, this part matters.

tar_extract_file() will fail if:

• EEXIST — if the O_NOOVERWRITE flag is set and the file already exists. like, it's already here?? we're not touching it. 🚫

the tar_extract_*() functions will fail if:

• EINVAL — an entry could not be added to the internal file hash.
• EINVAL — less than T_BLOCKSIZE bytes were read from the tar archive.
• EINVAL — the current file header associated with t refers to a kind of file other than the one which the called function knows about. (mismatch energy 💀)

they may also fail if any of the following functions fail: mkdir(), write(), link(), symlink(), mknod(), mkfifo(), utime(), chown(), lchown(), chmod(), or lstat().

---

🌈 SEE ALSO 🌈

mkdir(2), write(2), link(2), symlink(2), mknod(2), mkfifo(2), utime(2), chown(2), lchown(2), chmod(2), lstat(2) — go read those too, iykyk 🫶

---

and that's the whole page, bestie! this one's brought to you by the University of Illinois, dated Jan 2001 (yes, a vintage queen 👑), documenting tar_extract_file(3) in the C Library Calls lineup. mwah 💋✨