Man page - gfarm(3)

Packages contains this manual

Available languages:

en ja

Manual

GFARM

NAME
SYNOPSIS
DESCRIPTION
Initialize / Finalize
File input/output operations
Directory access
File / Directory manipulation
ACL (Access Control List) OPERATIONS
Error handling
String Array manipulation utilities
String Array manipulation macros

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.