POSIX-like API

Functions
int	gfal_chmod (const char *url, mode_t mode)
	change file access permissions
int	gfal_rename (const char *oldurl, const char *newurl)
	change the name or location of a file
int	gfal_stat (const char *url, struct stat *st)
	get the file status, follow links
int	gfal_lstat (const char *url, struct stat *st)
	get the file status, does not follow links
int	gfal_access (const char *url, int amode)
	check user permissions for a file
ssize_t	gfal_readlink (const char *url, char *buff, size_t buffsiz)
	resolve a link destination
int	gfal_symlink (const char *oldurl, const char *newurl)
	create a symbolic link
int	gfal_unlink (const char *url)
	unlink a file, delete it
int	gfal_mkdir (const char *url, mode_t mode)
	create a directory
DIR *	gfal_opendir (const char *url)
	open a directory
struct dirent *	gfal_readdir (DIR *d)
	read a directory
int	gfal_closedir (DIR *d)
	close a directory
int	gfal_rmdir (const char *url)
	delete a directory
int	gfal_creat (const char *url, mode_t mode)
	creat a file
int	gfal_open (const char *url, int flags,...)
	open a file
off_t	gfal_lseek (int fd, off_t off, int flags)
	reposition read/write file offset
int	gfal_close (int fd)
	close a gfal file descriptor
ssize_t	gfal_read (int fd, void *buff, size_t size)
	read from a gfal file descriptor
ssize_t	gfal_write (int fd, const void *buff, size_t size)
	write from a gfal file descriptor
int	gfal_flush (int fd)
	flush the given file descriptor
ssize_t	gfal_pread (int fd, void *buff, size_t size, off_t offset)
	parallel read from a gfal file descriptor
ssize_t	gfal_pwrite (int fd, const void *buff, size_t size, off_t offset)
	parallel write from a gfal file descriptor
ssize_t	gfal_getxattr (const char *url, const char *name, void *value, size_t size)
	retrieve an extended attribute value
ssize_t	gfal_listxattr (const char *url, char *list, size_t size)
	retrieve a list of the extended attributes availables
int	gfal_setxattr (const char *url, const char *name, const void *value, size_t size, int flags)
	define an extended attribute value
int	gfal_removexattr (const char *url, const char *name)
	delete a extended attribute value
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)
char *	gfal_version ()
gfal2_context_t	gfal_posix_get_context ()
	get context for advanced operation return the gfal2 context used for POSIX operations allow to do advanced operation ( config, checksum, transfer ) on this context

---

Function Documentation

int gfal_access	(	const char *	url,
		int	amode
	)

check user permissions for a file

Similar behavior to the POSIX access ( man 2 access )

Parameters:

	url	: url of the file to access
	amode	: access 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. In case of errors, see gfal_posix_check_error() for error management

Examples:

gfal_testchmod.c.

int gfal_chmod	(	const char *	url,
		mode_t	mode
	)

change file access permissions

Warnings about POSIX functions : some protocols do not permit a full POSIX support ( ex : no symlinks in srm:// URLs ) In case of a call to a unsupported function, -1 code is return and an error is set to EPROTONOSUPPORT

gfal_chmod changes the permissions of each given file according to mode, Similar behavior to the POSIX chmod ( man 2 chmod )

Parameters:

	url	: url 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 if errors occures. In case of errors, see gfal_posix_check_error() for error management

Examples:

gfal_testchmod.c.

int gfal_close

(

int

fd

)

close a gfal file descriptor

Similar behavior to the POSIX close ( man 2 close )

Parameters:

fd

: gfal file descriptor of the file

Returns:

This routine return 0 if the operation is a success or -1 if error occured. In case of errors, see gfal_posix_check_error() for error management

Examples:

gfal_testread.c, and gfal_testrw.c.

int gfal_closedir

(

DIR *

d

)

close a directory

Similar behavior to the POSIX closedir ( man 2 closedir )

Parameters:

d

: descriptor of the directory

Returns:

This routine return 0 if the operation was successful, or -1 if error occured. In case of errors, see gfal_posix_check_error() for error management

Examples:

gfal_testdir.c.

int gfal_creat	(	const char *	url,
		mode_t	mode
	)

creat a file

Similar behavior to the POSIX creat ( man 2 creat ) gfal_creat is similar to gfal_open with the flags O_CREAT|O_WRONLY|O_TRUNC

Parameters:

	url	: url of the file to creat
	mode	: mode of the file.

Returns:

This routine return a valid file descriptor if the operation is a success or -1 if error occured. In case of errors, see gfal_posix_check_error() for error management

int gfal_flush

(

int

fd

)

flush the given file descriptor

flush the current fiel descriptor, clear the cache \ and commit the changes. This call is reserved fora futur usage.

Parameters:

fd

: gfal file descriptor of the file

Returns:

On success, return 0. In case of errors, -1 is returned see gfal_posix_check_error() for error management

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

retrieve an extended attribute value

similar to the getxattr function

In gfal 2.0, this is the standard way to interact \ with advanced file properties

ex : gfal_getxattr("srm://myurl/endpoint", "user.replicas", buff, 256);

Parameters:

	url	: url of the file
	name	: key of the extended attribute
	value	: buffer for the extended attribute value
	size	: maximum size of the buffer

Returns:

On success, return the size of the extended attribute. In case of errors, -1 is returned see gfal_posix_check_error() for error management

Examples:

gfal_testget.c.

ssize_t gfal_listxattr	(	const char *	url,
		char *	list,
		size_t	size
	)

retrieve a list of the extended attributes availables

similar to the etxattr function

Parameters:

	url	: url of the file
	list	: buffer for the list of availables attributes concatened.
	size	: maximum size of the buffer

Returns:

On success, return the size of the list. In case of errors, -1 is returned see gfal_posix_check_error() for error management

off_t gfal_lseek	(	int	fd,
		off_t	off,
		int	flags
	)

reposition read/write file offset

Similar behavior to the POSIX lseek ( man 2 lseek )

Parameters:

	fd	: gfal file descriptor of the file
	off	: offset to set
	flags	: offset mode

Returns:

This routine return the current offset if the operation is a success or -1 if error occured. In case of errors, see gfal_posix_check_error() for error management

int gfal_lstat	(	const char *	url,
		struct stat *	st
	)

get the file status, does not follow links

return informations about the given files and links Similar behavior to the POSIX lstat ( man 2 lstat )

In case of protocols without the support of links, GFAL 2.0 \ convert this call to gfal_stat

Parameters:

	url	: url of the file
	st	: pointer to an allocated struct stat

Returns:

: return 0 if success, else -1 if errors. In case of errors, see gfal_posix_check_error() for error management

int gfal_mkdir	(	const char *	url,
		mode_t	mode
	)

create a directory

Similar behavior to the POSIX mkdir( man 2 mkdir )

Parameters:

	url	: url of the directory to create
	mode	: initial mode right of the directory

Returns:

This routine return 0 if the operation was successful, or -1 if error occured. In case of errors, see gfal_posix_check_error() for error management

Examples:

gfal_testcreatedir.c.

int gfal_open	(	const char *	url,
		int	flags,
			...
	)

open a file

Similar behavior to the POSIX open ( man 2 open ) 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:

	url	: url of the file to open
	flags	: flags to use ( similar to open )
	mode	(optional) : mode of the file in case of a new file.

Returns:

This routine return a valid file descriptor if the operation is a success or -1 if error occured. In case of errors, see gfal_posix_check_error() for error management

Examples:

gfal_testread.c, and gfal_testrw.c.

DIR* gfal_opendir

(

const char *

url

)

open a directory

Similar behavior to the POSIX opendir ( man 2 opendir )

Parameters:

url

: url of the directory to list

Returns:

This routine return a directory descriptor if the operation was successful, or -1 if error occured. In case of errors, see gfal_posix_check_error() for error management

Examples:

gfal_testdir.c.

int gfal_posix_check_error

(

)

safe and easy error management : -> if last error -> print on stderr, return 1 -> else do nothing

Returns:

0 if no error, 1 else

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 \ provided for convenience.

int gfal_posix_code_error

(

)

return the code associated with the last error. In case of POSIX calls and when possible, this code is similar to the local errno

Returns:

last error code or 0 if nothing

gfal2_context_t gfal_posix_get_context

(

)

get context for advanced operation return the gfal2 context used for POSIX operations allow to do advanced operation ( config, checksum, transfer ) on this context

Warning:

Delete this context leads to undefined behavior.

void gfal_posix_print_error

(

)

display the last error recorded to the standard output, provided for convenience.

void gfal_posix_release_error

(

)

display the last error to the standard output \ and clear it. provided for convenience.

char* gfal_posix_strerror_r	(	char *	buff_err,
		size_t	s_err
	)

Get the string representation of the last error

Parameters:

	buff_err	: buffer where string representation will be stored.
	s_err	: maximum message size

Returns:

return pointer to buff_err for convenience

ssize_t gfal_pread	(	int	fd,
		void *	buff,
		size_t	size,
		off_t	offset
	)

parallel read from a gfal file descriptor

Similar behavior to the POSIX pread ( man 2 pread )

In gfal 2.0, this call is thread-safe and allows the usage of \ parallels read at the same time on the same file descriptor.

This is the recommended way to execute parallels transfers.

This gfal_pread is emulated on filesystem that does not support it explicitely ( ex : rfio )

Parameters:

	fd	: gfal file descriptor of the file
	buff	: buffer for the read content
	size	: maximum size to read
	offset	: offset where the read start

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.In case of errors, see gfal_posix_check_error() for error management In case of errors, see gfal_posix_check_error() for error management

ssize_t gfal_pwrite	(	int	fd,
		const void *	buff,
		size_t	size,
		off_t	offset
	)

parallel write from a gfal file descriptor

Similar behavior to the POSIX pwrite ( man 2 pwrite )

In gfal 2.0, this function is thread-safe and allows the usage of parallels write at the same time on the same file descriptor.

This is the recommended way to execute parallels transfers.

This gfal_pwrite is emulated on filesystem that does not support it explicitely ( ex : rfio )

Parameters:

	fd	: gfal file descriptor of the file
	buff	: buffer for the write content
	size	: maximum size to write
	offset	: offset where the write start

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.In case of errors, see gfal_posix_check_error() for error management In case of errors, see gfal_posix_check_error() for error management

ssize_t gfal_read	(	int	fd,
		void *	buff,
		size_t	size
	)

read from a gfal file descriptor

Similar behavior to the POSIX read ( man 2 read )

Parameters:

	fd	: gfal file descriptor of the file
	buff	: buffer for the read content
	size	: maximum size to read

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.In case of errors, see gfal_posix_check_error() for error management In case of errors, see gfal_posix_check_error() for error management

Examples:

gfal_testread.c, and gfal_testrw.c.

struct dirent* gfal_readdir

(

DIR *

d

)

[read]

read a directory

the directory descriptor must be provided by gfal_opendir Similar behavior to the POSIX readdir ( man 2 readdir )

Parameters:

d

: descriptor of the directory

Returns:

This routine return the directory information if the operation was successful, NULL if the end of the directory is reached or if error occured. In case of errors, see gfal_posix_check_error() for error management

Examples:

gfal_testdir.c.

ssize_t gfal_readlink	(	const char *	url,
		char *	buff,
		size_t	buffsiz
	)

resolve a link destination

Similar behavior to the POSIX readlink ( man 2 readlink )

Some protocols can not support this functionality, \ check the protocol specification for more information.

Parameters:

	url	: url of the file to access, can be in supported protocols (lfn, srm, file, guid,..)
	buff	: buffer to fill
	buffsiz	: maximum size of the link destination

Returns:

This routine return the size of the link destination \ if the operation was successful, or -1 if error occured. In case of errors, see gfal_posix_check_error() for error management

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

delete a extended attribute value

similar to the removexattr function

Parameters:

	url	: url of the file
	name	: key of the extended attribute

Returns:

On success, return 0. In case of errors, -1 is returned see gfal_posix_check_error() for error management

int gfal_rename	(	const char *	oldurl,
		const char *	newurl
	)

change the name or location of a file

gfal_rename will rename the specified files by replacing the first occurrence of from in their name by to. gfal_rename implies two URL with the same protocols and generally on the same server. Similar behavior to the POSIX rename ( man 2 rename )

Parameters:

	oldurl	: the old url of the file
	newurl	: the new url of the file

Returns:

: return 0 if success, else -1 if errors. In case of errors, see gfal_posix_check_error() for error management

int gfal_rmdir

(

const char *

url

)

delete a directory

Similar behavior to the POSIX rmdir ( man 2 rmdir )

Parameters:

url

: url of the directory to suppress

Returns:

This routine return 0 if the operation was successful, or -1 if error occured. In case of errors, see gfal_posix_check_error() for error management

int gfal_set_verbose

(

int

)

set the gfal verbose mode

see gfal_constant.h for details

Examples:

gfal_testdir.c, and gfal_testget.c.

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

define an extended attribute value

similar to the listxattr function

In gfal 2.0, this is the standard way to interact \ with advanced file properties

ex : gfal_setxattr("srm://myurl/endpoint", "user.status", "ONLINE", strlen("ONLINE"),0); // -> simple brings_online

Parameters:

	url	: url of the file
	name	: key of the extended attribute
	value	: buffer for the extended attribute value
	size	: size of the attribute value
	flags	: mode

Returns:

On success, return 0 . In case of errors, -1 is returned see gfal_posix_check_error() for error management

int gfal_stat	(	const char *	url,
		struct stat *	st
	)

get the file status, follow links

return informations about the given files Similar behavior to the POSIX stat ( man 2 stat )

Parameters:

	url	: url of the file
	st	: pointer to an allocated struct stat

Returns:

: return 0 if success, else -1 if errors. In case of errors, see gfal_posix_check_error() for error management

int gfal_symlink	(	const char *	oldurl,
		const char *	newurl
	)

create a symbolic link

Similar behavior to the POSIX symlink ( man 2 symlink )

Some protocols can not support this functionality, \ check the protocol specification for more information.

Parameters:

	oldurl	: url of the original file
	newurl	: url of the symlink

Returns:

This routine return 0 if the operation was successful, or -1 if error occured. In case of errors, see gfal_posix_check_error() for error management

int gfal_unlink

(

const char *

url

)

unlink a file, delete it

Similar behavior to the POSIX unlink ( man 2 unlink )

Parameters:

url

: url of the file to delete

Returns:

This routine return 0 if the operation was successful, or -1 if error occured. In case of errors, see gfal_posix_check_error() for error management

char* gfal_version

(

)

get a string representation of the gfal version

Returns:

string of the gfal_version

ssize_t gfal_write	(	int	fd,
		const void *	buff,
		size_t	size
	)

write from a gfal file descriptor

Similar behavior to the POSIX write ( man 2 write )

Parameters:

	fd	: gfal file descriptor of the file
	buff	: buffer for the write content
	size	: maximum size to write

Returns:

On success, the number of bytes written is returned. In case of errors, -1 is returned see gfal_posix_check_error() for error management

Examples:

gfal_testrw.c.