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.