GFAL 2.0 generic file API

Functions

int gfal2_checksum (gfal2_context_t context, const char *url, const char *check_type, off_t start_offset, size_t data_length, char *checksum_buffer, size_t buffer_length, GError **err)
int gfal2_access (gfal2_context_t context, const char *url, int amode, GError **err)
 permission check
int gfal2_chmod (gfal2_context_t context, const char *url, mode_t mode, GError **err)
 change file access permissions
int gfal2_rename (gfal2_context_t context, const char *oldurl, const char *newurl, GError **err)
 change the name or location of a file
int gfal2_stat (gfal2_context_t context, const char *url, struct stat *buff, GError **err)
 posix file status
int gfal2_lstat (gfal2_context_t context, const char *url, struct stat *buff, GError **err)
 posix file status
int gfal2_mkdir (gfal2_context_t context, const char *url, mode_t mode, GError **err)
 create directory
int gfal2_mkdir_rec (gfal2_context_t context, const char *url, mode_t mode, GError **err)
 create directory
int gfal2_rmdir (gfal2_context_t context, const char *url, GError **err)
 suppress a directory
DIR * gfal2_opendir (gfal2_context_t context, const char *url, GError **err)
 open a directory for content listing
struct dirent * gfal2_readdir (gfal2_context_t context, DIR *d, GError **err)
 return the next directory entry
struct dirent * gfal2_readdirpp (gfal2_context_t context, DIR *d, struct stat *st, GError **err)
 return the next directory entry in addition of the entry meta-data
int gfal2_closedir (gfal2_context_t context, DIR *d, GError **err)
 close a directory handle
int gfal2_symlink (gfal2_context_t context, const char *oldpath, const char *newpath, GError **err)
 create a symbolic link
ssize_t gfal2_readlink (gfal2_context_t context, const char *path, char *buff, size_t buffsiz, GError **err)
 read a symbolic link value, provide the linked file path
int gfal2_unlink (gfal2_context_t context, const char *path, GError **err)
 Delete a file entry.
ssize_t gfal2_listxattr (gfal2_context_t context, const char *path, char *list, size_t size, GError **err)
 list extended attributes of a resource.
ssize_t gfal2_getxattr (gfal2_context_t context, const char *path, const char *name, void *value, size_t size, GError **err)
 get an extended attribute value of a resource.
int gfal2_setxattr (gfal2_context_t context, const char *path, const char *name, const void *value, size_t size, int flags, GError **err)
 set an extended attribute value of a resource.
int gfal2_bring_online (gfal2_context_t context, const char *path, time_t pintime, time_t timeout, char *token, size_t tsize, int async, GError **err)
 Bring online a file.
int gfal2_bring_online_poll (gfal2_context_t context, const char *path, const char *token, GError **err)
 Check for a bring online request.
int gfal2_release_file (gfal2_context_t context, const char *path, const char *token, GError **err)
 Release a file.
int gfal2_open (gfal2_context_t context, const char *path, int flag, GError **err)
 Open a file, return GFAL2 file descriptor.
int gfal2_open2 (gfal2_context_t context, const char *path, int flag, mode_t mode, GError **err)
int gfal2_creat (gfal2_context_t context, const char *filename, mode_t mode, GError **err)
ssize_t gfal2_read (gfal2_context_t context, int fd, void *buff, size_t s_buff, GError **err)
 read data from a GFAL2 file descriptor
ssize_t gfal2_write (gfal2_context_t context, int fd, const void *buff, size_t s_buff, GError **err)
 write data to a GFAL2 file descriptor
off_t gfal2_lseek (gfal2_context_t context, int fd, off_t offset, int whence, GError **err)
 move the file cursor
int gfal2_close (gfal2_context_t context, int fd, GError **err)
 close a file GFAL2 descriptor
int gfal2_flush (gfal2_context_t context, int fd, GError **err)
 flush all buffered data for the given file descriptor
ssize_t gfal2_pread (gfal2_context_t context, int fd, void *buffer, size_t count, off_t offset, GError **err)
ssize_t gfal2_pwrite (gfal2_context_t context, int fd, const void *buffer, size_t count, off_t offset, GError **err)

Detailed Description

GFAL 2.0 file API is the main entry point for file/directory operations

All functions report a EPROTONOSUPPORT GError if the url protocol does not support this operation.

Function Documentation

int gfal2_access ( gfal2_context_t  context,
const char *  url,
int  amode,
GError **  err 
)

permission check

check real user's permissions for a file

Parameters:
context : gfal2 handle, see gfal2_context_new
url : url of the file
amode : mode of the access
err : GError error report
Returns:
0 if success, else -1 and err MUST be set properly see gfal2 error system for more information gfal2_error_system
int gfal2_bring_online ( gfal2_context_t  context,
const char *  path,
time_t  pintime,
time_t  timeout,
char *  token,
size_t  tsize,
int  async,
GError **  err 
)

Bring online a file.

Parameters:
context : gfal2 handle, see gfal2_context_new
path : url of the file
pintime : pin time
timeout : timeout
token : The token will be put in the buffer pointed by this
async,: Asynchronous request (does not block if != 0)
err : GError error report
Returns:
0 if the request has been queued, > 0 if the file is pinned, < 0 on error
int gfal2_bring_online_poll ( gfal2_context_t  context,
const char *  path,
const char *  token,
GError **  err 
)

Check for a bring online request.

Parameters:
context : gfal2 handle, see gfal2_context_new
path : url of the file
token : As set by gfal2_bring_online
err : GError error report
Returns:
0 if the request is queued, > 0 if the file is pinned, < 0 on error
int gfal2_checksum ( gfal2_context_t  context,
const char *  url,
const char *  check_type,
off_t  start_offset,
size_t  data_length,
char *  checksum_buffer,
size_t  buffer_length,
GError **  err 
)

checksum

compute checksum function for a file url

Parameters:
context : gfal2 handle, see gfal2_context_new
url : url of the file
check_type : string of the checksum type ( GFAL_CHKSUM_MD5, GFAL_CHKSUM_SHA1, .. )
start_offset : offset in the file where the checksum calculation will start ( 0 : from begining )
data_length : size of data to compute for the checksum after start_offset ( 0 -: full file )
checksum_buffer : buffer with checksum string as result
buffer_length : maximum buffer length
err : GError error report
Returns:
0 if success, else -1 and err is be set see gfal2 error system for more information gfal2_error_system
int gfal2_chmod ( gfal2_context_t  context,
const char *  url,
mode_t  mode,
GError **  err 
)

change file access permissions

change the permissions of a file according to "mode"

Parameters:
context : gfal2 handle, see gfal2_context_new
url : url of the file or the folder
mode : right to configure
err : GError error report
Returns:
return 0 if success else -1 and err is be set see gfal2 error system for more information gfal2_error_system
int gfal2_close ( gfal2_context_t  context,
int  fd,
GError **  err 
)

close a file GFAL2 descriptor

Parameters:
context : gfal2 handle, see gfal2_context_new
fd : file descriptor
err : GError error report
Returns:
new cursor position if success, -1 if failure, set err properly in case of error.
int gfal2_closedir ( gfal2_context_t  context,
DIR *  d,
GError **  err 
)

close a directory handle

Parameters:
context : gfal2 handle, see gfal2_context_new
d : directory handle created by gfal2_opendir
err : GError error report
Returns:
0 if success, negative value if error, set err properly in case of error
int gfal2_creat ( gfal2_context_t  context,
const char *  filename,
mode_t  mode,
GError **  err 
)

gfal2_creat is equivalent to gfal2_open2 with flags equal to O_CREAT|O_WRONLY|O_TRUNC.

int gfal2_flush ( gfal2_context_t  context,
int  fd,
GError **  err 
)

flush all buffered data for the given file descriptor

Parameters:
context : gfal2 handle, see gfal2_context_new
fd : file descriptor
err : GError error report
Returns:
new cursor position if success, -1 if failure, set err properly in case of error.
ssize_t gfal2_getxattr ( gfal2_context_t  context,
const char *  path,
const char *  name,
void *  value,
size_t  size,
GError **  err 
)

get an extended attribute value of a resource.

Parameters:
context : gfal2 handle, see gfal2_context_new
path : path of the resource
name : key of the extended attribute
value : buffer for the extended attribute value
size : maximum size of the buffer to write
err : GError error report
Returns:
the size of the xattr value in bytes if success, -1 if error. set err properly in case of errors.
ssize_t gfal2_listxattr ( gfal2_context_t  context,
const char *  path,
char *  list,
size_t  size,
GError **  err 
)

list extended attributes of a resource.

Extended attributes keys are concatenated in the buffer and separated by a null character

Parameters:
context : gfal2 handle, see gfal2_context_new
path : path of the resource
list : buffer for the extended attribute keys
size : maximum size of the buffer to write
err : GError error report
Returns:
the size of the concatenated xattr keys in bytes if success, -1 if error. set err properly in case of errors.
off_t gfal2_lseek ( gfal2_context_t  context,
int  fd,
off_t  offset,
int  whence,
GError **  err 
)

move the file cursor

move the file cursor of the GFAL2 file descriptor fd to offset

Parameters:
context : gfal2 handle, see gfal2_context_new
fd : file descriptor
offset : new position of the cursor
whence : directive to follow, can be SEEK_SET, SEEK_CUR or SEEK_END
err : GError error report
Returns:
new cursor position if success, -1 if failure, set err properly in case of error.
int gfal2_lstat ( gfal2_context_t  context,
const char *  url,
struct stat *  buff,
GError **  err 
)

posix file status

get meta-data information about the file 'url' same behavior than gfal2_stat but return information about the link itself if "url" is a symbolic link

Parameters:
context : gfal2 handle, see gfal2_context_new
url : url of the file
buff : stat structure filled
err : GError error report
int gfal2_mkdir ( gfal2_context_t  context,
const char *  url,
mode_t  mode,
GError **  err 
)

create directory

create a directory at the address 'url'

Parameters:
context : gfal2 handle, see gfal2_context_new
url : url of the file
mode : directory file rights
err : GError error report
int gfal2_mkdir_rec ( gfal2_context_t  context,
const char *  url,
mode_t  mode,
GError **  err 
)

create directory

create a directory at the address 'url' create all the parent drectories and does not return an error if the directory already exist

Parameters:
context : gfal2 handle, see gfal2_context_new
url : url of the file
mode : directory file rights
err : GError error report
int gfal2_open ( gfal2_context_t  context,
const char *  path,
int  flag,
GError **  err 
)

Open a file, return GFAL2 file descriptor.

gfal_open supports the same flags than the POSIX open call

O_TRUNC If the file already exists and is a regular file and the open mode allows writing (i.e., is O_RDWR or O_WRONLY) it will be truncated to length 0. If the file is a FIFO or termi‐ nal device file, the O_TRUNC flag is ignored. Otherwise the effect of O_TRUNC is unspecified.

O_APPEND The file is opened in append mode. Before each write(2), the file offset is positioned at the end of the file, as if with lseek(2). O_APPEND may lead to corrupted files on NFS file systems if more than one process appends data to a file at once. This is because NFS does not support appending to a file, so the client kernel has to simulate it, which can't be done without a race condition.

O_CREAT If the file does not exist it will be created. The owner (user ID) of the file is set to the effective user ID of the process. The group ownership (group ID) is set either to the effective group ID of the process or to the group ID of the parent directory (depending on file system type and mount options, and the mode of the parent directory, see the mount options bsdgroups and sysvgroups described in mount(8)).

mode specifies the permissions to use in case a new file is created. This argument must be supplied when O_CREAT is specified in flags; if O_CREAT is not specified, then mode is ignored. The effective permissions are modified by the process's umask in the usual way: The permissions of the created file are (mode & ~umask). Note that this mode only applies to future accesses of the newly created file; the open() call that creates a read-only file may well return a read/write file descriptor.

O_DIRECT Try to minimize cache effects of the I/O to and from this file. In general this will degrade performance, but it is useful in special situations, such as when applications do their own caching. File I/O is done directly to/from user space buffers. The O_DIRECT flag on its own makes at an effort to transfer data synchronously, but does not give the guarantees of the O_SYNC that data and necessary metadata are transferred. To guarantee synchronous I/O the O_SYNC must be used in addition to O_DIRECT. See NOTES below for fur‐ ther discussion.

O_LARGEFILE (LFS) Allow files whose sizes cannot be represented in an off_t (but can be represented in an off64_t) to be opened. The _LARGEFILE64_SOURCE macro must be defined (before includ‐ ing any header files) in order to obtain this definition. Setting the _FILE_OFFSET_BITS feature test macro to 64 (rather than using O_LARGEFILE) is the preferred method of obtaining method of accessing large files on 32-bit systems

Parameters:
context : gfal2 handle, see gfal2_context_new
url : url of the file to open
flags : flags to use ( similar to open )
err : GError error report
Returns:
This routine return a valid file descriptor if the operation is a success or -1 if error occured. In case of Error, err is set properly
int gfal2_open2 ( gfal2_context_t  context,
const char *  path,
int  flag,
mode_t  mode,
GError **  err 
)

Same than gfal2_open but allow to specifie the default right of the file

DIR* gfal2_opendir ( gfal2_context_t  context,
const char *  url,
GError **  err 
)

open a directory for content listing

return a directory handle for content listing

Parameters:
context : gfal2 handle, see gfal2_context_new
url : url of the file
err : GError error report
Returns:
a directory handle in case of success or NULL if error occurs, set err properly in case of error
ssize_t gfal2_read ( gfal2_context_t  context,
int  fd,
void *  buff,
size_t  s_buff,
GError **  err 
)

read data from a GFAL2 file descriptor

Parameters:
context : gfal2 handle, see gfal2_context_new
fd : GFAL2 file descriptor of the file
buff : buffer for read data
size : maximum size to read
err : GError error report*
Returns:
On success, the number of bytes read is returned (zero indicates end of file), and the file position is advanced by this number. It is not an error if this number is smaller than the number of bytes requested. or a negative value is returned when an error occurs In case of Error, err is set properly
struct dirent* gfal2_readdir ( gfal2_context_t  context,
DIR *  d,
GError **  err 
) [read]

return the next directory entry

Parameters:
context : gfal2 handle, see gfal2_context_new
d : directory handle created by gfal2_opendir
err : GError error report
Returns:
pointer to a dirent struct if success, NULL if end of listing or error, set err properly in case of error
struct dirent* gfal2_readdirpp ( gfal2_context_t  context,
DIR *  d,
struct stat *  st,
GError **  err 
) [read]

return the next directory entry in addition of the entry meta-data

readdirpp get both of the directory entry informations and the stat informations in one operation, improving the performance in case of remote file system

Parameters:
context : gfal2 handle, see gfal2_context_new
d : directory handle created by gfal2_opendir
err : GError error report
Returns:
pointer to a dirent struct and configure st with the meta-data information if success, NULL if end of listing or error, set err properly in case of error
ssize_t gfal2_readlink ( gfal2_context_t  context,
const char *  path,
char *  buff,
size_t  buffsiz,
GError **  err 
)

read a symbolic link value, provide the linked file path

Symbolic links are not supported by all protocols, in case of non-supported feature GFAL2 always return an error and set err to the code EPROTONOSUPPORT. gfal2_readlink follows the POSIX behavior and does not add a null byte at the end of the buffer if the link is truncated.

Parameters:
context : gfal2 handle, see gfal2_context_new
path : path of the symbolic link to read
buff : buffer for symbolic link value
buffsiz : maximum number of bytes to write
err : GError error report
Returns:
size of the link value in bytes if success, negative value if error. set err properly in case of error
int gfal2_rename ( gfal2_context_t  context,
const char *  oldurl,
const char *  newurl,
GError **  err 
)

change the name or location of a file

move ( or rename ) the file 'oldurl' to 'newurl'

Parameters:
context : gfal2 handle, see gfal2_context_new
oldurl : the old url of the file
newurl : the new url of the file
err : GError error report
Returns:
: return 0 if success, else -1 if errors. see gfal2 error system for more information gfal2_error_system
int gfal2_rmdir ( gfal2_context_t  context,
const char *  url,
GError **  err 
)

suppress a directory

suppress a directory at the address 'url'

Parameters:
context : gfal2 handle, see gfal2_context_new
url : url of the file
err : GError error report
Returns:
0 if success, negative value if error, set err properly in case of error
int gfal2_setxattr ( gfal2_context_t  context,
const char *  path,
const char *  name,
const void *  value,
size_t  size,
int  flags,
GError **  err 
)

set an extended attribute value of a resource.

Parameters:
context : gfal2 handle, see gfal2_context_new
path : path of the resource
name : key of the extended attribute to define/set
value : new value of the xattr
size : size of the data
flags,: xattr flag, XATTR_CREATE specifies a pure create, which fails if the named attribute exists already. XATTR_REPLACE specifies a pure replace operation, which fails if the named attribute does not already exist. By default (no flags), the extended attribute will be created if need be, or will simply replace the value if the attribute exists.
err : GError error report
Returns:
0 if success, -1 if error. set err properly in case of errors.
int gfal2_stat ( gfal2_context_t  context,
const char *  url,
struct stat *  buff,
GError **  err 
)

posix file status

get meta-data information about the file 'url'

Parameters:
context : gfal2 handle, see gfal2_context_new
url : url of the file
buff : stat structure filled
err : GError error report
int gfal2_symlink ( gfal2_context_t  context,
const char *  oldpath,
const char *  newpath,
GError **  err 
)

create a symbolic link

Symbolic links are not supported by all protocols, in case of non-supported feature GFAL2 always return an error and set err to the code EPROTONOSUPPORT

Parameters:
context : gfal2 handle, see gfal2_context_new
oldpath : origin file
newpath : symbolic link path
err : GError error report
Returns:
0 if success, negative value if error, set err properly in case of error
int gfal2_unlink ( gfal2_context_t  context,
const char *  path,
GError **  err 
)

Delete a file entry.

Does not work for Collections or directory.

Parameters:
context : gfal2 handle, see gfal2_context_new
path : path of the file to delete
err : GError error report
Returns:
0 if success, -1 if error. set err properly in case of error
ssize_t gfal2_write ( gfal2_context_t  context,
int  fd,
const void *  buff,
size_t  s_buff,
GError **  err 
)

write data to a GFAL2 file descriptor

Parameters:
context : gfal2 handle, see gfal2_context_new
fd : GFAL2 file descriptor of the file
buff : buffer with data to write
s_buff : maximum size to write
err : GError error report*
Returns:
On success, the number of bytes written is returned (zero indicates end of file), and the file position is advanced by this number. It is not an error if this number is smaller than the number of bytes requested. or a negative value is returned when an error occurs. In case of Error, err is set properly
Generated on 28 Nov 2013 for GFAL2 by  doxygen 1.6.1