<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">


<refentry id="gfarm.3">

<refentryinfo><date>26 Jun 2010</date></refentryinfo>

<refmeta>
<refentrytitle>gfarm</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Gfarm</refmiscinfo>
</refmeta>

<refnamediv id="name">
<refname>gfarm</refname>
<refpurpose>Gfarm file system API library</refpurpose>
</refnamediv>
<refsynopsisdiv id="synopsis">
<synopsis format="linespecific">
#include &lt;gfarm/gfarm.h&gt;

</synopsis>
</refsynopsisdiv>

<!-- body begins here -->

<refsect1 id="description"><title>DESCRIPTION</title>
<para>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.
</para>

<refsect2 id="initialize-finalize">
<title>Initialize / Finalize</title>
<para>
<citerefentry>
<refentrytitle>gfarm_initialize</refentrytitle>
</citerefentry> function is used for the initilization of the Gfarm
library, and
<citerefentry>
<refentrytitle>gfarm_terminate</refentrytitle>
</citerefentry> function is used for the termination of the library.
</para>
</refsect2>

<refsect2 id="input-output-operations">
<title>File input/output operations</title>
<para>
To open an existing file as a stream,
<citerefentry>
<refentrytitle>gfs_pio_open</refentrytitle>
</citerefentry> function is used.
To create an file and open the file as a stream,
<citerefentry>
<refentrytitle>gfs_pio_create</refentrytitle>
</citerefentry> function is used.
<citerefentry>
<refentrytitle>gfs_pio_close</refentrytitle>
</citerefentry> function is used to close such streams.
</para>

<para>
<citerefentry>
<refentrytitle>gfs_pio_error</refentrytitle>
</citerefentry> function is used to see whether an error happens or not
about a stream.
<citerefentry>
<refentrytitle>gfs_pio_eof</refentrytitle>
</citerefentry> function is used to see whether a stream,
which is opened for read, already reaches end-of-file or not.
<citerefentry>
<refentrytitle>gfs_pio_seek</refentrytitle>
</citerefentry> function changes the current position of the stream.
</para>

<para>
<citerefentry>
<refentrytitle>gfs_pio_getc</refentrytitle>
</citerefentry> function reads a character from a stream, and
<citerefentry>
<refentrytitle>gfs_pio_ungetc</refentrytitle>
</citerefentry> function puts back a character to a stream.
<citerefentry>
<refentrytitle>gfs_pio_getline</refentrytitle>
</citerefentry> function,
<citerefentry>
<refentrytitle>gfs_pio_gets</refentrytitle>
</citerefentry> function, and
<citerefentry>
<refentrytitle>gfs_pio_readline</refentrytitle>
</citerefentry> function read one line from a stream, and
<citerefentry>
<refentrytitle>gfs_pio_readdelim</refentrytitle>
</citerefentry> function reads from stream until delimiter character,
specified by the function argument, appears.
<citerefentry>
<refentrytitle>gfs_pio_read</refentrytitle>
</citerefentry> function reads specified bytes from a stream.
</para>

<para>
<citerefentry>
<refentrytitle>gfs_pio_putc</refentrytitle>
</citerefentry> function writes one character to a stream, and
<citerefentry>
<refentrytitle>gfs_pio_putline</refentrytitle>
</citerefentry> function and
<citerefentry>
<refentrytitle>gfs_pio_puts</refentrytitle>
</citerefentry> function write one line to a stream.
<citerefentry>
<refentrytitle>gfs_pio_write</refentrytitle>
</citerefentry> function writes specified bytes to a stream.
<citerefentry>
<refentrytitle>gfs_pio_flush</refentrytitle>
</citerefentry> function,
<citerefentry>
<refentrytitle>gfs_pio_sync</refentrytitle>
</citerefentry> function and
<citerefentry>
<refentrytitle>gfs_pio_datasync</refentrytitle>
</citerefentry> function moves buffered data to a storage device.

<citerefentry>
<refentrytitle>gfs_pio_truncate</refentrytitle>
</citerefentry> function truncates a file.
</para>
</refsect2>

<refsect2 id="directory-access">
<title>Directory access</title>
<!--
<para>
<citerefentry>
<refentrytitle>gfs_chdir</refentrytitle>
</citerefentry> function changes current working directory.
<citerefentry>
<refentrytitle>gfs_realpath</refentrytitle>
</citerefentry> function returns full pathname of the argument.
</para>
 -->
<para>
<citerefentry>
<refentrytitle>gfs_opendir</refentrytitle>
</citerefentry> function opens a directory, and
<citerefentry>
<refentrytitle>gfs_readdir</refentrytitle>
</citerefentry> function retrieves entries of the directory.
<citerefentry>
<refentrytitle>gfs_closedir</refentrytitle>
</citerefentry> function closes the directory.
</para>

<para>
A gfs_glob_t data, which is initialized by
<citerefentry>
<refentrytitle>gfs_glob_init</refentrytitle>
</citerefentry> function,
can be passed to
<citerefentry>
<refentrytitle>gfs_glob</refentrytitle>
</citerefentry> 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 
<citerefentry>
<refentrytitle>gfs_glob_free</refentrytitle>
</citerefentry> function.
<citerefentry>
<refentrytitle>gfs_glob_add</refentrytitle>
</citerefentry> function is used add an entry to gfs_glob_t.
</para>
</refsect2>

<refsect2 id="file-directory-manipulation">
<title>File / Directory manipulation</title>
<para>
<citerefentry>
<refentrytitle>gfs_chmod</refentrytitle>
</citerefentry> function changes the mode of a file, and
<citerefentry>
<refentrytitle>gfs_chown</refentrytitle>
</citerefentry> function changes the owner of a file, and
<citerefentry>
<refentrytitle>gfs_utimes</refentrytitle>
</citerefentry> function changes file's modification time and access time.
</para>

<para>
<citerefentry>
<refentrytitle>gfs_mkdir</refentrytitle>
</citerefentry> function creates a directory, and
<citerefentry>
<refentrytitle>gfs_rmdir</refentrytitle>
</citerefentry> function removes a directory.
<citerefentry>
<refentrytitle>gfs_unlink</refentrytitle>
</citerefentry> function removes a file, and
<citerefentry>
<refentrytitle>gfs_rename</refentrytitle>
</citerefentry> function renames a file or a directory.
</para>

<para>
<citerefentry>
<refentrytitle>gfs_stat</refentrytitle>
</citerefentry> function returns information like size, modified/access
time, etc.
The struct gfs_stat returned by gfs_stat function must be released by
<citerefentry>
<refentrytitle>gfs_stat_free</refentrytitle>
</citerefentry> function.
</para>
</refsect2>

<refsect2 id="acl-operations">
<title>ACL (Access Control List) OPERATIONS</title>
<para>
<citerefentry>
<refentrytitle>gfs_acl_init</refentrytitle>
</citerefentry> function is used for the initilization of an ACL
structure (gfarm_acl_t), and
<citerefentry>
<refentrytitle>gfs_acl_free</refentrytitle>
</citerefentry> function is used to release the ACL structure.
<citerefentry>
<refentrytitle>gfs_acl_dup</refentrytitle>
</citerefentry> function duplicates an ACL structure.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_create_entry</refentrytitle>
</citerefentry> function creates an ACL entry (gfarm_acl_entry_t) in
an ACL structure, and
<citerefentry>
<refentrytitle>gfs_acl_get_entry</refentrytitle>
</citerefentry> function gets an ACL entry from the ACL structure, and
<citerefentry>
<refentrytitle>gfs_acl_delete_entry</refentrytitle>
</citerefentry> function removes an ACL entry from the ACL structure.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_valid</refentrytitle>
</citerefentry> function checks an ACL structure for validity.
gfs_acl_check function can check more for
validity.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_calc_mask</refentrytitle>
</citerefentry> function calculates and sets an ACL permissions of
a GFARM_ACL_MASK type entry in an ACL structure.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_get_tag_type</refentrytitle>
</citerefentry> function gets an ACL tag (gfarm_acl_tag_t) (type of
ACL entry) from an ACL entry.
<citerefentry>
<refentrytitle>gfs_acl_set_tag_type</refentrytitle>
</citerefentry> function sets an ACL tag of an ACL entry.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_get_permset</refentrytitle>
</citerefentry> function gets an ACL permission-set
(gfarm_acl_permset_t) from an ACL entry.
<citerefentry>
<refentrytitle>gfs_acl_set_permset</refentrytitle>
</citerefentry> function an ACL permission-set of an ACL entry.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_add_perm</refentrytitle>
</citerefentry> function adds an ACL permission (gfarm_acl_perm_t) to
an ACL permission-set.
<citerefentry>
<refentrytitle>gfs_acl_clear_perms</refentrytitle>
</citerefentry> clears all ACL permissions from an ACL permission-set.
<citerefentry>
<refentrytitle>gfs_acl_delete_perm</refentrytitle>
</citerefentry> function deletes a permission from an ACL permission-set.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_get_qualifier</refentrytitle>
</citerefentry> function gets a username/groupname from an ACL entry.
GFARM_ACL_USER/GFARM_ACL_GROUP tag entries have a username/groupname.
<citerefentry>
<refentrytitle>gfs_acl_set_qualifier</refentrytitle>
</citerefentry> function sets a username/groupname of an ACL entry.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_delete_def_file</refentrytitle>
</citerefentry> function deletes a Default ACL from a file or directory.
<citerefentry>
<refentrytitle>gfs_acl_get_file</refentrytitle>
</citerefentry> function gets an ACL structure of a file or directory.
<citerefentry>
<refentrytitle>gfs_acl_set_file</refentrytitle>
</citerefentry> 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.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_to_text</refentrytitle>
</citerefentry> function converts an ACL structure to an ACL text.
gfs_acl_to_any_text function is more
functional than this function.
<citerefentry>
<refentrytitle>gfs_acl_from_text</refentrytitle>
</citerefentry> function creates an ACL structure from an ACL text.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_get_perm</refentrytitle>
</citerefentry> function tests for an ACL permission in an ACL
permission set.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_check</refentrytitle>
</citerefentry> 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.
<citerefentry>
<refentrytitle>gfs_acl_error</refentrytitle>
</citerefentry> function converts an ACL error code of
gfs_acl_check function to a text message.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_entries</refentrytitle>
</citerefentry> function returns the number of entries in an ACL structure.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_equiv_mode</refentrytitle>
</citerefentry> 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.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_cmp</refentrytitle>
</citerefentry> function compares two ACL structures.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_from_mode</refentrytitle>
</citerefentry> function creates an ACL structure from file permission
bits (gfarm_mode_t).
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_to_any_text</refentrytitle>
</citerefentry> 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.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_to_xattr_value</refentrytitle>
</citerefentry> 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.
<citerefentry>
<refentrytitle>gfs_acl_from_xattr_value</refentrytitle>
</citerefentry> converts ACL binary data for Extended Attribute value
to an ACL structure.
</para>
<para>
<citerefentry>
<refentrytitle>gfs_acl_sort</refentrytitle>
</citerefentry> function sorts ACL entries of an ACL structure in ACL
validity order.
</para>
<para>
<citerefentry>
<refentrytitle>
gfs_acl_from_text_with_default</refentrytitle>
</citerefentry> function creates two ACL structures (Access ACL and
Default ACL) from an ACL text which includes "default:" prefix.
</para>
</refsect2>


<refsect2 id="error-handling">
<title>Error handling</title>
<para>
Most Gfarm API returns the Gfarm error code in gfarm_error_t.
<citerefentry>
<refentrytitle>gfarm_error_string</refentrytitle>
</citerefentry> function returns a string describing the Gfarm error code.
<citerefentry>
<refentrytitle>gfarm_errno_to_error</refentrytitle>
</citerefentry> function translates the error number (errno) to the Gfarm
error code.
<citerefentry>
<refentrytitle>gfarm_error_to_errno</refentrytitle>
</citerefentry> function translates the Gfarm error code to the error number.
</para>
</refsect2>

<refsect2 id="string-array-manipulation-utilities">
<title>String Array manipulation utilities</title>
<para>
A gfarm_stringlist type variable represents an array of strings,
and this type is initialized by
<citerefentry>
<refentrytitle>gfarm_stringlist_init</refentrytitle>
</citerefentry> function.
<citerefentry>
<refentrytitle>gfarm_stringlist_add</refentrytitle>
</citerefentry> function is used to add a string to a gfarm_stringlist.
<citerefentry>
<refentrytitle>gfarm_stringlist_cat</refentrytitle>
</citerefentry> function is used to add strings to a gfarm_stringlist.
<citerefentry>
<refentrytitle>gfarm_stringlist_free</refentrytitle>
</citerefentry> function releases gfarm_stringlist.
<citerefentry>
<refentrytitle>gfarm_stringlist_elem</refentrytitle>
</citerefentry> function or
GFARM_STRINGLIST_ELEM() macro
can be used to access each string of an array.
<citerefentry>
<refentrytitle>gfarm_stringlist_length</refentrytitle>
</citerefentry> function can be used to see number of strings in an array.
</para>

<para>
<citerefentry>
<refentrytitle>gfarm_strings_free_deeply</refentrytitle>
</citerefentry> function releases a string array and each element of the
array by calling standard library function free().
</para>

</refsect2>

<refsect2 id="string-array-manipulation-macros">
<title>String Array manipulation macros</title>
<variablelist>

<varlistentry>
<term>GFARM_STRINGLIST_ELEM(list, i)</term>
<listitem>
<para>
represents <parameter moreinfo="none">i</parameter>-th element of
the <parameter moreinfo="none">list</parameter> 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
<citerefentry>
<refentrytitle>gfarm_stringlist_elem</refentrytitle>
</citerefentry> function.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>GFARM_STRINGLIST_STRARRAY(list)</term>
<listitem>
<para>
returns pointer to first element of the <parameter moreinfo="none">list</parameter> argument
which type is gfarm_stringlist.
The type of the return value is a pointer to pointer to a character.
</para>
</listitem>

</varlistentry>
</variablelist>

</refsect2>

</refsect1>

</refentry>
