GFARM(3)

NAME
gfarm - Gfarm file system API library

SYNOPSIS

#include <gfarm/gfarm.h>

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.