atReadExpand(3)

💖 atReadExpand(3) — bestie edition 💖

okay so this is the AtFS Toolkit Library page for atReadExpand(3) and its little friend group, and honestly? they ate. ✨

---

🌸 NAME 🌸

• atOpenExpand, atReadExpand, atCloseExpand — read version objects with attribute citations expanded 🦋
• atGetWriteName — get the bound version name of a version object that got opened with atOpenExpand 👑

---

✨ SYNOPSIS ✨

#include <atfs.h>
#include <atfstk.h>

int   atOpenExpand(char *version, int expand_busy) ;

int   atReadExpand(int desc, char *bufp, int nbytes) ;

void  atCloseExpand(int desc) ;

char *atGetWriteName(int desc) ;

extern int  atBindError ;
extern char atBindErrorMsg[] ;

---

💅 DESCRIPTION 💅

so atOpenExpand, atReadExpand, and atCloseExpand are literally designed as a nearly plug-compatible replacement for the system calls open(2), read(2), and close(2) — but for reading AtFS version objects with attribute citations expanded. it's giving "same energy, extra sparkle." 🎀

atOpenExpand opens the file or AtFS version object version for reading with atReadExpand. version points to the pathname of a file or an AtFS version object. if the flag expand_busy is non-zero, attribute citations get expanded in busy versions also 👀. atOpenExpand returns a descriptor that is valid as an argument to successive calls to atReadExpand and atCloseExpand.

atReadExpand attempts to read nbytes of data from the object referenced by the descriptor desc into the buffer pointed to by bufp. if desc is zero, atReadExpand reads from the standard input 📥. atReadExpand returns the number of bytes actually read.

atCloseExpand frees the resources associated with the descriptor desc. bye bestie, clean up after yourself 🫶

atGetWriteName returns a pointer to the bound version name of the version object for which atOpenExpand returned the descriptor desc. iconic behavior tbh.

---

🔥 DIAGNOSTICS 🔥

on error, atOpenExpand and atReadExpand return -1 and set errno appropriately. if one of these returns an error and errno is set to ENOMEM, the application may retry the operation, possibly after freeing some memory. so like, breathe, free some stuff, try again 💆

if atOpenExpand returns an error and atBindError has a non-zero value, the string version did not select a version object, or did not select a unique version object. in that case atBindErrorMsg contains an appropriate error message 📢.

possible values of errno after a call to atOpenExpand:

• ENOMEM — not enough memory could be allocated 😭
• EMFILE — all available descriptors are in use 💀
• all errno values returned by open(2) or read(2) — yes, the whole set, no crumbs left

possible values of errno after a call to atReadExpand:

• ENOMEM — not enough memory could be allocated 😭
• EBADF — invalid descriptor 🚫

---

💀 BUGS 💀

since atOpenExpand reads the complete contents of version into memory, it fails on very large version objects. so like… big files? not her moment. no cap. 🙈

---

🌈 SEE ALSO 🌈

intro(2), open(2), read(2), close(2), errno(3), atattribute(3), atbind(3).

---

this has been AtFStk-1.12, dated Tue Feb 16 20:33:25 1993 — yes bestie, 1993, she's vintage and she's still serving 👑✨💜