'\" t
.\" Title: gfarm
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 26 Jun 2010
.\" Manual: Gfarm
.\" Source: Gfarm
.\" Language: English
.\"
.TH "GFARM" "3" "26 Jun 2010" "Gfarm" "Gfarm"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
gfarm \- Gfarm file system API library
.SH "SYNOPSIS"
.sp
.nf
#include
.fi
.SH "DESCRIPTION"
.PP
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\&.
.SS "Initialize / Finalize"
.PP
\fBgfarm_initialize\fR()
function is used for the initilization of the Gfarm library, and
\fBgfarm_terminate\fR()
function is used for the termination of the library\&.
.SS "File input/output operations"
.PP
To open an existing file as a stream,
\fBgfs_pio_open\fR()
function is used\&. To create an file and open the file as a stream,
\fBgfs_pio_create\fR()
function is used\&.
\fBgfs_pio_close\fR()
function is used to close such streams\&.
.PP
\fBgfs_pio_error\fR()
function is used to see whether an error happens or not about a stream\&.
\fBgfs_pio_eof\fR()
function is used to see whether a stream, which is opened for read, already reaches end\-of\-file or not\&.
\fBgfs_pio_seek\fR()
function changes the current position of the stream\&.
.PP
\fBgfs_pio_getc\fR()
function reads a character from a stream, and
\fBgfs_pio_ungetc\fR()
function puts back a character to a stream\&.
\fBgfs_pio_getline\fR()
function,
\fBgfs_pio_gets\fR()
function, and
\fBgfs_pio_readline\fR()
function read one line from a stream, and
\fBgfs_pio_readdelim\fR()
function reads from stream until delimiter character, specified by the function argument, appears\&.
\fBgfs_pio_read\fR()
function reads specified bytes from a stream\&.
.PP
\fBgfs_pio_putc\fR()
function writes one character to a stream, and
\fBgfs_pio_putline\fR()
function and
\fBgfs_pio_puts\fR()
function write one line to a stream\&.
\fBgfs_pio_write\fR()
function writes specified bytes to a stream\&.
\fBgfs_pio_flush\fR()
function,
\fBgfs_pio_sync\fR()
function and
\fBgfs_pio_datasync\fR()
function moves buffered data to a storage device\&.
\fBgfs_pio_truncate\fR()
function truncates a file\&.
.SS "Directory access"
.PP
\fBgfs_opendir\fR()
function opens a directory, and
\fBgfs_readdir\fR()
function retrieves entries of the directory\&.
\fBgfs_closedir\fR()
function closes the directory\&.
.PP
A gfs_glob_t data, which is initialized by
\fBgfs_glob_init\fR()
function, can be passed to
\fBgfs_glob\fR()
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
\fBgfs_glob_free\fR()
function\&.
\fBgfs_glob_add\fR()
function is used add an entry to gfs_glob_t\&.
.SS "File / Directory manipulation"
.PP
\fBgfs_chmod\fR()
function changes the mode of a file, and
\fBgfs_chown\fR()
function changes the owner of a file, and
\fBgfs_utimes\fR()
function changes file\*(Aqs modification time and access time\&.
.PP
\fBgfs_mkdir\fR()
function creates a directory, and
\fBgfs_rmdir\fR()
function removes a directory\&.
\fBgfs_unlink\fR()
function removes a file, and
\fBgfs_rename\fR()
function renames a file or a directory\&.
.PP
\fBgfs_stat\fR()
function returns information like size, modified/access time, etc\&. The struct gfs_stat returned by gfs_stat function must be released by
\fBgfs_stat_free\fR()
function\&.
.SS "ACL (Access Control List) OPERATIONS"
.PP
\fBgfs_acl_init\fR()
function is used for the initilization of an ACL structure (gfarm_acl_t), and
\fBgfs_acl_free\fR()
function is used to release the ACL structure\&.
\fBgfs_acl_dup\fR()
function duplicates an ACL structure\&.
.PP
\fBgfs_acl_create_entry\fR()
function creates an ACL entry (gfarm_acl_entry_t) in an ACL structure, and
\fBgfs_acl_get_entry\fR()
function gets an ACL entry from the ACL structure, and
\fBgfs_acl_delete_entry\fR()
function removes an ACL entry from the ACL structure\&.
.PP
\fBgfs_acl_valid\fR()
function checks an ACL structure for validity\&. gfs_acl_check function can check more for validity\&.
.PP
\fBgfs_acl_calc_mask\fR()
function calculates and sets an ACL permissions of a GFARM_ACL_MASK type entry in an ACL structure\&.
.PP
\fBgfs_acl_get_tag_type\fR()
function gets an ACL tag (gfarm_acl_tag_t) (type of ACL entry) from an ACL entry\&.
\fBgfs_acl_set_tag_type\fR()
function sets an ACL tag of an ACL entry\&.
.PP
\fBgfs_acl_get_permset\fR()
function gets an ACL permission\-set (gfarm_acl_permset_t) from an ACL entry\&.
\fBgfs_acl_set_permset\fR()
function an ACL permission\-set of an ACL entry\&.
.PP
\fBgfs_acl_add_perm\fR()
function adds an ACL permission (gfarm_acl_perm_t) to an ACL permission\-set\&.
\fBgfs_acl_clear_perms\fR()
clears all ACL permissions from an ACL permission\-set\&.
\fBgfs_acl_delete_perm\fR()
function deletes a permission from an ACL permission\-set\&.
.PP
\fBgfs_acl_get_qualifier\fR()
function gets a username/groupname from an ACL entry\&. GFARM_ACL_USER/GFARM_ACL_GROUP tag entries have a username/groupname\&.
\fBgfs_acl_set_qualifier\fR()
function sets a username/groupname of an ACL entry\&.
.PP
\fBgfs_acl_delete_def_file\fR()
function deletes a Default ACL from a file or directory\&.
\fBgfs_acl_get_file\fR()
function gets an ACL structure of a file or directory\&.
\fBgfs_acl_set_file\fR()
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\&.
.PP
\fBgfs_acl_to_text\fR()
function converts an ACL structure to an ACL text\&. gfs_acl_to_any_text function is more functional than this function\&.
\fBgfs_acl_from_text\fR()
function creates an ACL structure from an ACL text\&.
.PP
\fBgfs_acl_get_perm\fR()
function tests for an ACL permission in an ACL permission set\&.
.PP
\fBgfs_acl_check\fR()
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\&.
\fBgfs_acl_error\fR()
function converts an ACL error code of gfs_acl_check function to a text message\&.
.PP
\fBgfs_acl_entries\fR()
function returns the number of entries in an ACL structure\&.
.PP
\fBgfs_acl_equiv_mode\fR()
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\&.
.PP
\fBgfs_acl_cmp\fR()
function compares two ACL structures\&.
.PP
\fBgfs_acl_from_mode\fR()
function creates an ACL structure from file permission bits (gfarm_mode_t)\&.
.PP
\fBgfs_acl_to_any_text\fR()
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\&.
.PP
\fBgfs_acl_to_xattr_value\fR()
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\&.
\fBgfs_acl_from_xattr_value\fR()
converts ACL binary data for Extended Attribute value to an ACL structure\&.
.PP
\fBgfs_acl_sort\fR()
function sorts ACL entries of an ACL structure in ACL validity order\&.
.PP
\fB gfs_acl_from_text_with_default\fR()
function creates two ACL structures (Access ACL and Default ACL) from an ACL text which includes "default:" prefix\&.
.SS "Error handling"
.PP
Most Gfarm API returns the Gfarm error code in gfarm_error_t\&.
\fBgfarm_error_string\fR()
function returns a string describing the Gfarm error code\&.
\fBgfarm_errno_to_error\fR()
function translates the error number (errno) to the Gfarm error code\&.
\fBgfarm_error_to_errno\fR()
function translates the Gfarm error code to the error number\&.
.SS "String Array manipulation utilities"
.PP
A gfarm_stringlist type variable represents an array of strings, and this type is initialized by
\fBgfarm_stringlist_init\fR()
function\&.
\fBgfarm_stringlist_add\fR()
function is used to add a string to a gfarm_stringlist\&.
\fBgfarm_stringlist_cat\fR()
function is used to add strings to a gfarm_stringlist\&.
\fBgfarm_stringlist_free\fR()
function releases gfarm_stringlist\&.
\fBgfarm_stringlist_elem\fR()
function or GFARM_STRINGLIST_ELEM() macro can be used to access each string of an array\&.
\fBgfarm_stringlist_length\fR()
function can be used to see number of strings in an array\&.
.PP
\fBgfarm_strings_free_deeply\fR()
function releases a string array and each element of the array by calling standard library function free()\&.
.SS "String Array manipulation macros"
.PP
GFARM_STRINGLIST_ELEM(list, i)
.RS 4
represents
\fIi\fR\-th element of the
\fIlist\fR
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
\fBgfarm_stringlist_elem\fR()
function\&.
.RE
.PP
GFARM_STRINGLIST_STRARRAY(list)
.RS 4
returns pointer to first element of the
\fIlist\fR
argument which type is gfarm_stringlist\&. The type of the return value is a pointer to pointer to a character\&.
.RE