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(3) function is used for the  initilization  of  the  Gfarm  library,  and
       gfarm_terminate(3) function is used for the termination of the library.

   FILE INPUT/OUTPUT OPERATIONS
       To open an existing file as a stream, gfs_pio_open(3) function is used.  To create an file
       and open the file as a  stream,  gfs_pio_create(3)  function  is  used.   gfs_pio_close(3)
       function is used to close such streams.

       gfs_pio_error(3)  function  is used to see whether an error happens or not about a stream.
       gfs_pio_eof(3) function is used to see whether a stream, which is opened for read, already
       reaches  end-of-file or not.  gfs_pio_seek(3) function changes the current position of the
       stream.

       gfs_pio_getc(3) function reads a character from a stream, and  gfs_pio_ungetc(3)  function
       puts back a character to a stream.  gfs_pio_getline(3) function, gfs_pio_gets(3) function,
       and gfs_pio_readline(3) function read one line from  a  stream,  and  gfs_pio_readdelim(3)
       function  reads from stream until delimiter character, specified by the function argument,
       appears.  gfs_pio_read(3) function reads specified bytes from a stream.

       gfs_pio_putc(3) function writes one character to a stream, and gfs_pio_putline(3) function
       and gfs_pio_puts(3) function write one line to a stream.  gfs_pio_write(3) function writes
       specified bytes to a stream.   gfs_pio_flush(3)  function,  gfs_pio_sync(3)  function  and
       gfs_pio_datasync(3) function moves buffered data to a storage device.  gfs_pio_truncate(3)
       function truncates a file.

   DIRECTORY ACCESS
       gfs_opendir(3) function opens a directory, and gfs_readdir(3) function  retrieves  entries
       of the directory.  gfs_closedir(3) function closes the directory.

       A  gfs_glob_t  data,  which  is initialized by gfs_glob_init(3) function, can be passed to
       gfs_glob(3) 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(3) function.
       gfs_glob_add(3) function is used add an entry to gfs_glob_t.

   FILE / DIRECTORY MANIPULATION
       gfs_chmod(3) function changes the mode of a file, and gfs_chown(3)  function  changes  the
       owner  of  a  file, and gfs_utimes(3) function changes file's modification time and access
       time.

       gfs_mkdir(3) function creates a directory, and gfs_rmdir(3) function removes a  directory.
       gfs_unlink(3)  function  removes  a  file,  and gfs_rename(3) function renames a file or a
       directory.

       gfs_stat(3) 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(3) function.

   ERROR HANDLING
       Most  Gfarm  API  returns  the  Gfarm  error code in gfarm_error_t.  gfarm_error_string(3)
       function returns a  string  describing  the  Gfarm  error  code.   gfarm_errno_to_error(3)
       function    translates   the   error   number   (errno)   to   the   Gfarm   error   code.
       gfarm_error_to_errno(3) 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(3)  function.   gfarm_stringlist_add(3) function is
       used to add a string to a gfarm_stringlist.  gfarm_stringlist_cat(3) function is  used  to
       add   strings   to   a   gfarm_stringlist.    gfarm_stringlist_free(3)  function  releases
       gfarm_stringlist.  gfarm_stringlist_elem(3) function or GFARM_STRINGLIST_ELEM() macro  can
       be  used  to  access  each string of an array.  gfarm_stringlist_length(3) function can be
       used to see number of strings in an array.

       gfarm_strings_free_deeply(3) 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(3) 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.