diff options
Diffstat (limited to 'api/src/glfs.h')
| -rw-r--r-- | api/src/glfs.h | 1242 |
1 files changed, 971 insertions, 271 deletions
diff --git a/api/src/glfs.h b/api/src/glfs.h index 8b5782ef084..279d11d58ee 100644 --- a/api/src/glfs.h +++ b/api/src/glfs.h @@ -1,5 +1,5 @@ /* - Copyright (c) 2012 Red Hat, Inc. <http://www.redhat.com> + Copyright (c) 2012-2018 Red Hat, Inc. <http://www.redhat.com> This file is part of GlusterFS. This file is licensed to you under your choice of the GNU Lesser @@ -8,7 +8,6 @@ cases as published by the Free Software Foundation. */ - #ifndef _GLFS_H #define _GLFS_H @@ -21,6 +20,17 @@ both the library and the application. */ +/* Values for valid flags to be used when using XXXsetattr, to set multiple + attribute values passed via the related stat structure. + */ + +#define GFAPI_SET_ATTR_MODE 0x1 +#define GFAPI_SET_ATTR_UID 0x2 +#define GFAPI_SET_ATTR_GID 0x4 +#define GFAPI_SET_ATTR_SIZE 0x8 +#define GFAPI_SET_ATTR_ATIME 0x10 +#define GFAPI_SET_ATTR_MTIME 0x20 + #ifndef _FILE_OFFSET_BITS #define _FILE_OFFSET_BITS 64 #endif @@ -41,6 +51,40 @@ #include <sys/cdefs.h> #include <dirent.h> #include <sys/statvfs.h> +#include <stdint.h> +#include <sys/time.h> + +/* + * For off64_t to be defined, we need both + * __USE_LARGEFILE64 to be true and __off64_t_defnined to be + * false. But, making __USE_LARGEFILE64 true causes other issues + * such as redinition of stat and fstat to stat64 and fstat64 + * respectively which again causes compilation issues. + * Without off64_t being defined, this will not compile as + * copy_file_range uses off64_t. Hence define it here. First + * check whether __off64_t_defined is true or not. <unistd.h> + * sets that flag when it defines off64_t. If __off64_t_defined + * is false and __USE_FILE_OFFSET64 is true, then go on to define + * off64_t using __off64_t. + */ +#ifndef GF_BSD_HOST_OS +#if defined(__USE_FILE_OFFSET64) && !defined(__off64_t_defined) +typedef __off64_t off64_t; +#endif /* defined(__USE_FILE_OFFSET64) && !defined(__off64_t_defined) */ +#else +#include <stdio.h> +#ifndef _OFF64_T_DECLARED +/* + * Including <stdio.h> (done above) should actually define + * _OFF64_T_DECLARED with off64_t data type being available + * for consumption. But, off64_t data type is not recognizable + * for FreeBSD versions less than 11. Hence, int64_t is typedefed + * to off64_t. + */ +#define _OFF64_T_DECLARED +typedef int64_t off64_t; +#endif /* _OFF64_T_DECLARED */ +#endif /* GF_BSD_HOST_OS */ #if defined(HAVE_SYS_ACL_H) || (defined(USE_POSIX_ACLS) && USE_POSIX_ACLS) #include <sys/acl.h> @@ -51,19 +95,20 @@ typedef int acl_type_t; /* Portability non glibc c++ build systems */ #ifndef __THROW -# if defined __cplusplus -# define __THROW throw () -# else -# define __THROW -# endif +#if defined __cplusplus +#define __THROW throw() +#else +#define __THROW +#endif #endif #ifndef GF_DARWIN_HOST_OS -#define GFAPI_PUBLIC(sym, ver) /**/ +#define GFAPI_PUBLIC(sym, ver) /**/ #define GFAPI_PRIVATE(sym, ver) /**/ #else #define GFAPI_PUBLIC(sym, ver) __asm("_" __STRING(sym) "$GFAPI_" __STRING(ver)) -#define GFAPI_PRIVATE(sym, ver) __asm("_" __STRING(sym) "$GFAPI_PRIVATE_" __STRING(ver)) +#define GFAPI_PRIVATE(sym, ver) \ + __asm("_" __STRING(sym) "$GFAPI_PRIVATE_" __STRING(ver)) #endif __BEGIN_DECLS @@ -72,7 +117,6 @@ __BEGIN_DECLS struct glfs; typedef struct glfs glfs_t; - /* SYNOPSIS @@ -93,8 +137,8 @@ typedef struct glfs glfs_t; @volname: Name of the volume. This identifies the server-side volume and the fetched volfile (equivalent of --volfile-id command line - parameter to glusterfsd). When used with glfs_set_volfile() the - @volname has no effect (except for appearing in log messages). + parameter to glusterfsd). When used with glfs_set_volfile() the + @volname has no effect (except for appearing in log messages). RETURN VALUES @@ -103,9 +147,8 @@ typedef struct glfs glfs_t; */ -glfs_t *glfs_new (const char *volname) __THROW - GFAPI_PUBLIC(glfs_new, 3.4.0); - +glfs_t * +glfs_new(const char *volname) __THROW GFAPI_PUBLIC(glfs_new, 3.4.0); /* SYNOPSIS @@ -134,9 +177,9 @@ glfs_t *glfs_new (const char *volname) __THROW */ -int glfs_set_volfile (glfs_t *fs, const char *volfile) __THROW - GFAPI_PUBLIC(glfs_set_volfile, 3.4.0); - +int +glfs_set_volfile(glfs_t *fs, const char *volfile) __THROW + GFAPI_PUBLIC(glfs_set_volfile, 3.4.0); /* SYNOPSIS @@ -161,10 +204,9 @@ int glfs_set_volfile (glfs_t *fs, const char *volfile) __THROW specification file. @transport: String specifying the transport used to connect to the - management daemon. Specifying NULL will result in the usage - of the default (tcp) transport type. Permitted values - are those what you specify as transport-type in a volume - specification file (e.g "tcp", "rdma", "unix" etc.) + management daemon. Specifying NULL will result in the + usage of the default (tcp) transport type. Permitted + values are "tcp" or "unix". @host: String specifying the address where to find the management daemon. Socket path, while using Unix domain socket as transport type. @@ -188,12 +230,15 @@ int glfs_set_volfile (glfs_t *fs, const char *volfile) __THROW */ -int glfs_set_volfile_server (glfs_t *fs, const char *transport, - const char *host, int port) __THROW - GFAPI_PUBLIC(glfs_set_volfile_server, 3.4.0); -int glfs_unset_volfile_server (glfs_t *fs, const char *transport, - const char *host, int port) __THROW - GFAPI_PUBLIC(glfs_unset_volfile_server, 3.5.1); +int +glfs_set_volfile_server(glfs_t *fs, const char *transport, const char *host, + int port) __THROW + GFAPI_PUBLIC(glfs_set_volfile_server, 3.4.0); + +int +glfs_unset_volfile_server(glfs_t *fs, const char *transport, const char *host, + int port) __THROW + GFAPI_PUBLIC(glfs_unset_volfile_server, 3.5.1); /* SYNOPSIS @@ -223,9 +268,9 @@ int glfs_unset_volfile_server (glfs_t *fs, const char *transport, */ -int glfs_set_logging (glfs_t *fs, const char *logfile, int loglevel) __THROW - GFAPI_PUBLIC(glfs_set_logging, 3.4.0); - +int +glfs_set_logging(glfs_t *fs, const char *logfile, int loglevel) __THROW + GFAPI_PUBLIC(glfs_set_logging, 3.4.0); /* SYNOPSIS @@ -251,9 +296,8 @@ int glfs_set_logging (glfs_t *fs, const char *logfile, int loglevel) __THROW */ -int glfs_init (glfs_t *fs) __THROW - GFAPI_PUBLIC(glfs_init, 3.4.0); - +int +glfs_init(glfs_t *fs) __THROW GFAPI_PUBLIC(glfs_init, 3.4.0); /* SYNOPSIS @@ -285,8 +329,8 @@ int glfs_init (glfs_t *fs) __THROW 0 : Success. */ -int glfs_fini (glfs_t *fs) __THROW - GFAPI_PUBLIC(glfs_fini, 3.4.0); +int +glfs_fini(glfs_t *fs) __THROW GFAPI_PUBLIC(glfs_fini, 3.4.0); /* SYNOPSIS @@ -316,9 +360,9 @@ int glfs_fini (glfs_t *fs) __THROW <0: volfile length exceeds @len by N bytes (@buf unchanged) */ -ssize_t glfs_get_volfile (glfs_t *fs, void *buf, size_t len) __THROW - GFAPI_PUBLIC(glfs_get_volfile, 3.6.0); - +ssize_t +glfs_get_volfile(glfs_t *fs, void *buf, size_t len) __THROW + GFAPI_PUBLIC(glfs_get_volfile, 3.6.0); /* SYNOPSIS @@ -331,9 +375,9 @@ ssize_t glfs_get_volfile (glfs_t *fs, void *buf, size_t len) __THROW the management server (glusterd) to fetch volume uuid and stores it in the glusterfs_context linked to the glfs object fs which can be used in the subsequent calls. Later it parses that UUID to convert it from - cannonical string format into an opaque byte array and copy it into - the volid array. Incase if either of the input parameters, volid or size, - is NULL, number of bytes required to copy the volume UUID is returned. + canonical string format into an opaque byte array and copy it into + the volid array. In case if either of the input parameters, volid or + size, is NULL, number of bytes required to copy the volume UUID is returned. PARAMETERS @@ -348,9 +392,9 @@ ssize_t glfs_get_volfile (glfs_t *fs, void *buf, size_t len) __THROW Others : length of the volume UUID stored. */ -int glfs_get_volumeid (struct glfs *fs, char *volid, size_t size) __THROW - GFAPI_PUBLIC(glfs_get_volumeid, 3.5.0); - +int +glfs_get_volumeid(glfs_t *fs, char *volid, size_t size) __THROW + GFAPI_PUBLIC(glfs_get_volumeid, 3.5.0); /* * FILE OPERATION @@ -372,6 +416,119 @@ struct glfs_fd; typedef struct glfs_fd glfs_fd_t; /* + * Mask for request/result items in the struct glfs_stat. + * + * Query request/result mask for glfs_stat() (family of functions) and + * struct glfs_stat::glfs_st_mask. + * + * These bits should be set in the mask argument of glfs_stat() (family of + * functions) to request particular items when calling glfs_stat(). + * + * NOTE: Lower order 32 bits are used to reflect statx(2) bits. For Gluster + * specific attrs/extensions, use higher order 32 bits. + * + */ +#define GLFS_STAT_TYPE 0x0000000000000001U /* Want/got stx_mode & S_IFMT */ +#define GLFS_STAT_MODE 0x0000000000000002U /* Want/got stx_mode & ~S_IFMT */ +#define GLFS_STAT_NLINK 0x0000000000000004U /* Want/got stx_nlink */ +#define GLFS_STAT_UID 0x0000000000000008U /* Want/got stx_uid */ +#define GLFS_STAT_GID 0x0000000000000010U /* Want/got stx_gid */ +#define GLFS_STAT_ATIME 0x0000000000000020U /* Want/got stx_atime */ +#define GLFS_STAT_MTIME 0x0000000000000040U /* Want/got stx_mtime */ +#define GLFS_STAT_CTIME 0x0000000000000080U /* Want/got stx_ctime */ +#define GLFS_STAT_INO 0x0000000000000100U /* Want/got stx_ino */ +#define GLFS_STAT_SIZE 0x0000000000000200U /* Want/got stx_size */ +#define GLFS_STAT_BLOCKS 0x0000000000000400U /* Want/got stx_blocks */ +#define GLFS_STAT_BASIC_STATS \ + 0x00000000000007ffU /* Items in the normal stat struct */ +#define GLFS_STAT_BTIME 0x0000000000000800U /* Want/got stx_btime */ +#define GLFS_STAT_ALL 0x0000000000000fffU /* All currently supported flags */ +#define GLFS_STAT_RESERVED \ + 0x8000000000000000U /* Reserved to denote future expansion */ + +/* Macros for checking validity of struct glfs_stat members.*/ +#define GLFS_STAT_TYPE_VALID(stmask) (stmask & GLFS_STAT_TYPE) +#define GLFS_STAT_MODE_VALID(stmask) (stmask & GLFS_STAT_MODE) +#define GLFS_STAT_NLINK_VALID(stmask) (stmask & GLFS_STAT_NLINK) +#define GLFS_STAT_UID_VALID(stmask) (stmask & GLFS_STAT_UID) +#define GLFS_STAT_GID_VALID(stmask) (stmask & GLFS_STAT_GID) +#define GLFS_STAT_ATIME_VALID(stmask) (stmask & GLFS_STAT_ATIME) +#define GLFS_STAT_MTIME_VALID(stmask) (stmask & GLFS_STAT_MTIME) +#define GLFS_STAT_CTIME_VALID(stmask) (stmask & GLFS_STAT_CTIME) +#define GLFS_STAT_INO_VALID(stmask) (stmask & GLFS_STAT_INO) +#define GLFS_STAT_SIZE_VALID(stmask) (stmask & GLFS_STAT_SIZE) +#define GLFS_STAT_BLOCKS_VALID(stmask) (stmask & GLFS_STAT_BLOCKS) +#define GLFS_STAT_BTIME_VALID(stmask) (stmask & GLFS_STAT_BTIME) +#define GLFS_STAT_GFID_VALID(stmask) (stmask & GLFS_STAT_GFID) + +/* + * Attributes to be found in glfs_st_attributes and masked in + * glfs_st_attributes_mask. + * + * These give information about the features or the state of a file that might + * be of use to programs. + * + * NOTE: Lower order 32 bits are used to reflect statx(2) attribute bits. For + * Gluster specific attrs, use higher order 32 bits. + * + * NOTE: We do not support any file attributes or state as yet! + */ +#define GLFS_STAT_ATTR_RESERVED \ + 0x8000000000000000U /* Reserved to denote future expansion */ + +/* Extended file attribute structure. + * + * The caller passes a mask of what they're specifically interested in as a + * parameter to glfs_stat(). What glfs_stat() actually got will be indicated + * in glfs_st_mask upon return. + * + * For each bit in the mask argument: + * + * - if the datum is not supported: + * + * - the bit will be cleared, and + * + * - the datum value is undefined + * + * - otherwise, if explicitly requested: + * + * - the field will be filled in and the bit will be set; + * + * - otherwise, if not requested, but available in, it will be filled in + * anyway, and the bit will be set upon return; + * + * - otherwise the field and the bit will be cleared before returning. + * + */ + +struct glfs_stat { + uint64_t glfs_st_mask; /* What results were written [uncond] */ + uint64_t glfs_st_attributes; /* Flags conveying information about the file + [uncond] */ + uint64_t glfs_st_attributes_mask; /* Mask to show what's supported in + st_attributes [ucond] */ + struct timespec glfs_st_atime; /* Last access time */ + struct timespec glfs_st_btime; /* File creation time */ + struct timespec glfs_st_ctime; /* Last attribute change time */ + struct timespec glfs_st_mtime; /* Last data modification time */ + ino_t glfs_st_ino; /* Inode number */ + off_t glfs_st_size; /* File size */ + blkcnt_t glfs_st_blocks; /* Number of 512-byte blocks allocated */ + uint32_t glfs_st_rdev_major; /* Device ID of special file [if bdev/cdev] */ + uint32_t glfs_st_rdev_minor; + uint32_t glfs_st_dev_major; /* ID of device containing file [uncond] */ + uint32_t glfs_st_dev_minor; + blksize_t glfs_st_blksize; /* Preferred general I/O size [uncond] */ + nlink_t glfs_st_nlink; /* Number of hard links */ + uid_t glfs_st_uid; /* User ID of owner */ + gid_t glfs_st_gid; /* Group ID of owner */ + mode_t glfs_st_mode; /* File mode */ +}; + +#define GLFS_LEASE_ID_SIZE 16 /* 128bits */ +typedef char glfs_leaseid_t[GLFS_LEASE_ID_SIZE]; + +/* * PER THREAD IDENTITY MODIFIERS * * The following operations enable to set a per thread identity context @@ -388,18 +545,27 @@ typedef struct glfs_fd glfs_fd_t; * caller * - The groups once set, need to be unset by setting the size to 0 (in which * case the list argument is a do not care) + * - In case of leases feature enables, setfsleaseid is used to set and reset + * leaseid before and after every I/O operation. * - Once a process for a thread of operation choses to set the IDs, all glfs * calls made from that thread would default to the IDs set for the thread. * As a result use these APIs with care and ensure that the set IDs are * reverted to global process defaults as required. * */ -int glfs_setfsuid (uid_t fsuid) __THROW - GFAPI_PUBLIC(glfs_setfsuid, 3.4.2); -int glfs_setfsgid (gid_t fsgid) __THROW - GFAPI_PUBLIC(glfs_setfsgid, 3.4.2); -int glfs_setfsgroups (size_t size, const gid_t *list) __THROW - GFAPI_PUBLIC(glfs_setfsgroups, 3.4.2); +int +glfs_setfsuid(uid_t fsuid) __THROW GFAPI_PUBLIC(glfs_setfsuid, 3.4.2); + +int +glfs_setfsgid(gid_t fsgid) __THROW GFAPI_PUBLIC(glfs_setfsgid, 3.4.2); + +int +glfs_setfsgroups(size_t size, const gid_t *list) __THROW + GFAPI_PUBLIC(glfs_setfsgroups, 3.4.2); + +int +glfs_setfsleaseid(glfs_leaseid_t leaseid) __THROW + GFAPI_PUBLIC(glfs_setfsleaseid, 4.0.0); /* SYNOPSIS @@ -426,9 +592,9 @@ int glfs_setfsgroups (size_t size, const gid_t *list) __THROW */ -glfs_fd_t *glfs_open (glfs_t *fs, const char *path, int flags) __THROW - GFAPI_PUBLIC(glfs_open, 3.4.0); - +glfs_fd_t * +glfs_open(glfs_t *fs, const char *path, int flags) __THROW + GFAPI_PUBLIC(glfs_open, 3.4.0); /* SYNOPSIS @@ -456,19 +622,20 @@ glfs_fd_t *glfs_open (glfs_t *fs, const char *path, int flags) __THROW */ -glfs_fd_t *glfs_creat (glfs_t *fs, const char *path, int flags, - mode_t mode) __THROW - GFAPI_PUBLIC(glfs_creat, 3.4.0); +glfs_fd_t * +glfs_creat(glfs_t *fs, const char *path, int flags, mode_t mode) __THROW + GFAPI_PUBLIC(glfs_creat, 3.4.0); -int glfs_close (glfs_fd_t *fd) __THROW - GFAPI_PUBLIC(glfs_close, 3.4.0); +int +glfs_close(glfs_fd_t *fd) __THROW GFAPI_PUBLIC(glfs_close, 3.4.0); -glfs_t *glfs_from_glfd (glfs_fd_t *fd) __THROW - GFAPI_PUBLIC(glfs_from_glfd, 3.4.0); +glfs_t * +glfs_from_glfd(glfs_fd_t *fd) __THROW GFAPI_PUBLIC(glfs_from_glfd, 3.4.0); -int glfs_set_xlator_option (glfs_t *fs, const char *xlator, const char *key, - const char *value) __THROW - GFAPI_PUBLIC(glfs_set_xlator_options, 3.4.0); +int +glfs_set_xlator_option(glfs_t *fs, const char *xlator, const char *key, + const char *value) __THROW + GFAPI_PUBLIC(glfs_set_xlator_option, 3.4.0); /* @@ -491,295 +658,828 @@ int glfs_set_xlator_option (glfs_t *fs, const char *xlator, const char *key, time of issuing the async IO call. This can be used by the caller to differentiate different instances of the async requests in a common callback function. + + @prestat and @poststat are allocated on the stack, that are auto destroyed + post the callback function returns. */ -typedef void (*glfs_io_cbk) (glfs_fd_t *fd, ssize_t ret, void *data); +typedef void (*glfs_io_cbk)(glfs_fd_t *fd, ssize_t ret, + struct glfs_stat *prestat, + struct glfs_stat *poststat, void *data); // glfs_{read,write}[_async] -ssize_t glfs_read (glfs_fd_t *fd, void *buf, - size_t count, int flags) __THROW - GFAPI_PUBLIC(glfs_read, 3.4.0); -ssize_t glfs_write (glfs_fd_t *fd, const void *buf, - size_t count, int flags) __THROW - GFAPI_PUBLIC(glfs_write, 3.4.0); -int glfs_read_async (glfs_fd_t *fd, void *buf, size_t count, int flags, - glfs_io_cbk fn, void *data) __THROW - GFAPI_PUBLIC(glfs_read_async, 3.4.0); -int glfs_write_async (glfs_fd_t *fd, const void *buf, size_t count, int flags, - glfs_io_cbk fn, void *data) __THROW - GFAPI_PUBLIC(glfs_write_async, 3.4.0); +ssize_t +glfs_read(glfs_fd_t *fd, void *buf, size_t count, int flags) __THROW + GFAPI_PUBLIC(glfs_read, 3.4.0); + +ssize_t +glfs_write(glfs_fd_t *fd, const void *buf, size_t count, int flags) __THROW + GFAPI_PUBLIC(glfs_write, 3.4.0); + +int +glfs_read_async(glfs_fd_t *fd, void *buf, size_t count, int flags, + glfs_io_cbk fn, void *data) __THROW + GFAPI_PUBLIC(glfs_read_async, 6.0); + +int +glfs_write_async(glfs_fd_t *fd, const void *buf, size_t count, int flags, + glfs_io_cbk fn, void *data) __THROW + GFAPI_PUBLIC(glfs_write_async, 6.0); // glfs_{read,write}v[_async] -ssize_t glfs_readv (glfs_fd_t *fd, const struct iovec *iov, int iovcnt, - int flags) __THROW - GFAPI_PUBLIC(glfs_readv, 3.4.0); -ssize_t glfs_writev (glfs_fd_t *fd, const struct iovec *iov, int iovcnt, - int flags) __THROW - GFAPI_PUBLIC(glfs_writev, 3.4.0); -int glfs_readv_async (glfs_fd_t *fd, const struct iovec *iov, int count, - int flags, glfs_io_cbk fn, void *data) __THROW - GFAPI_PUBLIC(glfs_readv_async, 3.4.0); -int glfs_writev_async (glfs_fd_t *fd, const struct iovec *iov, int count, - int flags, glfs_io_cbk fn, void *data) __THROW - GFAPI_PUBLIC(glfs_writev_async, 3.4.0); +ssize_t +glfs_readv(glfs_fd_t *fd, const struct iovec *iov, int iovcnt, + int flags) __THROW GFAPI_PUBLIC(glfs_readv, 3.4.0); + +ssize_t +glfs_writev(glfs_fd_t *fd, const struct iovec *iov, int iovcnt, + int flags) __THROW GFAPI_PUBLIC(glfs_writev, 3.4.0); + +int +glfs_readv_async(glfs_fd_t *fd, const struct iovec *iov, int count, int flags, + glfs_io_cbk fn, void *data) __THROW + GFAPI_PUBLIC(glfs_readv_async, 6.0); + +int +glfs_writev_async(glfs_fd_t *fd, const struct iovec *iov, int count, int flags, + glfs_io_cbk fn, void *data) __THROW + GFAPI_PUBLIC(glfs_writev_async, 6.0); // glfs_p{read,write}[_async] -ssize_t glfs_pread (glfs_fd_t *fd, void *buf, size_t count, off_t offset, - int flags) __THROW - GFAPI_PUBLIC(glfs_pread, 3.4.0); -ssize_t glfs_pwrite (glfs_fd_t *fd, const void *buf, size_t count, - off_t offset, int flags) __THROW - GFAPI_PUBLIC(glfs_pwrite, 3.4.0); -int glfs_pread_async (glfs_fd_t *fd, void *buf, size_t count, off_t offset, - int flags, glfs_io_cbk fn, void *data) __THROW - GFAPI_PUBLIC(glfs_pread_async, 3.4.0); -int glfs_pwrite_async (glfs_fd_t *fd, const void *buf, int count, off_t offset, - int flags, glfs_io_cbk fn, void *data) __THROW - GFAPI_PUBLIC(glfs_pwrite_async, 3.4.0); +ssize_t +glfs_pread(glfs_fd_t *fd, void *buf, size_t count, off_t offset, int flags, + struct glfs_stat *poststat) __THROW GFAPI_PUBLIC(glfs_pread, 6.0); + +ssize_t +glfs_pwrite(glfs_fd_t *fd, const void *buf, size_t count, off_t offset, + int flags, struct glfs_stat *prestat, + struct glfs_stat *poststat) __THROW GFAPI_PUBLIC(glfs_pwrite, 6.0); + +int +glfs_pread_async(glfs_fd_t *fd, void *buf, size_t count, off_t offset, + int flags, glfs_io_cbk fn, void *data) __THROW + GFAPI_PUBLIC(glfs_pread_async, 6.0); + +int +glfs_pwrite_async(glfs_fd_t *fd, const void *buf, int count, off_t offset, + int flags, glfs_io_cbk fn, void *data) __THROW + GFAPI_PUBLIC(glfs_pwrite_async, 6.0); // glfs_p{read,write}v[_async] -ssize_t glfs_preadv (glfs_fd_t *fd, const struct iovec *iov, int iovcnt, - off_t offset, int flags) __THROW - GFAPI_PUBLIC(glfs_preadv, 3.4.0); -ssize_t glfs_pwritev (glfs_fd_t *fd, const struct iovec *iov, int iovcnt, - off_t offset, int flags) __THROW - GFAPI_PUBLIC(glfs_pwritev, 3.4.0); -int glfs_preadv_async (glfs_fd_t *fd, const struct iovec *iov, - int count, off_t offset, int flags, - glfs_io_cbk fn, void *data) __THROW - GFAPI_PUBLIC(glfs_preadv_async, 3.4.0); -int glfs_pwritev_async (glfs_fd_t *fd, const struct iovec *iov, - int count, off_t offset, int flags, - glfs_io_cbk fn, void *data) __THROW - GFAPI_PUBLIC(glfs_pwritev_async, 3.4.0); +ssize_t +glfs_preadv(glfs_fd_t *fd, const struct iovec *iov, int iovcnt, off_t offset, + int flags) __THROW GFAPI_PUBLIC(glfs_preadv, 3.4.0); + +ssize_t +glfs_pwritev(glfs_fd_t *fd, const struct iovec *iov, int iovcnt, off_t offset, + int flags) __THROW GFAPI_PUBLIC(glfs_pwritev, 3.4.0); + +int +glfs_preadv_async(glfs_fd_t *fd, const struct iovec *iov, int count, + off_t offset, int flags, glfs_io_cbk fn, void *data) __THROW + GFAPI_PUBLIC(glfs_preadv_async, 6.0); + +int +glfs_pwritev_async(glfs_fd_t *fd, const struct iovec *iov, int count, + off_t offset, int flags, glfs_io_cbk fn, void *data) __THROW + GFAPI_PUBLIC(glfs_pwritev_async, 6.0); + +off_t +glfs_lseek(glfs_fd_t *fd, off_t offset, int whence) __THROW + GFAPI_PUBLIC(glfs_lseek, 3.4.0); + +ssize_t +glfs_copy_file_range(struct glfs_fd *glfd_in, off64_t *off_in, + struct glfs_fd *glfd_out, off64_t *off_out, size_t len, + unsigned int flags, struct glfs_stat *statbuf, + struct glfs_stat *prestat, + struct glfs_stat *poststat) __THROW + GFAPI_PUBLIC(glfs_copy_file_range, 6.0); + +int +glfs_truncate(glfs_t *fs, const char *path, off_t length) __THROW + GFAPI_PUBLIC(glfs_truncate, 3.7.15); + +int +glfs_ftruncate(glfs_fd_t *fd, off_t length, struct glfs_stat *prestat, + struct glfs_stat *poststat) __THROW + GFAPI_PUBLIC(glfs_ftruncate, 6.0); + +int +glfs_ftruncate_async(glfs_fd_t *fd, off_t length, glfs_io_cbk fn, + void *data) __THROW + GFAPI_PUBLIC(glfs_ftruncate_async, 6.0); + +int +glfs_lstat(glfs_t *fs, const char *path, struct stat *buf) __THROW + GFAPI_PUBLIC(glfs_lstat, 3.4.0); + +int +glfs_stat(glfs_t *fs, const char *path, struct stat *buf) __THROW + GFAPI_PUBLIC(glfs_stat, 3.4.0); + +int +glfs_fstat(glfs_fd_t *fd, struct stat *buf) __THROW + GFAPI_PUBLIC(glfs_fstat, 3.4.0); + +int +glfs_fsync(glfs_fd_t *fd, struct glfs_stat *prestat, + struct glfs_stat *poststat) __THROW GFAPI_PUBLIC(glfs_fsync, 6.0); + +int +glfs_fsync_async(glfs_fd_t *fd, glfs_io_cbk fn, void *data) __THROW + GFAPI_PUBLIC(glfs_fsync_async, 6.0); + +int +glfs_fdatasync(glfs_fd_t *fd, struct glfs_stat *prestat, + struct glfs_stat *poststat) __THROW + GFAPI_PUBLIC(glfs_fdatasync, 6.0); + +int +glfs_fdatasync_async(glfs_fd_t *fd, glfs_io_cbk fn, void *data) __THROW + GFAPI_PUBLIC(glfs_fdatasync_async, 6.0); + +int +glfs_access(glfs_t *fs, const char *path, int mode) __THROW + GFAPI_PUBLIC(glfs_access, 3.4.0); + +int +glfs_symlink(glfs_t *fs, const char *oldpath, const char *newpath) __THROW + GFAPI_PUBLIC(glfs_symlink, 3.4.0); + +int +glfs_readlink(glfs_t *fs, const char *path, char *buf, size_t bufsiz) __THROW + GFAPI_PUBLIC(glfs_readlink, 3.4.0); + +int +glfs_mknod(glfs_t *fs, const char *path, mode_t mode, dev_t dev) __THROW + GFAPI_PUBLIC(glfs_mknod, 3.4.0); + +int +glfs_mkdir(glfs_t *fs, const char *path, mode_t mode) __THROW + GFAPI_PUBLIC(glfs_mkdir, 3.4.0); + +int +glfs_unlink(glfs_t *fs, const char *path) __THROW + GFAPI_PUBLIC(glfs_unlink, 3.4.0); + +int +glfs_rmdir(glfs_t *fs, const char *path) __THROW + GFAPI_PUBLIC(glfs_rmdir, 3.4.0); + +int +glfs_rename(glfs_t *fs, const char *oldpath, const char *newpath) __THROW + GFAPI_PUBLIC(glfs_rename, 3.4.0); + +int +glfs_link(glfs_t *fs, const char *oldpath, const char *newpath) __THROW + GFAPI_PUBLIC(glfs_link, 3.4.0); + +glfs_fd_t * +glfs_opendir(glfs_t *fs, const char *path) __THROW + GFAPI_PUBLIC(glfs_opendir, 3.4.0); + +/* + * @glfs_readdir_r and @glfs_readdirplus_r ARE thread safe AND re-entrant, + * but the interface has ambiguity about the size of @dirent to be allocated + * before calling the APIs. 512 byte buffer (for @dirent) is sufficient for + * all known systems which are tested againt glusterfs/gfapi, but may be + * insufficient in the future. + */ + +int +glfs_readdir_r(glfs_fd_t *fd, struct dirent *dirent, + struct dirent **result) __THROW + GFAPI_PUBLIC(glfs_readdir_r, 3.4.0); + +int +glfs_readdirplus_r(glfs_fd_t *fd, struct stat *stat, struct dirent *dirent, + struct dirent **result) __THROW + GFAPI_PUBLIC(glfs_readdirplus_r, 3.4.0); + +/* + * @glfs_readdir and @glfs_readdirplus are NEITHER thread safe NOR re-entrant + * when called on the same directory handle. However they ARE thread safe + * AND re-entrant when called on different directory handles (which may be + * referring to the same directory too.) + */ + +struct dirent * +glfs_readdir(glfs_fd_t *fd) __THROW GFAPI_PUBLIC(glfs_readdir, 3.5.0); + +struct dirent * +glfs_readdirplus(glfs_fd_t *fd, struct stat *stat) __THROW + GFAPI_PUBLIC(glfs_readdirplus, 3.5.0); + +long +glfs_telldir(glfs_fd_t *fd) __THROW GFAPI_PUBLIC(glfs_telldir, 3.4.0); + +void +glfs_seekdir(glfs_fd_t *fd, long offset) __THROW + GFAPI_PUBLIC(glfs_seekdir, 3.4.0); + +int +glfs_closedir(glfs_fd_t *fd) __THROW GFAPI_PUBLIC(glfs_closedir, 3.4.0); + +int +glfs_statvfs(glfs_t *fs, const char *path, struct statvfs *buf) __THROW + GFAPI_PUBLIC(glfs_statvfs, 3.4.0); + +int +glfs_chmod(glfs_t *fs, const char *path, mode_t mode) __THROW + GFAPI_PUBLIC(glfs_chmod, 3.4.0); + +int +glfs_fchmod(glfs_fd_t *fd, mode_t mode) __THROW + GFAPI_PUBLIC(glfs_fchmod, 3.4.0); + +int +glfs_chown(glfs_t *fs, const char *path, uid_t uid, gid_t gid) __THROW + GFAPI_PUBLIC(glfs_chown, 3.4.0); + +int +glfs_lchown(glfs_t *fs, const char *path, uid_t uid, gid_t gid) __THROW + GFAPI_PUBLIC(glfs_lchown, 3.4.0); +int +glfs_fchown(glfs_fd_t *fd, uid_t uid, gid_t gid) __THROW + GFAPI_PUBLIC(glfs_fchown, 3.4.0); -off_t glfs_lseek (glfs_fd_t *fd, off_t offset, int whence) __THROW - GFAPI_PUBLIC(glfs_lseek, 3.4.0); +int +glfs_utimens(glfs_t *fs, const char *path, + const struct timespec times[2]) __THROW + GFAPI_PUBLIC(glfs_utimens, 3.4.0); -int glfs_truncate (glfs_t *fs, const char *path, off_t length) __THROW - GFAPI_PUBLIC(glfs_truncate, 3.7.15); +int +glfs_lutimens(glfs_t *fs, const char *path, + const struct timespec times[2]) __THROW + GFAPI_PUBLIC(glfs_lutimens, 3.4.0); -int glfs_ftruncate (glfs_fd_t *fd, off_t length) __THROW - GFAPI_PUBLIC(glfs_ftruncate, 3.4.0); -int glfs_ftruncate_async (glfs_fd_t *fd, off_t length, glfs_io_cbk fn, - void *data) __THROW - GFAPI_PUBLIC(glfs_ftruncate_async, 3.4.0); +int +glfs_futimens(glfs_fd_t *fd, const struct timespec times[2]) __THROW + GFAPI_PUBLIC(glfs_futimens, 3.4.0); -int glfs_lstat (glfs_t *fs, const char *path, struct stat *buf) __THROW - GFAPI_PUBLIC(glfs_lstat, 3.4.0); -int glfs_stat (glfs_t *fs, const char *path, struct stat *buf) __THROW - GFAPI_PUBLIC(glfs_stat, 3.4.0); -int glfs_fstat (glfs_fd_t *fd, struct stat *buf) __THROW - GFAPI_PUBLIC(glfs_fstat, 3.4.0); +ssize_t +glfs_getxattr(glfs_t *fs, const char *path, const char *name, void *value, + size_t size) __THROW GFAPI_PUBLIC(glfs_getxattr, 3.4.0); -int glfs_fsync (glfs_fd_t *fd) __THROW - GFAPI_PUBLIC(glfs_fsync, 3.4.0); -int glfs_fsync_async (glfs_fd_t *fd, glfs_io_cbk fn, void *data) __THROW - GFAPI_PUBLIC(glfs_fsync_async, 3.4.0); +ssize_t +glfs_lgetxattr(glfs_t *fs, const char *path, const char *name, void *value, + size_t size) __THROW GFAPI_PUBLIC(glfs_lgetxattr, 3.4.0); -int glfs_fdatasync (glfs_fd_t *fd) __THROW - GFAPI_PUBLIC(glfs_fdatasync, 3.4.0); -int glfs_fdatasync_async (glfs_fd_t *fd, glfs_io_cbk fn, void *data) __THROW - GFAPI_PUBLIC(glfs_fdatasync_async, 3.4.0); +ssize_t +glfs_fgetxattr(glfs_fd_t *fd, const char *name, void *value, + size_t size) __THROW GFAPI_PUBLIC(glfs_fgetxattr, 3.4.0); -int glfs_access (glfs_t *fs, const char *path, int mode) __THROW - GFAPI_PUBLIC(glfs_access, 3.4.0); +ssize_t +glfs_listxattr(glfs_t *fs, const char *path, void *value, size_t size) __THROW + GFAPI_PUBLIC(glfs_listxattr, 3.4.0); -int glfs_symlink (glfs_t *fs, const char *oldpath, const char *newpath) __THROW - GFAPI_PUBLIC(glfs_symlink, 3.4.0); +ssize_t +glfs_llistxattr(glfs_t *fs, const char *path, void *value, size_t size) __THROW + GFAPI_PUBLIC(glfs_llistxattr, 3.4.0); -int glfs_readlink (glfs_t *fs, const char *path, - char *buf, size_t bufsiz) __THROW - GFAPI_PUBLIC(glfs_readlink, 3.4.0); +ssize_t +glfs_flistxattr(glfs_fd_t *fd, void *value, size_t size) __THROW + GFAPI_PUBLIC(glfs_flistxattr, 3.4.0); -int glfs_mknod (glfs_t *fs, const char *path, mode_t mode, dev_t dev) __THROW - GFAPI_PUBLIC(glfs_mknod, 3.4.0); +int +glfs_setxattr(glfs_t *fs, const char *path, const char *name, const void *value, + size_t size, int flags) __THROW + GFAPI_PUBLIC(glfs_setxattr, 3.4.0); -int glfs_mkdir (glfs_t *fs, const char *path, mode_t mode) __THROW - GFAPI_PUBLIC(glfs_mkdir, 3.4.0); +int +glfs_lsetxattr(glfs_t *fs, const char *path, const char *name, + const void *value, size_t size, int flags) __THROW + GFAPI_PUBLIC(glfs_lsetxattr, 3.4.0); -int glfs_unlink (glfs_t *fs, const char *path) __THROW - GFAPI_PUBLIC(glfs_unlink, 3.4.0); +int +glfs_fsetxattr(glfs_fd_t *fd, const char *name, const void *value, size_t size, + int flags) __THROW GFAPI_PUBLIC(glfs_fsetxattr, 3.4.0); -int glfs_rmdir (glfs_t *fs, const char *path) __THROW - GFAPI_PUBLIC(glfs_rmdir, 3.4.0); +int +glfs_removexattr(glfs_t *fs, const char *path, const char *name) __THROW + GFAPI_PUBLIC(glfs_removexattr, 3.4.0); -int glfs_rename (glfs_t *fs, const char *oldpath, const char *newpath) __THROW - GFAPI_PUBLIC(glfs_rename, 3.4.0); +int +glfs_lremovexattr(glfs_t *fs, const char *path, const char *name) __THROW + GFAPI_PUBLIC(glfs_lremovexattr, 3.4.0); -int glfs_link (glfs_t *fs, const char *oldpath, const char *newpath) __THROW - GFAPI_PUBLIC(glfs_link, 3.4.0); +int +glfs_fremovexattr(glfs_fd_t *fd, const char *name) __THROW + GFAPI_PUBLIC(glfs_fremovexattr, 3.4.0); -glfs_fd_t *glfs_opendir (glfs_t *fs, const char *path) __THROW - GFAPI_PUBLIC(glfs_opendir, 3.4.0); +int +glfs_fallocate(glfs_fd_t *fd, int keep_size, off_t offset, size_t len) __THROW + GFAPI_PUBLIC(glfs_fallocate, 3.5.0); + +int +glfs_discard(glfs_fd_t *fd, off_t offset, size_t len) __THROW + GFAPI_PUBLIC(glfs_discard, 3.5.0); + +int +glfs_discard_async(glfs_fd_t *fd, off_t length, size_t lent, glfs_io_cbk fn, + void *data) __THROW GFAPI_PUBLIC(glfs_discard_async, 6.0); + +int +glfs_zerofill(glfs_fd_t *fd, off_t offset, off_t len) __THROW + GFAPI_PUBLIC(glfs_zerofill, 3.5.0); + +int +glfs_zerofill_async(glfs_fd_t *fd, off_t length, off_t len, glfs_io_cbk fn, + void *data) __THROW GFAPI_PUBLIC(glfs_zerofill_async, 6.0); + +char * +glfs_getcwd(glfs_t *fs, char *buf, size_t size) __THROW + GFAPI_PUBLIC(glfs_getcwd, 3.4.0); + +int +glfs_chdir(glfs_t *fs, const char *path) __THROW + GFAPI_PUBLIC(glfs_chdir, 3.4.0); + +int +glfs_fchdir(glfs_fd_t *fd) __THROW GFAPI_PUBLIC(glfs_fchdir, 3.4.0); + +char * +glfs_realpath(glfs_t *fs, const char *path, char *resolved_path) __THROW + GFAPI_PUBLIC(glfs_realpath, 3.7.17); /* - * @glfs_readdir_r and @glfs_readdirplus_r ARE thread safe AND re-entrant, - * but the interface has ambiguity about the size of @dirent to be allocated - * before calling the APIs. 512 byte buffer (for @dirent) is sufficient for - * all known systems which are tested againt glusterfs/gfapi, but may be - * insufficient in the future. + * @cmd and @flock are as specified in man fcntl(2). */ +int +glfs_posix_lock(glfs_fd_t *fd, int cmd, struct flock *flock) __THROW + GFAPI_PUBLIC(glfs_posix_lock, 3.4.0); -int glfs_readdir_r (glfs_fd_t *fd, struct dirent *dirent, - struct dirent **result) __THROW - GFAPI_PUBLIC(glfs_readdir_r, 3.4.0); +/* + SYNOPSIS + + glfs_file_lock: Request extended byte range lock on a file + + DESCRIPTION + + This function is capable of requesting either advisory or mandatory type + byte range locks on a file. + + Note: To set a unique owner key for locks based on a particular file + descriptor, make use of glfs_fd_set_lkowner() api to do so before + requesting lock via this api. This owner key will be further consumed + by other incoming data modifying file operations via the same file + descriptor. -int glfs_readdirplus_r (glfs_fd_t *fd, struct stat *stat, struct dirent *dirent, - struct dirent **result) __THROW - GFAPI_PUBLIC(glfs_readdirplus_r, 3.4.0); + PARAMETERS + + @fd: File descriptor + + @cmd: As specified in man fcntl(2). + + @flock: As specified in man fcntl(2). + + @lk_mode: Required lock type from options available with the + enum glfs_lock_mode_t defined below. + + RETURN VALUES + + 0 : Success. Lock has been granted. + -1 : Failure. @errno will be set indicating the type of failure. + + */ + +/* Lock modes used by glfs_file_lock() */ +enum glfs_lock_mode { GLFS_LK_ADVISORY = 0, GLFS_LK_MANDATORY }; +typedef enum glfs_lock_mode glfs_lock_mode_t; + +int +glfs_file_lock(glfs_fd_t *fd, int cmd, struct flock *flock, + glfs_lock_mode_t lk_mode) __THROW + GFAPI_PUBLIC(glfs_file_lock, 3.13.0); + +glfs_fd_t * +glfs_dup(glfs_fd_t *fd) __THROW GFAPI_PUBLIC(glfs_dup, 3.4.0); + +void +glfs_free(void *ptr) __THROW GFAPI_PUBLIC(glfs_free, 3.7.16); /* - * @glfs_readdir and @glfs_readdirplus are NEITHER thread safe NOR re-entrant - * when called on the same directory handle. However they ARE thread safe - * AND re-entrant when called on different directory handles (which may be - * referring to the same directory too.) + * glfs_sysrq: send a system request to the @fs instance + * + * Different commands for @sysrq are possible, the defines for these are listed + * below the function definition. + * + * This function always returns success if the @sysrq is recognized. The return + * value does not way anythin about the result of the @sysrq execution. Not all + * @sysrq command will be able to return a success/failure status. */ +int +glfs_sysrq(glfs_t *fs, char sysrq) __THROW GFAPI_PUBLIC(glfs_sysrq, 3.10.0); -struct dirent *glfs_readdir (glfs_fd_t *fd) __THROW - GFAPI_PUBLIC(glfs_readdir, 3.5.0); +#define GLFS_SYSRQ_HELP 'h' /* log a message with supported sysrq commands */ +#define GLFS_SYSRQ_STATEDUMP 's' /* create a statedump */ -struct dirent *glfs_readdirplus (glfs_fd_t *fd, struct stat *stat) __THROW - GFAPI_PUBLIC(glfs_readdirplus, 3.5.0); +/* + * Structure returned as part of xreaddirplus + */ +struct glfs_xreaddirp_stat; +typedef struct glfs_xreaddirp_stat glfs_xreaddirp_stat_t; -long glfs_telldir (glfs_fd_t *fd) __THROW - GFAPI_PUBLIC(glfs_telldir, 3.4.0); +/* Request flags to be used in XREADDIRP operation */ +#define GFAPI_XREADDIRP_NULL \ + 0x00000000 /* by default, no stat will be fetched */ +#define GFAPI_XREADDIRP_STAT 0x00000001 /* Get stat */ +#define GFAPI_XREADDIRP_HANDLE 0x00000002 /* Get object handle */ + +/* + * This stat structure returned gets freed as part of glfs_free(xstat) + */ +struct stat * +glfs_xreaddirplus_get_stat(glfs_xreaddirp_stat_t *xstat) __THROW + GFAPI_PUBLIC(glfs_xreaddirplus_get_stat, 3.11.0); + +/* + * SYNOPSIS + * + * glfs_xreaddirplus_r: Extended Readirplus operation + * + * DESCRIPTION + * + * This API does readdirplus operation, but along with stat it can fetch other + * extra information like object handles etc for each of the dirents returned + * based on requested flags. On success it returns the set of flags successfully + * processed. + * + * Note that there are chances that some of the requested information may not be + * available or returned (for example if reached EOD). Ensure to validate the + * returned value to determine what flags have been successfully processed + * & set. + * + * PARAMETERS + * + * INPUT: + * @glfd: GFAPI file descriptor of the directory + * @flags: Flags determining xreaddirp_stat requested + * Current available values are: + * GFAPI_XREADDIRP_NULL + * GFAPI_XREADDIRP_STAT + * GFAPI_XREADDIRP_HANDLE + * @ext: Dirent struture to copy the values to + * (though optional recommended to be allocated by application + * esp., in multi-threaded environment) + * + * OUTPUT: + * @res: to store the next dirent value. If NULL and return value is '0', + * it means it reached end of the directory. + * @xstat_p: Pointer to contain all the requested data returned + * for that dirent. Application should make use of glfs_free() API + * to free this pointer and the variables returned by + * glfs_xreaddirplus_get_*() APIs. + * + * RETURN VALUE: + * >=0: SUCCESS (value contains the flags successfully processed) + * -1: FAILURE + */ +int +glfs_xreaddirplus_r(glfs_fd_t *glfd, uint32_t flags, + glfs_xreaddirp_stat_t **xstat_p, struct dirent *ext, + struct dirent **res) __THROW + GFAPI_PUBLIC(glfs_xreaddirplus_r, 3.11.0); -void glfs_seekdir (glfs_fd_t *fd, long offset) __THROW - GFAPI_PUBLIC(glfs_seekdir, 3.4.0); +#define GFAPI_MAX_LOCK_OWNER_LEN 255 + +/* + * + * DESCRIPTION + * + * This API allows application to set lk_owner on a fd. + * A glfd can be associated with only single lk_owner. In case if there + * is need to set another lk_owner, applications can make use of + * 'glfs_dup' to get duplicate glfd and set new lk_owner on that second + * glfd. + * + * Also its not recommended to override or clear lk_owner value as the + * same shall be used to flush any outstanding locks while closing the fd. + * + * PARAMETERS + * + * INPUT: + * @glfd: GFAPI file descriptor + * @len: Size of lk_owner buffer. Max value can be GFAPI_MAX_LOCK_OWNER_LEN + * @data: lk_owner data buffer. + * + * OUTPUT: + * 0: SUCCESS + * -1: FAILURE + */ +int +glfs_fd_set_lkowner(glfs_fd_t *glfd, void *data, int len) __THROW + GFAPI_PUBLIC(glfs_fd_set_lkowner, 3.10.7); + +/* + * Applications (currently NFS-Ganesha) can make use of this + * structure to read upcall notifications sent by server either + * by polling or registering a callback function. + * + * On success, applications need to check for 'reason' to decide + * if any upcall event is received. + * + * Currently supported upcall_events - + * GLFS_UPCALL_INODE_INVALIDATE - + * 'event_arg' - glfs_upcall_inode + * + * After processing the event, applications need to free 'event_arg' with + * glfs_free(). + * + * Also similar to I/Os, the application should ideally stop polling + * or unregister upcall_cbk function before calling glfs_fini(..). + * Hence making an assumption that 'fs' & ctx structures cannot be + * freed while in this routine. + */ +struct glfs_upcall; +typedef struct glfs_upcall glfs_upcall_t; + +glfs_t * +glfs_upcall_get_fs(glfs_upcall_t *arg) __THROW + GFAPI_PUBLIC(glfs_upcall_get_fs, 3.7.16); + +enum glfs_upcall_reason { + GLFS_UPCALL_EVENT_NULL = 0, + GLFS_UPCALL_INODE_INVALIDATE, /* invalidate cache entry */ + GLFS_UPCALL_RECALL_LEASE, /* recall lease */ +}; +typedef enum glfs_upcall_reason glfs_upcall_reason_t; + +glfs_upcall_reason_t +glfs_upcall_get_reason(glfs_upcall_t *arg) __THROW + GFAPI_PUBLIC(glfs_upcall_get_reason, 3.7.16); + +/* + * Applications first need to make use of above API i.e, + * "glfs_upcall_get_reason" to determine which upcall event it has + * received. Post that below API - "glfs_upcall_get_event" should + * be used to get corresponding upcall event object. + * + * Below are the upcall_reason and corresponding upcall_event objects: + * ========================================================== + * glfs_upcall_reason - event_object + * ========================================================== + * GLFS_UPCALL_EVENT_NULL - NULL + * GLFS_UPCALL_INODE_INVALIDATE - struct glfs_upcall_inode + * GLFS_UPCALL_RECALL_LEASE - struct glfs_upcall_lease + * + * After processing upcall event, glfs_free() should be called on the + * glfs_upcall. + */ +void * +glfs_upcall_get_event(glfs_upcall_t *arg) __THROW + GFAPI_PUBLIC(glfs_upcall_get_event, 3.7.16); + +/* + * SYNOPSIS + * + * glfs_upcall_cbk: Upcall callback definition + * + * This is function type definition of the callback function pointer + * which has to be provided by the caller while registering for any + * upcall events. + * + * This function is called whenever any upcall which the application + * has registered for is received from the server. + * + * @up_arg: Upcall structure whose contents need to be interpreted by + * making use of glfs_upcall_* helper routines. + * + * @data: The same context pointer provided by the caller at the time of + * registering of upcall events. This may be used by the caller for any + * of its internal use while processing upcalls. + */ +typedef void (*glfs_upcall_cbk)(glfs_upcall_t *up_arg, void *data); -int glfs_closedir (glfs_fd_t *fd) __THROW - GFAPI_PUBLIC(glfs_closedir, 3.4.0); +/* + * List of upcall events supported by gluster/gfapi + */ +#define GLFS_EVENT_INODE_INVALIDATE 0x00000001 /* invalidate cache entry */ +#define GLFS_EVENT_RECALL_LEASE 0x00000002 /* Recall lease */ +#define GLFS_EVENT_ANY 0xffffffff /* for all the above events */ -int glfs_statvfs (glfs_t *fs, const char *path, struct statvfs *buf) __THROW - GFAPI_PUBLIC(glfs_statvfs, 3.4.0); +/* + * SYNOPSIS + * + * glfs_upcall_register: Register for upcall events + * + * DESCRIPTION + * + * This function is used to register for various upcall events application + * is interested in and the callback function to be invoked when such + * events are triggered. + * + * Multiple calls of this routine shall override cbk function. That means + * only one cbk function can be used for all the upcall events registered + * and that shall be the one last updated. + * + * PARAMETERS: + * + * INPUT: + * @fs: The 'virtual mount' object + * + * @event_list: List of upcall events to be registered. + * Current available values are: + * - GLFS_EVENT_INODE_INVALIDATE + * - GLFS_EVENT_RECALL_LEASE + * + * @cbk: The cbk routine to be invoked in case of any upcall received + * @data: Any opaque pointer provided by caller which shall be using while + * making cbk calls. This pointer may be used by caller for any of its + * internal use while processing upcalls. Can be NULL. + * + * RETURN VALUE: + * >0: SUCCESS (value contains the events successfully registered) + * -1: FAILURE + */ +int +glfs_upcall_register(glfs_t *fs, uint32_t event_list, glfs_upcall_cbk cbk, + void *data) __THROW + GFAPI_PUBLIC(glfs_upcall_register, 3.13.0); -int glfs_chmod (glfs_t *fs, const char *path, mode_t mode) __THROW - GFAPI_PUBLIC(glfs_chmod, 3.4.0); +/* + * SYNOPSIS + * + * glfs_upcall_unregister: Unregister for upcall events + * + * DESCRIPTION + * + * This function is used to unregister the upcall events application + * is not interested in. In case if the caller unregisters all the events + * it has registered for, it shall no more receive any upcall event. + * + * PARAMETERS: + * + * INPUT: + * @fs: The 'virtual mount' object + * + * @event_list: List of upcall events to be unregistered. + * Current available values are: + * - GLFS_EVENT_INODE_INVALIDATE + * - GLFS_EVENT_RECALL_LEASE + * RETURN VALUE: + * >0: SUCCESS (value contains the events successfully unregistered) + * -1: FAILURE + */ +int +glfs_upcall_unregister(glfs_t *fs, uint32_t event_list) __THROW + GFAPI_PUBLIC(glfs_upcall_unregister, 3.13.0); + +/* Lease Types */ +enum glfs_lease_types { + GLFS_LEASE_NONE = 0, + GLFS_RD_LEASE = 1, + GLFS_RW_LEASE = 2, +}; +typedef enum glfs_lease_types glfs_lease_types_t; + +/* Lease cmds */ +enum glfs_lease_cmds { + GLFS_GET_LEASE = 1, + GLFS_SET_LEASE = 2, + GLFS_UNLK_LEASE = 3, +}; +typedef enum glfs_lease_cmds glfs_lease_cmds_t; + +struct glfs_lease { + glfs_lease_cmds_t cmd; + glfs_lease_types_t lease_type; + glfs_leaseid_t lease_id; + unsigned int lease_flags; +}; +typedef struct glfs_lease glfs_lease_t; + +typedef void (*glfs_recall_cbk)(glfs_lease_t lease, void *data); -int glfs_fchmod (glfs_fd_t *fd, mode_t mode) __THROW - GFAPI_PUBLIC(glfs_fchmod, 3.4.0); +/* + SYNOPSIS -int glfs_chown (glfs_t *fs, const char *path, uid_t uid, gid_t gid) __THROW - GFAPI_PUBLIC(glfs_chown, 3.4.0); + glfs_lease: Takes a lease on a file. -int glfs_lchown (glfs_t *fs, const char *path, uid_t uid, gid_t gid) __THROW - GFAPI_PUBLIC(glfs_lchown, 3.4.0); + DESCRIPTION -int glfs_fchown (glfs_fd_t *fd, uid_t uid, gid_t gid) __THROW - GFAPI_PUBLIC(glfs_fchown, 3.4.0); + This function takes lease on an open file. -int glfs_utimens (glfs_t *fs, const char *path, - const struct timespec times[2]) __THROW - GFAPI_PUBLIC(glfs_utimens, 3.4.0); + PARAMETERS -int glfs_lutimens (glfs_t *fs, const char *path, - const struct timespec times[2]) __THROW - GFAPI_PUBLIC(glfs_lutimens, 3.4.0); + @glfd: The fd of the file on which lease should be taken, + this fd is returned by glfs_open/glfs_create. -int glfs_futimens (glfs_fd_t *fd, const struct timespec times[2]) __THROW - GFAPI_PUBLIC(glfs_futimens, 3.4.0); + @lease: Struct that defines the lease operation to be performed + on the file. + @lease.cmd - Can be one of the following values + GF_GET_LEASE: Get the lease type currently present on the file, + lease.lease_type will contain GF_RD_LEASE + or GF_RW_LEASE or 0 if no leases. + GF_SET_LEASE: Set the lease of given lease.lease_type on the file. + GF_UNLK_LEASE: Unlock the lease present on the given fd. + Note that the every lease request should have + a corresponding unlk_lease. -ssize_t glfs_getxattr (glfs_t *fs, const char *path, const char *name, - void *value, size_t size) __THROW - GFAPI_PUBLIC(glfs_getxattr, 3.4.0); + @lease.lease_type - Can be one of the following values + GF_RD_LEASE: Read lease on a file, shared lease. + GF_RW_LEASE: Read-Write lease on a file, exclusive lease. -ssize_t glfs_lgetxattr (glfs_t *fs, const char *path, const char *name, - void *value, size_t size) __THROW - GFAPI_PUBLIC(glfs_lgetxattr, 3.4.0); + @lease.lease_id - A unique identification of lease, 128bits. -ssize_t glfs_fgetxattr (glfs_fd_t *fd, const char *name, - void *value, size_t size) __THROW - GFAPI_PUBLIC(glfs_fgetxattr, 3.4.0); + @fn: This is the function that is invoked when the lease has to be recalled + @data: It is a cookie, this pointer is returned as a part of recall -ssize_t glfs_listxattr (glfs_t *fs, const char *path, - void *value, size_t size) __THROW - GFAPI_PUBLIC(glfs_listxattr, 3.4.0); + fn and data field are stored as a part of glfs_fd, hence if there are multiple + glfs_lease calls, each of them updates the fn and data fields. glfs_recall_cbk + will be invoked with the last updated fn and data -ssize_t glfs_llistxattr (glfs_t *fs, const char *path, void *value, - size_t size) __THROW - GFAPI_PUBLIC(glfs_llistxattr, 3.4.0); + RETURN VALUES + 0: Successful completion + <0: Failure. @errno will be set with the type of failure +*/ -ssize_t glfs_flistxattr (glfs_fd_t *fd, void *value, size_t size) __THROW - GFAPI_PUBLIC(glfs_flistxattr, 3.4.0); +int +glfs_lease(glfs_fd_t *glfd, glfs_lease_t *lease, glfs_recall_cbk fn, + void *data) __THROW GFAPI_PUBLIC(glfs_lease, 4.0.0); -int glfs_setxattr (glfs_t *fs, const char *path, const char *name, - const void *value, size_t size, int flags) __THROW - GFAPI_PUBLIC(glfs_setxattr, 3.4.0); +/* + SYNOPSIS -int glfs_lsetxattr (glfs_t *fs, const char *path, const char *name, - const void *value, size_t size, int flags) __THROW - GFAPI_PUBLIC(glfs_lsetxattr, 3.4.0); + glfs_fsetattr: Function to set attributes. + glfs_setattr: Function to set attributes -int glfs_fsetxattr (glfs_fd_t *fd, const char *name, - const void *value, size_t size, int flags) __THROW - GFAPI_PUBLIC(glfs_fsetxattr, 3.4.0); + DESCRIPTION -int glfs_removexattr (glfs_t *fs, const char *path, const char *name) __THROW - GFAPI_PUBLIC(glfs_removexattr, 3.4.0); + The functions are used to set attributes on the file. -int glfs_lremovexattr (glfs_t *fs, const char *path, const char *name) __THROW - GFAPI_PUBLIC(glfs_lremovexattr, 3.4.0); + PARAMETERS -int glfs_fremovexattr (glfs_fd_t *fd, const char *name) __THROW - GFAPI_PUBLIC(glfs_fremovexattr, 3.4.0); + @glfs_fsetattr -int glfs_fallocate(glfs_fd_t *fd, int keep_size, - off_t offset, size_t len) __THROW - GFAPI_PUBLIC(glfs_fallocate, 3.5.0); + @glfd: The fd of the file for which the attributes are to be set, + this fd is returned by glfs_open/glfs_create. -int glfs_discard(glfs_fd_t *fd, off_t offset, size_t len) __THROW - GFAPI_PUBLIC(glfs_discard, 3.5.0); + @glfs_setattr + @fs: File object. -int glfs_discard_async (glfs_fd_t *fd, off_t length, size_t lent, - glfs_io_cbk fn, void *data) __THROW - GFAPI_PUBLIC(glfs_discard_async, 3.5.0); + @path: The path of the file that is being operated on. -int glfs_zerofill(glfs_fd_t *fd, off_t offset, off_t len) __THROW - GFAPI_PUBLIC(glfs_zerofill, 3.5.0); + @follow: Flag used to resolve symlink. -int glfs_zerofill_async (glfs_fd_t *fd, off_t length, off_t len, - glfs_io_cbk fn, void *data) __THROW - GFAPI_PUBLIC(glfs_zerofill_async, 3.5.0); -char *glfs_getcwd (glfs_t *fs, char *buf, size_t size) __THROW - GFAPI_PUBLIC(glfs_getcwd, 3.4.0); + @stat: Struct that has information about the file. -int glfs_chdir (glfs_t *fs, const char *path) __THROW - GFAPI_PUBLIC(glfs_chdir, 3.4.0); + @valid: This is the mask bit, that accepts GFAPI_SET_ATTR* masks. + Refer glfs.h to see the mask definitions. -int glfs_fchdir (glfs_fd_t *fd) __THROW - GFAPI_PUBLIC(glfs_fchdir, 3.4.0); + Both functions are similar in functionality, just that the + func setattr() uses file path whereas the func fsetattr() + uses the fd. -char *glfs_realpath (glfs_t *fs, const char *path, char *resolved_path) __THROW - GFAPI_PUBLIC(glfs_realpath, 3.4.0); + RETURN VALUES + 0: Successful completion + <0: Failure. @errno will be set with the type of failure -/* - * @cmd and @flock are as specified in man fcntl(2). */ -int glfs_posix_lock (glfs_fd_t *fd, int cmd, struct flock *flock) __THROW - GFAPI_PUBLIC(glfs_posix_lock, 3.4.0); -glfs_fd_t *glfs_dup (glfs_fd_t *fd) __THROW - GFAPI_PUBLIC(glfs_dup, 3.4.0); +int +glfs_fsetattr(struct glfs_fd *glfd, struct glfs_stat *stat) __THROW + GFAPI_PUBLIC(glfs_fsetattr, 6.0); -void glfs_free (void *ptr) __THROW - GFAPI_PUBLIC(glfs_free, 3.7.16); +int +glfs_setattr(struct glfs *fs, const char *path, struct glfs_stat *stat, + int follow) __THROW GFAPI_PUBLIC(glfs_setattr, 6.0); /* - * No xdata support for now. Nobody needs this call at all yet except for the - * test script, and that doesn't need xdata. Adding dict_t support and a new - * header-file requirement doesn't seem worth it until the need is greater. + SYNOPSIS + + glfs_set_statedump_path: Function to set statedump path. + + DESCRIPTION + + This function is used to set statedump directory + + PARAMETERS + + @fs: The 'virtual mount' object to be configured with the volume + specification file. + + @path: statedump path. Should be a directory. But the API won't fail if the + directory doesn't exist yet, as one may create it later. + + RETURN VALUES + + 0 : Success. + -1 : Failure. @errno will be set with the type of failure. + */ -int glfs_ipc (glfs_fd_t *fd, int cmd) __THROW - GFAPI_PUBLIC(glfs_ipc, 3.7.0); -__END_DECLS +int +glfs_set_statedump_path(struct glfs *fs, const char *path) __THROW + GFAPI_PUBLIC(glfs_set_statedump_path, 7.0); +__END_DECLS #endif /* !_GLFS_H */ |