CERN org.glite.Gfal  2.0.1
Functions
all POSIX style function

Functions

int gfal_chmod (const char *path, mode_t mode)
 change the right for a file or a folder
int gfal_rename (const char *oldpath, const char *newpath)
 change the name or location of a file oldpath and newpath need to be on the same plugin this functions work only with plugins (lfc ) and local files
int gfal_stat (const char *, struct stat *)
 informations about a file These functions return information about a file. No permissions are required on the file itself, but — in the case of stat() and lstat() — execute (search) permission is required on all of the directories in path that lead to the file.
int gfal_lstat (const char *, struct stat *)
 gfal_lstat is identical to gfal_stat except for symbolic links. In this case, the link itself is statted and not followed.
int gfal_access (const char *, int)
 test access to the given file
ssize_t gfal_readlink (const char *path, char *buff, size_t buffsiz)
int gfal_symlink (const char *oldpath, const char *newpath)
 make a new name for a file
int gfal_creat (const char *, mode_t)
 create a new file or truncate an existing one similar to the POSIX call creat opens a file according to the value of flags.
int gfal_open (const char *path, int flag,...)
 open a file similar to the POSIX call open opens a file according to the value of flags.
off_t gfal_lseek (int, off_t, int)
 set position in a file
int gfal_close (int)
 close a file similar to the POSIX call close closes the file whose descriptor fd is the one returned by gfal_open.
int gfal_read (int, void *, size_t)
 read a file similar to the POSIX call read gfal_read reads up to size bytes from the file descriptor fd into the buffer pointed by buff
int gfal_write (int, const void *, size_t)
 write a file similar to the POSIX call write gfal_write writes size bytes from the buffer pointed by buff to the file descriptor fd.
ssize_t gfal_pread (int fd, void *buffer, size_t count, off_t offset)
ssize_t gfal_pwrite (int fd, const void *buffer, size_t count, off_t offset)
ssize_t gfal_getxattr (const char *path, const char *name, void *value, size_t size)
 retrieve an extended attribute value
ssize_t gfal_listxattr (const char *path, char *list, size_t size)
 list all extended attributes
int gfal_setxattr (const char *path, const char *name, const void *value, size_t size, int flags)
 set an extended attribute to a given value similar to the setxattr standard call of libattr
int gfal_removexattr (const char *path, const char *name)
 removes the extended attribute identified by name and associated with the given path in the filesystem similar to the removexattr standard call of libattr
int gfal_mkdir (const char *, mode_t)
DIR * gfal_opendir (const char *)
 open a directory
int gfal_closedir (DIR *)
 close a file descriptor of a directory similar to the POSIX call closedir close the file descriptor of an opendir call
struct dirent * gfal_readdir (DIR *)
 read a directory similar to the POSIX call readdir The readdir() function returns a pointer to a dirent structure representing the next directory entry in the directory stream pointed to by dirp. It returns NULL on reaching the end of the directory stream or if an error occurred. struct dirent { ino_t d_ino; // inode number off_t d_off; // offset to the next dirent unsigned short d_reclen; // length of this record unsigned char d_type; // type of file; not supported // by all file system types char d_name[256]; // filename };
int gfal_rmdir (const char *)
 removes a directory if it is empty remove an existing directory, return error if the dir is not empty
int gfal_unlink (const char *)
 delete a name and possibly the file it refers to
int gfal_posix_check_error ()
void gfal_posix_clear_error ()
void gfal_posix_release_error ()
char * gfal_posix_strerror_r (char *buff_err, size_t s_err)
void gfal_posix_print_error ()
int gfal_posix_code_error ()
int gfal_set_verbose (int)
 set the verbose mode for the current program
char * gfal_version ()
int gfal_flush (int fd)
int gfal_set_parameter_string (const char *namespc, const char *key, const char *value)
char * gfal_get_parameter_string (const char *namespc, const char *key)
int gfal_set_parameter_string_list (const char *namespc, const char *key, const char *value[], size_t len)
char ** gfal_get_parameter_string_list (const char *namespc, const char *key, size_t *s_buff)
int gfal_set_parameter_int (const char *namespc, const char *key, int value)
int gfal_get_parameter_int (const char *namespc, const char *key)
int gfal_get_parameter_boolean (const char *namespc, const char *key)
int gfal_set_parameter_boolean (const char *namespc, const char *key, int bool_value)

Function Documentation

int gfal_access ( const char *  path,
int  amode 
)

test access to the given file

Parameters:
pathpath of the file to access, can be in supported protocols (lfn, srm, file, guid,..)
amodeaccess mode to check (R_OK, W_OK, X_OK or F_OK)
Returns:
This routine return 0 if the operation was successful, or -1 if error occured and errno is set, call gfal_posix_check_error() to check it.
Examples:
gfal_testchmod.c.
int gfal_chmod ( const char *  path,
mode_t  mode 
)

change the right for a file or a folder

Parameters:
path: path of the file or the folder, can be in all supported protocols (lfn, srm, file, guid,..)
mode: right to configure
Returns:
return 0 if success else -1 and errno is set, call gfal_posix_check_error() to check it
Examples:
gfal_testchmod.c.
int gfal_close ( int  fd)

close a file similar to the POSIX call close closes the file whose descriptor fd is the one returned by gfal_open.

Parameters:
fd: descriptor or the file given by gfal_open
Returns:
This routine returns 0 if the operation was successful or -1 if the operation failed. In the latter case, errno is set appropriately
Examples:
gfal_testread.c, and gfal_testrw.c.
int gfal_closedir ( DIR *  d)

close a file descriptor of a directory similar to the POSIX call closedir close the file descriptor of an opendir call

Parameters:
dfile handle ( return by opendir ) to close
Returns:
0 if success else negativevalue and errno is set ( ( gfal_posix_error_print() )
Examples:
gfal_testdir.c.
int gfal_creat ( const char *  filename,
mode_t  mode 
)

create a new file or truncate an existing one similar to the POSIX call creat opens a file according to the value of flags.

Parameters:
filename: url of the filename to create, can be in supported protocols (lfn, srm, file, guid,..)
mode: is used only if the file is created.
Returns:
return the file descriptor or -1 if errno is set call gfal_posix_check_error() to check it

References gfal_open().

ssize_t gfal_getxattr ( const char *  path,
const char *  name,
void *  value,
size_t  size 
)

retrieve an extended attribute value

similar to the getxattr call of the libattr gfal_getxattr retrieves an extended value for an url in a supported protocol. The extended attributes are use for the advanced file operations ( like set/get replicas, grid status, comments, etc... )

Parameters:
path: path of the file/dir, can be in supported protocols (lfn, srm, file, guid,..)
name,:name of the attribute to get
value,:pointer to buffer to get the value
size: size of the buffer
Returns:
return the size of the data returned, or -1 if error. In this case, errno is set and you can call gfal_posix_check_error() for a more complete description.
Examples:
gfal_testget.c.
ssize_t gfal_listxattr ( const char *  path,
char *  list,
size_t  size 
)

list all extended attributes

similar to listxattr standard call of libattr gfal_listxattr list all extended atributes associated with a file The extended attributes are use for the advanced file operations ( like set/get replicas, grid status, comments, etc... )

Parameters:
path: path of the file/dir, can be in a supported protocol (lfn, srm, file, guid,..)
list,:a list of the attribute in a string format, on after each other, separated by '\0'.
size: size of the buffer
Returns:
return the size of the data in list , or -1 if error. In this case, errno is set and you can call gfal_posix_check_error() for a more complete description.
off_t gfal_lseek ( int  fd,
off_t  offset,
int  whence 
)

set position in a file

similar to the POSIX call lseek gfal_lseek positions/repositions to offset the file associated with the descriptor fd generated by a previous gfal_open. whence indicates how to interpret the offset value:

SEEK_SET The offset is set from beginning of file.

SEEK_CUR The offset is added to current position.

SEEK_END The offset is added to current file size.

Parameters:
fd: file descriptor to lseek
offset,:offset in byte
whence,:flag
Returns:
This routine returns the actual offset from the beginning of the file if the operation was successful or -1 if the operation failed. In the latter case, errno is set appropriately, you can call gfal_posix_check_error() for a more complete description.

References gfal_posix_internal_lseek().

int gfal_mkdir ( const char *  path,
mode_t  mode 
)

Wrapper to mkdir for comptibility, same behavior than gfal_mkdirp ( but subject to change in order to follow POSIX mkdir in the futur )

Examples:
gfal_testcreatedir.c.

References gfal_mkdirp().

int gfal_open ( const char *  path,
int  flag,
  ... 
)

open a file similar to the POSIX call open opens a file according to the value of flags.

Parameters:
path: url of the filename to open. can be in supported protocols (lfn, srm, file, guid,..)
flag: same flag supported value is built by OR’ing the bits defined in <fcntl.h> but one and only one of the first three flags below must be used O_RDONLY open for reading only O_WRONLY open for writing only O_RDWR open for reading and writing O_CREAT If the file exists already and O_EXCL is also set, gfal_open will fail O_LARGEFILE allows files whose sizes cannot be represented in 31 bits to be opened
modeis used only if the file is created.
Returns:
return the file descriptor or -1 if errno is set call gfal_posix_check_error() to check it
Examples:
gfal_testread.c, and gfal_testrw.c.

References gfal_posix_internal_open().

Referenced by gfal_creat().

DIR* gfal_opendir ( const char *  name)

open a directory

opens a directory to be used in subsequent gfal_readdir operations the url supported are : local files, surls, plugin url ( lfc,...)

Parameters:
nameof the directory to open, can be in supported protocols (lfn, srm, file, guid,..)
Returns:
file descriptor DIR* if success else NULL if error and errno is set call gfal_posix_check_error() to check it
Examples:
gfal_testdir.c.
int gfal_posix_check_error ( )

check the last Error, if no error report return 0 else return 1 and print the error on stderr

Warning:
this does not clear the error
Examples:
gfal_testchmod.c, gfal_testcreatedir.c, gfal_testget.c, gfal_testread.c, and gfal_testrw.c.
void gfal_posix_clear_error ( )

clear the last error reported by a gfal posix function

Referenced by gfal_posix_release_error().

int gfal_posix_code_error ( )

return the last error code ( ERRNO-style ) most of the error code are ERRNO codes.

Returns:
last error code reported or 0 if nothing.
void gfal_posix_print_error ( )

print the last string error reported by the gfal error system for the posix API but DO NOT delete it Errors are printed on stderr

Referenced by gfal_posix_release_error().

void gfal_posix_release_error ( )

Display and clear the last string error reported by the gfal error system for the posix API equivalent to a gfal_posix_print_error() and a gfal_posix_clear_error() call

References gfal_posix_print_error(), and gfal_posix_clear_error().

char* gfal_posix_strerror_r ( char *  buff_err,
size_t  s_err 
)

Get the last Error in a string format

Returns:
return a pointer to the string buffer passed.

References gfal_str_GError_r().

ssize_t gfal_pread ( int  fd,
void *  buffer,
size_t  count,
off_t  offset 
)

pipelined call for read call, support parallels access similar to system call pread

Parameters:
fd: file descriptor
buffer: buffer with the data
s_buff: maximum size of the buffer
offset: offset in bytes
Returns:
return the number of bytes read, 0 means end of the file, and you can call gfal_posix_check_error() for a more complete description

References gfal_posix_internal_pread().

ssize_t gfal_pwrite ( int  fd,
const void *  buffer,
size_t  count,
off_t  offset 
)

pipelined write for write call, support parallels access similar to system call pwrite

Parameters:
fd: file descriptor
buffer: buffer with the data
s_buff: maximum size of the buffer
offset: offset in bytes
Returns:
return the number of bytes write, 0 means end of the file, and you can call gfal_posix_check_error() for a more complete description

References gfal_posix_internal_pwrite().

int gfal_read ( int  fd,
void *  buff,
size_t  s_buff 
)

read a file similar to the POSIX call read gfal_read reads up to size bytes from the file descriptor fd into the buffer pointed by buff

Parameters:
fdfile descriptor
buffbuffer of the data to read
s_buffsize of the data read in bytes
Returns:
number of byte read or -1 if error, errno is set call gfal_posix_check_error() to check it
Examples:
gfal_testread.c, and gfal_testrw.c.

References gfal_posix_internal_read().

struct dirent* gfal_readdir ( DIR *  d) [read]

read a directory similar to the POSIX call readdir The readdir() function returns a pointer to a dirent structure representing the next directory entry in the directory stream pointed to by dirp. It returns NULL on reaching the end of the directory stream or if an error occurred. struct dirent { ino_t d_ino; // inode number off_t d_off; // offset to the next dirent unsigned short d_reclen; // length of this record unsigned char d_type; // type of file; not supported // by all file system types char d_name[256]; // filename };

Parameters:
dfile handle ( return by opendir ) to read
Returns:
pointer to struct dirent with file information or NULL if end of list or error, errno is set call gfal_posix_check_error() to check it
Warning:
struct dirents are allocated statically, do not use free() on them
Examples:
gfal_testdir.c.

References gfal_posix_internal_readdir().

int gfal_removexattr ( const char *  path,
const char *  name 
)

removes the extended attribute identified by name and associated with the given path in the filesystem similar to the removexattr standard call of libattr

the effect of this call can be specific to the plugin used. ( ex : guid are read only)

Parameters:
path: path of the file
name: key of the extended to remove
Returns:
0 if success or -1 if error. In this case, errno is set and you can call gfal_posix_check_error() for a more complete description.
int gfal_rename ( const char *  oldpath,
const char *  newpath 
)

change the name or location of a file oldpath and newpath need to be on the same plugin this functions work only with plugins (lfc ) and local files

Parameters:
oldpath: the old path of the file, can be in supported protocols but need to be in the same adress space than newpath
newpath: the new path of the file, can be in supported protocols (lfn, srm, file, guid,..)
Returns:
: return 0 if success, else -1 and errno / gfal_posix_check_error()
Examples:
gfal_testcreatedir.c.
int gfal_rmdir ( const char *  path)

removes a directory if it is empty remove an existing directory, return error if the dir is not empty

Parameters:
pathspecifies the directory name, can be in supported protocols (lfn, srm, file, guid,..)
Returns:
return 0 is success else -1 and errno is set call gfal_posix_check_error() to check it
Examples:
gfal_testcreatedir.c.

References gfal_posix_internal_rmdir().

int gfal_set_verbose ( int  value)

set the verbose mode for the current program

set the verbose level of gfal 2

int gfal_setxattr ( const char *  path,
const char *  name,
const void *  value,
size_t  size,
int  flags 
)

set an extended attribute to a given value similar to the setxattr standard call of libattr

the effect of this call can be specific to the plugin used. ( ex : guid are read only)

Parameters:
path: path of the file
name: key of the extended atribute to set
value: value to set, must be at least of the size size
size: size of the attriute to set
flags: flags similar to the setxattr call, can be ignored by some plugins/call
Returns:
0 if success else or -1 if error. In this case, errno is set and you can call gfal_posix_check_error() for a more complete description.

References gfal_posix_internal_setxattr().

int gfal_stat ( const char *  path,
struct stat *  buff 
)

informations about a file These functions return information about a file. No permissions are required on the file itself, but — in the case of stat() and lstat() — execute (search) permission is required on all of the directories in path that lead to the file.

Parameters:
path: path of the file, can be in supported protocols (lfn, srm, file, guid,..)
buff: pointer to an allocated struct stat
Returns:
return 0 if success else -1 and errno is set, call gfal_posix_check_error() to check it

References gfal_posix_internal_stat().

int gfal_symlink ( const char *  oldpath,
const char *  newpath 
)

make a new name for a file

similar to the POSIX call symlink . symlink() creates a symbolic link named newpath which contains the string oldpath.

Parameters:
newpath: path of the link, can be in supported protocols but need to be in the same adress space than newpath
oldpath: path of the linked file, can be in supported protocols (lfn, srm, file, guid,..)
Returns:
0 if success else -1. if failure, errno is set, you can call gfal_posix_check_error() for a more complete description.

References gfal_posix_internal_symlink().

int gfal_unlink ( const char *  path)

delete a name and possibly the file it refers to

similar to the POSIX call unlink gfal_unlink() deletes a name from the file system. If that name was the last link to a file and no processes have the file open the file is deleted and the space it was using is made avail‐ able for reuse.

If the name was the last link to a file but any processes still have the file open the file will remain in existence until the last file descriptor referring to it is closed.

If the name referred to a symbolic link the link is removed.

If the name referred to a socket, fifo or device the name for it is removed but processes which have the object open may continue to use it.

Returns:
On success, zero is returned. On error, -1 is returned, and errno is set appropriately and you can call gfal_posix_check_error() for a more complete description.

References gfal_posix_internal_unlink().

char* gfal_version ( )

return a string of the current gfal version

int gfal_write ( int  fd,
const void *  buff,
size_t  s_buff 
)

write a file similar to the POSIX call write gfal_write writes size bytes from the buffer pointed by buff to the file descriptor fd.

Parameters:
fdfile descriptor
buffbuffer of the data to write
s_buffsize of the data write in bytes
Returns:
number of byte write or -1 if error, errno is set call gfal_posix_check_error() to check it
Examples:
gfal_testrw.c.

References gfal_posix_internal_write().