--- name: "gfarm" section: "3" platform: "linux" package: "libgfarm-dev" version: "2.7.20+dfsg-1.2+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/gfarm" --- # gfarm(3) Gfarm file system API library ## NAME gfarm - Gfarm file system API library ## SYNOPSIS ``` #include ``` ## DESCRIPTION The Gfarm library provides an interface layer to the Gfarm file system. This manual gives an overview of the library. For details, refer to a manual page of each function. ### Initialize / Finalize **gfarm\_initialize**() function is used for the initilization of the Gfarm library, and **gfarm\_terminate**() function is used for the termination of the library. ### File input/output operations To open an existing file as a stream, **gfs\_pio\_open**() function is used. To create an file and open the file as a stream, **gfs\_pio\_create**() function is used. **gfs\_pio\_close**() function is used to close such streams. **gfs\_pio\_error**() function is used to see whether an error happens or not about a stream. **gfs\_pio\_eof**() function is used to see whether a stream, which is opened for read, already reaches end-of-file or not. **gfs\_pio\_seek**() function changes the current position of the stream. **gfs\_pio\_getc**() function reads a character from a stream, and **gfs\_pio\_ungetc**() function puts back a character to a stream. **gfs\_pio\_getline**() function, **gfs\_pio\_gets**() function, and **gfs\_pio\_readline**() function read one line from a stream, and **gfs\_pio\_readdelim**() function reads from stream until delimiter character, specified by the function argument, appears. **gfs\_pio\_read**() function reads specified bytes from a stream. **gfs\_pio\_putc**() function writes one character to a stream, and **gfs\_pio\_putline**() function and **gfs\_pio\_puts**() function write one line to a stream. **gfs\_pio\_write**() function writes specified bytes to a stream. **gfs\_pio\_flush**() function, **gfs\_pio\_sync**() function and **gfs\_pio\_datasync**() function moves buffered data to a storage device. **gfs\_pio\_truncate**() function truncates a file. ### Directory access **gfs\_opendir**() function opens a directory, and **gfs\_readdir**() function retrieves entries of the directory. **gfs\_closedir**() function closes the directory. A gfs\_glob\_t data, which is initialized by **gfs\_glob\_init**() function, can be passed to **gfs\_glob**() function, and the gfs\_glob function returns list of matched file/directory names in the gfs\_glob\_t. The gfs\_glob\_t must be released by **gfs\_glob\_free**() function. **gfs\_glob\_add**() function is used add an entry to gfs\_glob\_t. ### File / Directory manipulation **gfs\_chmod**() function changes the mode of a file, and **gfs\_chown**() function changes the owner of a file, and **gfs\_utimes**() function changes file's modification time and access time. **gfs\_mkdir**() function creates a directory, and **gfs\_rmdir**() function removes a directory. **gfs\_unlink**() function removes a file, and **gfs\_rename**() function renames a file or a directory. **gfs\_stat**() function returns information like size, modified/access time, etc. The struct gfs\_stat returned by gfs\_stat function must be released by **gfs\_stat\_free**() function. ### ACL (Access Control List) OPERATIONS **gfs\_acl\_init**() function is used for the initilization of an ACL structure (gfarm\_acl\_t), and **gfs\_acl\_free**() function is used to release the ACL structure. **gfs\_acl\_dup**() function duplicates an ACL structure. **gfs\_acl\_create\_entry**() function creates an ACL entry (gfarm\_acl\_entry\_t) in an ACL structure, and **gfs\_acl\_get\_entry**() function gets an ACL entry from the ACL structure, and **gfs\_acl\_delete\_entry**() function removes an ACL entry from the ACL structure. **gfs\_acl\_valid**() function checks an ACL structure for validity. gfs\_acl\_check function can check more for validity. **gfs\_acl\_calc\_mask**() function calculates and sets an ACL permissions of a GFARM\_ACL\_MASK type entry in an ACL structure. **gfs\_acl\_get\_tag\_type**() function gets an ACL tag (gfarm\_acl\_tag\_t) (type of ACL entry) from an ACL entry. **gfs\_acl\_set\_tag\_type**() function sets an ACL tag of an ACL entry. **gfs\_acl\_get\_permset**() function gets an ACL permission-set (gfarm\_acl\_permset\_t) from an ACL entry. **gfs\_acl\_set\_permset**() function an ACL permission-set of an ACL entry. **gfs\_acl\_add\_perm**() function 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. **gfs\_acl\_delete\_perm**() function deletes a permission from an ACL permission-set. **gfs\_acl\_get\_qualifier**() function gets a username/groupname from an ACL entry. GFARM\_ACL\_USER/GFARM\_ACL\_GROUP tag entries have a username/groupname. **gfs\_acl\_set\_qualifier**() function sets a username/groupname of an ACL entry. **gfs\_acl\_delete\_def\_file**() function deletes a Default ACL from a file or directory. **gfs\_acl\_get\_file**() function gets an ACL structure of a file or directory. **gfs\_acl\_set\_file**() function replaces an ACL structure of a file or directory. Before using this function, the ACL structure must be sorted by gfs\_acl\_sort function. **gfs\_acl\_to\_text**() function converts an ACL structure to an ACL text. gfs\_acl\_to\_any\_text function is more functional than this function. **gfs\_acl\_from\_text**() function creates an ACL structure from an ACL text. **gfs\_acl\_get\_perm**() function tests for an ACL permission in an ACL permission set. **gfs\_acl\_check**() function checks an ACL structure for validity. And, this function can get the place of the error and the ACL error code. This function is more functional than gfs\_acl\_valid function. **gfs\_acl\_error**() function converts an ACL error code of gfs\_acl\_check function to a text message. **gfs\_acl\_entries**() function returns the number of entries in an ACL structure. **gfs\_acl\_equiv\_mode**() checks for an equivalent ACL structure. An equivalent ACL structure has only base ACL entries of tag types (GFARM\_ACL\_USER\_OBJ, GFARM\_ACL\_GROUP\_OBJ, GFARM\_ACL\_OTHER). And, this function can create a file permission bits (gfarm\_mode\_t) from base ACL entries. **gfs\_acl\_cmp**() function compares two ACL structures. **gfs\_acl\_from\_mode**() function creates an ACL structure from file permission bits (gfarm\_mode\_t). **gfs\_acl\_to\_any\_text**() function converts an ACL structure to an ACL text. This function has some options for output format. This function is more functional than gfs\_acl\_to\_text function. **gfs\_acl\_to\_xattr\_value**() converts an ACL structure to ACL binary data for Extended Attribute value. Before using this function, the ACL structure must be sorted by gfs\_acl\_sort function. **gfs\_acl\_from\_xattr\_value**() converts ACL binary data for Extended Attribute value to an ACL structure. **gfs\_acl\_sort**() function sorts ACL entries of an ACL structure in ACL validity order. **gfs\_acl\_from\_text\_with\_default**() function creates two ACL structures (Access ACL and Default ACL) from an ACL text which includes "default:" prefix. ### Error handling Most Gfarm API returns the Gfarm error code in gfarm\_error\_t. **gfarm\_error\_string**() function returns a string describing the Gfarm error code. **gfarm\_errno\_to\_error**() function translates the error number (errno) to the Gfarm error code. **gfarm\_error\_to\_errno**() function translates the Gfarm error code to the error number. ### String Array manipulation utilities A gfarm\_stringlist type variable represents an array of strings, and this type is initialized by **gfarm\_stringlist\_init**() function. **gfarm\_stringlist\_add**() function is used to add a string to a gfarm\_stringlist. **gfarm\_stringlist\_cat**() function is used to add strings to a gfarm\_stringlist. **gfarm\_stringlist\_free**() function releases gfarm\_stringlist. **gfarm\_stringlist\_elem**() function or GFARM\_STRINGLIST\_ELEM() macro can be used to access each string of an array. **gfarm\_stringlist\_length**() function can be used to see number of strings in an array. **gfarm\_strings\_free\_deeply**() function releases a string array and each element of the array by calling standard library function free(). ### String Array manipulation macros GFARM\_STRINGLIST\_ELEM(list, i) represents *i*-th element of the *list* argument which type is gfarm\_stringlist. This macro can be used as a L-value. If this macro is used as a value, it returns same result with **gfarm\_stringlist\_elem**() function. GFARM\_STRINGLIST\_STRARRAY(list) returns pointer to first element of the *list* argument which type is gfarm\_stringlist. The type of the return value is a pointer to pointer to a character.