DIRREAD(3)

🌸 NAME 🌸

okay so this is the DIRREAD(3) page from the Library Functions Manual, and it’s all about dirread, dirreadall — read directory, bestie 💅✨

✨ SYNOPSIS ✨

#include <u.h>
#include <libc.h>

long dirread(int fd, Dir **buf)

long dirreadall(int fd, Dir **buf)

#define   STATMAX   65535U

#define   DIRMAX    (sizeof(Dir)+STATMAX)

💖 DESCRIPTION 💖

okay so picture this: the data you get back from a read(3) on a directory is a set of complete directory entries in a machine-independent format. It’s exactly equivalent to the result of a stat(3) on each file or subdirectory in the directory. No cap. 🫶

dirread decodes those directory entries into a machine-dependent form. It reads from fd and unpacks the data into an array of Dir structures. The address of that array is returned in *buf — and yeah, see stat(3) for the layout of a Dir. The array is allocated with malloc(3) each time dirread is called, so it’s fresh every single time ✨

dirreadall is like dirread, but it reads in the entire directory. By contrast, dirread steps through a directory one read(3) at a time — lil sips, not the whole thing 🍓

Directory entries have variable length. A successful read of a directory always returns an integral number of complete directory entries; dirread always returns complete Dir structures. See read(9p) for more information — iykyk 📚

The constant STATMAX is the maximum size that a directory entry can occupy. The constant DIRMAX is an upper limit on the size necessary to hold a Dir structure and all the associated data. Basically: size limits, but make it iconic 💅

dirread and dirreadall return the number of Dir structures filled in buf. The file offset is advanced by the number of bytes actually read. slay. 📈

🎀 SOURCE 🎀

/src/lib9/dirread.c — that’s the source file, bestie. 🫶

🦋 SEE ALSO 🦋

• intro(3)
• open(3)
• read(3)

💀 DIAGNOSTICS 💀

dirread and dirreadall return zero for end of file and a negative value for error. In either case, *buf is set to nil, so the pointer can always be freed with impunity. No cap — free it and don’t stress. 🫶

These functions set errstr. So if something goes sideways, check errstr, bestie. 🚨

and that’s the whole page, bestie — footer vibe is just DIRREAD(3) from the Library Functions Manual, no date printed on this one, so I’m not inventing one. source/version? The source path is /src/lib9/dirread.c up in SOURCE, the manual name is DIRREAD(3), and that’s periodt. 💖✨🎀