BREAD(3)

💅 BREAD(3) — the bread, bwrite, berase era 🍞✨

okay so bestie, this one's from the Library Functions Manual, and honestly? it's giving "tiny API, huge responsibility." let's get into it 🫶

---

🌸 NAME

bread, bwrite — read and write blocks of a UFS file system 💾 (and yes there's a berase in here too, she's in the synopsis, don't worry, we'll get to her 😌)

---

🎀 LIBRARY

UFS File System Access Library (libufs, -lufs) — literally the whole vibe check for talking to UFS from userland 💖

---

✨ SYNOPSIS

like, first you gotta summon the headers, no cap:

#include <sys/param.h>
#include <sys/mount.h>
#include <ufs/ufs/ufsmount.h>
#include <ufs/ufs/dinode.h>
#include <ufs/ffs/fs.h>
#include <libufs.h>

then the actual main characters 🔥:

ssize_t
bread(struct uufsd *disk, ufs2_daddr_t blockno, void *data,
    size_t size);

ssize_t
bwrite(struct uufsd *disk, ufs2_daddr_t blockno, const void *data,
    size_t size);

int
berase(struct uufsd *disk, ufs2_daddr_t blockno, ufs2_daddr_t size);

look at them. so compact. so iconic. 👑

---

🦋 DESCRIPTION

so bread(), bwrite() and berase() are the block read / write / erase API for libufs(3) girlies 🌈. they do exactly what they say on the tin — they operate on a userland UFS disk structure, and they do the read and the write at a given block address, which honestly is just using the current d_bsize value of that structure 💅. that's the whole plot, no plot twists, fr fr.

---

💜 RETURN VALUES

• bread() and bwrite() — return the amount read or written. and if literally anything goes wrong? -1. and yes, a short read counts as an error, so don't come crying to me when you get -1 back 😭
• berase() — returns non-zero on error. (so zero = we slayed, non-zero = we did not 🫠)

---

💀 ERRORS

okay so this is the "when things go sideways" section, pay attention bestie:

• bread() may fail and set errno for any of the errors specified for the library functions ufs_disk_write(3) or pread(2).
• bwrite() may fail and set errno for any of the errors specified for the library function pwrite(2).
• berase() may fail and set errno for any of the errors specified for the library function ioctl(2).

🚨 and additionally, all three of these functions may follow the libufs(3) error methodologies in situations where the amount of data written is not equal to the amount requested, or in case of a device error. that's the scary part, ngl. keep an eye on your return values, they're telling you something 🙈

---

🌟 SEE ALSO

• libufs(3)
• ufs_disk_write(3)

go read those too, iykyk 💖

---

🧚 HISTORY

these functions first appeared as part of libufs(3) in FreeBSD 5.0 ⭐ — so yeah, they've been serving for a minute 🎀

---

👑 AUTHORS

Juli Mallett <jmallett@FreeBSD.org> — we stan 🫶

---

and that's the page!! 💅 this beauty is from the Debian edition, dated June 4, 2003, and it's filed under BREAD(3). periodt. 🌸✨