NAME
gfarm - Gfarm native API library
SYNOPSIS
#include <gfarm/gfarm.h>
DESCRIPTION
The Gfarm library provides an interface layer to the gfarm filesystem.
This manual only gives an overview of the library, please use manual
pages of each functions to see the detail of the functions.
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
gfs_pio_set_local(3) function specifies current node number and total
number of nodes as an initialization step of a parallel process. 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_set_view_index(3) function and
gfs_pio_set_view_local(3) function specifies an access method of a
parallel file.
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) functions reads a character from a stream, and
gfs_pio_ungetc(3) functions 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) functions 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_chdir(3) function changes current working directory.
gfs_realpath(3) function returns full pathname of the argument.
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 initilized 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_utimes(3)
function changes file’s modified 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_unlink_section(3) function removes a fragment which is a member of
a parallel file. 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.
UTILITY FUNCTIONS
gfarm_hostlist_read(3) function, gfarm_import_fragment_config_read(3)
function, and gfarm_import_fragment_size_alloc(3) function are utility
functions used to register a file as a fragmented parallel file. Please
see the source code of gfimport_text(1) command and gfimport_fixed(1)
command as an example how to use these functions.
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.
INTERNAL FUNCTIONS
gfarm_url_program_register(3) function, gfarm_url_hosts_schedule(3)
function, gfarm_url_fragments_replicate(3) function,
gfarm_url_program_deliver(3) function,
gfarm_url_section_replicate_from_to(3) function, and
gfarm_url_section_replicate_to(3) functions are internal functions of
Gfarm. These manual are provided by historical reasons, but these
specification may be changed later.