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.

Gfarm                                             26 June 2010                                          GFARM(3)