GFARM(3)

💖 GFARM 💖

okay bestie, buckle up — this is the GFARM(3) page from the Gfarm manual, and it's literally the whole vibe of the Gfarm file system API library. it's the map, not the territory: every function gets its own page, and this one is the ✨overview✨. iykyk. 🦋

---

🌸 NAME 🌸

gfarm — the Gfarm file system API library, no cap 💅

---

✨ SYNOPSIS ✨

#include <gfarm/gfarm.h>

---

🎀 DESCRIPTION 🎀

so like. the Gfarm library is your little interface layer to the Gfarm file system, and this manual is the big-picture tour of the whole library. for the deets on any single function, go read that function's own manual page, bestie. 📖

🧚 Initialize / Finalize 🧚

• the gfarm_initialize() function is the one you call to init the Gfarm library — like, wake it up. 🌅
• the gfarm_terminate() function is the one you call to terminate the library — tuck it in. 😴

📁 File input/output operations 📁

want to open a file that already exists as a stream? that's gfs_pio_open(), periodt. want to create a file and open it as a stream? that's gfs_pio_create(). and gfs_pio_close() is how you close those streams. 🫶

• gfs_pio_error() — peep whether an error has happened with a stream or not.
• gfs_pio_eof() — peep whether a stream that was opened for read has already hit end-of-file or not.
• gfs_pio_seek() — moves the current position of the stream. sliding around fr. 🛝

reading:

• gfs_pio_getc() reads a character from a stream, and gfs_pio_ungetc() puts a character back onto a stream (not me un-reading, iconic).
• gfs_pio_getline(), gfs_pio_gets(), and gfs_pio_readline() all read one line from a stream.
• gfs_pio_readdelim() reads from the stream until the delimiter character — the one you passed as a function argument — shows up.
• gfs_pio_read() reads the specified bytes from a stream.

writing:

• gfs_pio_putc() writes one character to a stream, and gfs_pio_putline() and gfs_pio_puts() write one line to a stream.
• gfs_pio_write() writes the specified bytes to a stream.
• gfs_pio_flush(), gfs_pio_sync(), and gfs_pio_datasync() move buffered data to a storage device. the way that data has to actually leave the buffer 💀
• gfs_pio_truncate() truncates a file. ✂️

🗂️ Directory access 🗂️

• gfs_opendir() opens a directory, gfs_readdir() retrieves the entries of that directory, and gfs_closedir() closes it. main character directory arc.

now the glob girlies:

• a gfs_glob_t data — which you init with gfs_glob_init() — can be passed to gfs_glob(), and gfs_glob() returns a list of matched file/directory names in that gfs_glob_t.
• that gfs_glob_t must be released by gfs_glob_free(). don't leave it hanging, bestie. 🚨
• gfs_glob_add() is used to add an entry to a gfs_glob_t.

🌈 File / Directory manipulation 🌈

• gfs_chmod() changes the mode of a file, gfs_chown() changes the owner of a file, and gfs_utimes() changes the file's modification time and access time. glow-up but for metadata ✨
• gfs_mkdir() creates a directory, gfs_rmdir() removes a directory, gfs_unlink() removes a file, and gfs_rename() renames a file or a directory.
• gfs_stat() returns information like size, modified/access time, etc.

⚠️ the struct gfs_stat returned by gfs_stat() must be released by gfs_stat_free(). literally do not forget this one. 😭

🔐 ACL (Access Control List) OPERATIONS 🔐

the access-control era. let's go, we're doing it in chunks 🧵

setup & teardown:

• gfs_acl_init() is used to init an ACL structure (gfarm_acl_t), and gfs_acl_free() is used to release the ACL structure.
• gfs_acl_dup() duplicates an ACL structure.

entries:

• gfs_acl_create_entry() creates an ACL entry (gfarm_acl_entry_t) in an ACL structure.
• gfs_acl_get_entry() gets an ACL entry from the ACL structure.
• gfs_acl_delete_entry() removes an ACL entry from the ACL structure.

validity:

• gfs_acl_valid() checks an ACL structure for validity.
• gfs_acl_check can check more for validity. 👀

mask:

• gfs_acl_calc_mask() calculates and sets the ACL permissions of a GFARM_ACL_MASK type entry in an ACL structure.

tag types:

• gfs_acl_get_tag_type() gets an ACL tag (gfarm_acl_tag_t) — that's the type of the ACL entry — from an ACL entry.
• gfs_acl_set_tag_type() sets an ACL tag of an ACL entry.

permission sets:

• gfs_acl_get_permset() gets an ACL permission-set (gfarm_acl_permset_t) from an ACL entry.
• gfs_acl_set_permset() sets an ACL permission-set of an ACL entry.

individual permissions:

• gfs_acl_add_perm() adds an ACL permission (gfarm_acl_perm_t) to an ACL permission-set.
• gfs_acl_clear_perms() clears all ACL permissions from an ACL permission-set. wipeout 🧼
• gfs_acl_delete_perm() deletes a permission from an ACL permission-set.

qualifiers:

• gfs_acl_get_qualifier() gets a username/groupname from an ACL entry. heads up: GFARM_ACL_USER / GFARM_ACL_GROUP tag entries have a username/groupname. 🏷️
• gfs_acl_set_qualifier() sets the username/groupname of an ACL entry.

whole files & directories:

• gfs_acl_delete_def_file() deletes a Default ACL from a file or directory.
• gfs_acl_get_file() gets the ACL structure of a file or directory.
• gfs_acl_set_file() replaces the ACL structure of a file or directory.

🚨 before using gfs_acl_set_file(), the ACL structure must be sorted by gfs_acl_sort(). non-negotiable.

text conversion:

• gfs_acl_to_text() converts an ACL structure to an ACL text. gfs_acl_to_any_text() is more functional than this function, jsyk.
• gfs_acl_from_text() creates an ACL structure from an ACL text.

single permission testing:

• gfs_acl_get_perm() tests for an ACL permission in an ACL permission set.

checking + errors:

• gfs_acl_check() checks an ACL structure for validity. and! it can also get the place of the error and the ACL error code. this function is more functional than gfs_acl_valid(), slay.
• gfs_acl_error() converts an ACL error code from gfs_acl_check() into a text message.

counting:

• gfs_acl_entries() returns the number of entries in an ACL structure.

equivalence:

• gfs_acl_equiv_mode() checks for an equivalent ACL structure. an equivalent ACL structure has only the base ACL entries of tag types (GFARM_ACL_USER_OBJ, GFARM_ACL_GROUP_OBJ, GFARM_ACL_OTHER). and, this function can create file permission bits (gfarm_mode_t) from base ACL entries. two-for-one 💫

comparing:

• gfs_acl_cmp() compares two ACL structures. 🆚

from mode:

• gfs_acl_from_mode() creates an ACL structure from file permission bits (gfarm_mode_t).

to any text:

• gfs_acl_to_any_text() converts an ACL structure to an ACL text. this function has some options for output format, and it's more functional than gfs_acl_to_text(). 💅

xattr binary data:

• gfs_acl_to_xattr_value() converts an ACL structure to ACL binary data for an Extended Attribute value.
• gfs_acl_from_xattr_value() converts ACL binary data for an Extended Attribute value into an ACL structure.

⚠️ before using gfs_acl_to_xattr_value(), the ACL structure must be sorted by gfs_acl_sort(). same rule, same energy.

sorting:

• gfs_acl_sort() sorts the ACL entries of an ACL structure in ACL validity order. 🧹

the fancy one:

• gfs_acl_from_text_with_default() creates two ACL structures (Access ACL and Default ACL) from an ACL text which includes a "default:" prefix. two at once, she ate 🍽️

💀 Error handling 💀

• most Gfarm API returns the Gfarm error code in gfarm_error_t.
• gfarm_error_string() returns a string describing the Gfarm error code.
• gfarm_errno_to_error() translates the error number (errno) to the Gfarm error code.
• gfarm_error_to_errno() translates the Gfarm error code to the error number.

back and forth, back and forth, the translation pipeline never sleeps 🌙

🧵 String Array manipulation utilities 🧵

a gfarm_stringlist type variable represents an array of strings, and this type is initialized by gfarm_stringlist_init(). 💖

• gfarm_stringlist_add() — add a string to a gfarm_stringlist.
• gfarm_stringlist_cat() — add strings to a gfarm_stringlist.
• gfarm_stringlist_free() — releases a gfarm_stringlist.
• gfarm_stringlist_elem() or the GFARM_STRINGLIST_ELEM() macro — access each string of an array.
• gfarm_stringlist_length() — see the number of strings in an array. 🔢

and then:

• gfarm_strings_free_deeply() releases a string array and each element of the array by calling the standard library function free(). deep clean, no crumbs left 🧼

⭐ String Array manipulation macros ⭐

• GFARM_STRINGLIST_ELEM(list, i) — represents the i-th element of the list argument, whose type is gfarm_stringlist. this macro can be used as an L-value. if this macro is used as a value, it returns the same result as the gfarm_stringlist_elem() function.
• GFARM_STRINGLIST_STRARRAY(list) — returns a pointer to the first element of the list argument, whose type is gfarm_stringlist. the type of the return value is a pointer to pointer to a character. 🪄

---

and that's the whole page bestie!! this was Gfarm, dated 26 Jun 2010, from the Gfarm source/version line at the bottom — so yeah, retro but still serving. go read the individual function pages for the deep lore, ily, drink water 💜🦋✨