libutil(3)

🌸 libutil(3) — the wipefs girlies' field guide 🌸

ok so this is a page from the Library Functions Manual (yes, the manual-manual, we love a classic) and it's all about the wipefs family of functions. if you've ever wondered how newfs_* keeps your shiny new file system from getting ghosted by the old one's leftovers — this is the tea. 🫖

---

✨ NAME ✨

wipefs_alloc, wipefs_except_blocks, wipefs_wipe, wipefs_free — literally just wipes the existing file systems off a volume. that's it. that's the whole job. 💅

🎀 LIBRARY 🎀

System Utilities Library — that's libutil, link it with -lutil. iconic. no cap.

🦋 SYNOPSIS 🦋

#include <wipefs.h>

int
wipefs_alloc(int fd, size_t block_size, wipefs_ctx *handle);

int
wipefs_include_blocks(wipefs_ctx handle, off_t block_offset,
    off_t nblocks);

int
wipefs_except_blocks(wipefs_ctx handle, off_t block_offset,
    off_t nblocks);

int
wipefs_wipe(wipefs_ctx handle);

void
wipefs_free(wipefs_ctx *handle);

---

💖 DESCRIPTION 💖

okay so the wipefs family of functions wipes existing file systems on a volume. the whole glow-up process is: first a DKIOCUNMAP ioctl gets sent to the device to invalidate, like, all of its content. then zeroes get written to the various little spots that different file systems peek at to recognize their own content and mount their volumes. 🧹✨

this is usually what the newfs_* utilities do before they create a new file system on the volume — so the old file system doesn't accidentally get mounted after the new one exists. imagine showing up to the party and your ex is still there. not on our watch. 🙈

NOTE (read this bestie, fr fr): these routines do not overwrite all volume structures. they do not securely erase the previous content. they only overwrite enough to make sure the normal utilities won't recognize any file system content anymore. it is possible that previous file system content could be recovered by other means. 💀 so like… do not use this to "securely delete" your ex's mixtape. that is not what this is.

---

🌟 wipefs_alloc() 🌟

initializes a wipefs_ctx object (which is an opaque data type — mysterious, main character energy). file_desc is the file handle of the volume to be wiped, and it can be a block device node, a character device node, or a file. file_desc must be opened with write access.

if block_size is 0, this function calls ioctl(2) to get the block size. a valid block_size must be supplied if file_desc is a regular file (no guessing games with regular files, okay?).

this function does not write any data to the volume. it just sets things up. ✨

🌟 wipefs_include_blocks() 🌟

tells wipefs to write zeroes in the block range provided, in addition to any other ranges it would normally write. this may be more efficient than if the caller were to write this range separately — especially if the block range overlaps or is contiguous with other ranges that wipefs will write. slay, efficiency. ⚡

does not write any data to the volume. if you call this multiple times, the union of all the ranges provided will be written by wipefs_wipe().

🌟 wipefs_except_blocks() 🌟

tells wipefs not to write anything in the block range provided. this one's for performance optimizations, for when the caller is gonna write to these blocks themselves. ⚠️ and it is the caller's responsibility to write to these blocks — otherwise some file systems may still be recognized on the volume. so like, don't skip leg day and don't skip your writes.

does not write any data to the volume. if you call this multiple times, the union of all the ranges provided will be excluded from being written by wipefs_wipe().

🔥 wipefs_wipe() 🔥

sends a DKIOCUNMAP ioctl and then writes data to the volume to wipe out existing file systems on it.

CAUTION: this function destroys any file system or partition scheme on the volume represented by file_desc. if file_desc represents the entire disk (e.g. /dev/diskX), the partition map of the disk will be destroyed. if file_desc represents a partition (e.g. /dev/diskXsY), only the file system in that partition is destroyed.

and like, even though the partition scheme or file system on file_desc may be beyond repair after wipefs_wipe(), this function is not designed as a means to safely delete all data. it is possible that some user data (or intact file systems in some partitions) may still be recovered. 💀 so again — not a shredder. it's a "make it unrecognizable" situation, not a "gone forever" situation.

🌈 wipefs_free() 🌈

frees the allocated wipefs_ctx handle and sets *handlep to NULL. clean up after yourself, bestie. 🫶

---

⭐ RETURN VALUES ⭐

wipefs_alloc(), wipefs_include_blocks(), wipefs_except_blocks() and wipefs_wipe() all return 0 on success, or they'll fail and return an error code. 📉

each function may return ENOMEM if insufficient memory is available. in addition:

• if block_size is not provided, wipefs_alloc() may return any error ioctl(2) returns.
• wipefs_wipe() may return any error pwrite(2) returns.

---

💜 a lil sign-off 💜

that's the whole page, bestie — brought to you by Mac OS, dated 6/30/11, living at libutil(3). go forth and wipe responsibly. mwah. 😘💅