gfarm

## 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.