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.