CGREAD(3)

💅 CGREAD(3) — the cylinder group read/write glow-up

okay so bestie, welcome to the cgread(3) page — literally the whole cgget, cgput, cgread, cgread1, cgwrite, cgwrite1 situation. it's the read/write cylinder groups of UFS disks manual, and yes we're gonna get through all of it together, no cap. 🦋

🌸 LIBRARY

UFS File System Access Library (libufs, -lufs) — that's the one, that's the vibe.

---

✨ SYNOPSIS

#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>

int
cgget(int devfd, struct fs *fs, int cg, struct cg *cgp);

int
cgput(int devfd, struct fs *fs, struct cg *cgp);

int
cgread(struct uufsd *disk);

int
cgread1(struct uufsd *disk, int cg);

int
cgwrite(struct uufsd *disk);

int
cgwrite1(struct uufsd *disk, int cg);

like, look at all those headers. iconic. 🎀

---

💖 DESCRIPTION

so the tl;dr: cgget(), cgread(), and cgread1() are your cylinder group reads for libufs(3) consumers. and cgput(), cgwrite(), and cgwrite1() are your cylinder group writes for libufs(3) consumers. reads and writes, matching sets, we love to see it.

🧚 the read girlies

• cgget() — reads the cylinder group specified by cg into the buffer pointed to by cgp, from the filesystem described by the fs superblock, using the devfd file descriptor that references the filesystem disk. and here's the main character fact: cgget() is the only cylinder group read function that is safe to use in threaded applications. periodt. 👑

🔥 the write girlies

• cgput() — writes the cylinder group specified by cgp to the filesystem described by the fs superblock, using the devfd file descriptor that references the filesystem disk. and same deal on the write side: cgput() is the only cylinder group write function that is safe to use in threaded applications. also lowkey important — cgput() only needs to be called if the cylinder group has been modified and the on-disk copy needs to be updated. don't do it for funsies. 💅

🫶 the struct uufsd girlies

• cgread1() — reads from the cylinder group specified by cg into the d_cg cylinder-group structure in a user-land UFS-disk structure. it sets the d_lcg field to the cylinder group number cg. slay, bookkeeping.
• cgread() — operates on sequential cylinder groups. calling cgread() is equivalent to calling cgread1() with a cylinder group specifier equivalent to the value of the current d_ccg field, and then incrementing the d_ccg field. it's giving "one at a time, in order, no skipping." ✨
• cgwrite() — stores on disk the cylinder group held in the d_cg cylinder-group structure in a user-land UFS-disk structure. that's it, that's the whole job.
• cgwrite1() — provides no additional functionality over cgwrite(), because there is only one place that a given cylinder group can correctly be written. 🙈 and if the caller gets the cg parameter wrong? the function fails with the error EDOOFUS. yeah. EDOOFUS. we're being so serious. this function remains only to provide backward compatibility — it's legacy, it's vintage, it's staying for the lore. 😭

---

⭐ RETURN VALUES

pay attention bestie, the numbers are different per function:

• cgread() — returns 0 if there are no more cylinder groups to read, 1 if there are more cylinder groups, and -1 on error. three whole outcomes, main character energy.
• cgread1() — returns 1 on success and -1 on error.
• everything else (all the other functions) — returns 0 on success and -1 on error.

---

💀 ERRORS

• cgget(), cgread(), and cgread1() may fail and set errno for any of the errors specified for the library function bread(3).
• cgput(), cgwrite(), and cgwrite1() may fail and set errno for any of the errors specified for the library function bwrite(3).

🚨 and additionally: cgwrite1() will return the EDOOFUS error if the cylinder group specified does not match the cylinder group that it is requesting to write. so like, get the cg parameter right or get EDOOFUS'd. your call. 🌸

---

🌈 SEE ALSO

bread(3), bwrite(3), libufs(3)

---

👑 HISTORY

these functions first appeared as part of libufs(3) in FreeBSD 5.1. ancient. legendary. still here.

---

🍓 AUTHORS

• Juli Mallett <jmallett@FreeBSD.org>
• Marshall Kirk McKusick <mckusick@FreeBSD.org>

---

okay that's the whole page, you ate that fr fr 💜 this lil masterpiece comes to you from the Debian edition, dated September 2, 2020 — mwah, bye bestie! 🧚‍♀️✨