fuse_lowlevel.h File Reference

#include "fuse_common.h"
#include <utime.h>
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <sys/statvfs.h>
#include <sys/uio.h>
#include "fuse_lowlevel_compat.h"

Data Structures
struct	fuse_entry_param
struct	fuse_ctx
struct	fuse_lowlevel_ops
struct	fuse_session_ops
struct	fuse_chan_ops

Macros
#define	FUSE_ROOT_ID   1

Typedefs
typedef unsigned long	fuse_ino_t
typedef struct fuse_req *	fuse_req_t
typedef void(*	fuse_interrupt_func_t )(fuse_req_t req, void *data)

Functions
int	fuse_reply_err (fuse_req_t req, int err)
void	fuse_reply_none (fuse_req_t req)
int	fuse_reply_entry (fuse_req_t req, const struct fuse_entry_param *e)
int	fuse_reply_create (fuse_req_t req, const struct fuse_entry_param *e, const struct fuse_file_info *fi)
int	fuse_reply_attr (fuse_req_t req, const struct stat *attr, double attr_timeout)
int	fuse_reply_readlink (fuse_req_t req, const char *link)
int	fuse_reply_open (fuse_req_t req, const struct fuse_file_info *fi)
int	fuse_reply_write (fuse_req_t req, size_t count)
int	fuse_reply_buf (fuse_req_t req, const char *buf, size_t size)
int	fuse_reply_data (fuse_req_t req, struct fuse_bufvec *bufv, enum fuse_buf_copy_flags flags)
int	fuse_reply_iov (fuse_req_t req, const struct iovec *iov, int count)
int	fuse_reply_statfs (fuse_req_t req, const struct statvfs *stbuf)
int	fuse_reply_xattr (fuse_req_t req, size_t count)
int	fuse_reply_lock (fuse_req_t req, const struct flock *lock)
int	fuse_reply_bmap (fuse_req_t req, uint64_t idx)
size_t	fuse_add_direntry (fuse_req_t req, char *buf, size_t bufsize, const char *name, const struct stat *stbuf, off_t off)
int	fuse_reply_ioctl_retry (fuse_req_t req, const struct iovec *in_iov, size_t in_count, const struct iovec *out_iov, size_t out_count)
int	fuse_reply_ioctl (fuse_req_t req, int result, const void *buf, size_t size)
int	fuse_reply_ioctl_iov (fuse_req_t req, int result, const struct iovec *iov, int count)
int	fuse_reply_poll (fuse_req_t req, unsigned revents)
int	fuse_lowlevel_notify_poll (struct fuse_pollhandle *ph)
int	fuse_lowlevel_notify_inval_inode (struct fuse_chan *ch, fuse_ino_t ino, off_t off, off_t len)
int	fuse_lowlevel_notify_inval_entry (struct fuse_chan *ch, fuse_ino_t parent, const char *name, size_t namelen)
int	fuse_lowlevel_notify_delete (struct fuse_chan *ch, fuse_ino_t parent, fuse_ino_t child, const char *name, size_t namelen)
int	fuse_lowlevel_notify_store (struct fuse_chan *ch, fuse_ino_t ino, off_t offset, struct fuse_bufvec *bufv, enum fuse_buf_copy_flags flags)
int	fuse_lowlevel_notify_retrieve (struct fuse_chan *ch, fuse_ino_t ino, size_t size, off_t offset, void *cookie)
void *	fuse_req_userdata (fuse_req_t req)
const struct fuse_ctx *	fuse_req_ctx (fuse_req_t req)
int	fuse_req_getgroups (fuse_req_t req, int size, gid_t list[])
void	fuse_req_interrupt_func (fuse_req_t req, fuse_interrupt_func_t func, void *data)
int	fuse_req_interrupted (fuse_req_t req)
struct fuse_session *	fuse_lowlevel_new (struct fuse_args *args, const struct fuse_lowlevel_ops *op, size_t op_size, void *userdata)
struct fuse_session *	fuse_session_new (struct fuse_session_ops *op, void *data)
void	fuse_session_add_chan (struct fuse_session *se, struct fuse_chan *ch)
void	fuse_session_remove_chan (struct fuse_chan *ch)
struct fuse_chan *	fuse_session_next_chan (struct fuse_session *se, struct fuse_chan *ch)
void	fuse_session_process (struct fuse_session *se, const char *buf, size_t len, struct fuse_chan *ch)
void	fuse_session_process_buf (struct fuse_session *se, const struct fuse_buf *buf, struct fuse_chan *ch)
int	fuse_session_receive_buf (struct fuse_session *se, struct fuse_buf *buf, struct fuse_chan **chp)
void	fuse_session_destroy (struct fuse_session *se)
void	fuse_session_exit (struct fuse_session *se)
void	fuse_session_reset (struct fuse_session *se)
int	fuse_session_exited (struct fuse_session *se)
void *	fuse_session_data (struct fuse_session *se)
int	fuse_session_loop (struct fuse_session *se)
int	fuse_session_loop_mt (struct fuse_session *se)
struct fuse_chan *	fuse_chan_new (struct fuse_chan_ops *op, int fd, size_t bufsize, void *data)
int	fuse_chan_fd (struct fuse_chan *ch)
size_t	fuse_chan_bufsize (struct fuse_chan *ch)
void *	fuse_chan_data (struct fuse_chan *ch)
struct fuse_session *	fuse_chan_session (struct fuse_chan *ch)
int	fuse_chan_recv (struct fuse_chan **ch, char *buf, size_t size)
int	fuse_chan_send (struct fuse_chan *ch, const struct iovec iov[], size_t count)
void	fuse_chan_destroy (struct fuse_chan *ch)

Detailed Description

Low level API

IMPORTANT: you should define FUSE_USE_VERSION before including this header. To use the newest API define it to 26 (recommended for any new application), to use the old API define it to 24 (default) or 25

Macro Definition Documentation

#define FUSE_ROOT_ID   1

The node ID of the root inode

Typedef Documentation

typedef unsigned long fuse_ino_t

Inode number type

typedef void(* fuse_interrupt_func_t)(fuse_req_t req, void *data)

Callback function for an interrupt

Parameters

req	interrupted request
data	user data

typedef struct fuse_req* fuse_req_t

Request pointer type

Function Documentation

size_t fuse_add_direntry	(	fuse_req_t	req,
		char *	buf,
		size_t	bufsize,
		const char *	name,
		const struct stat *	stbuf,
		off_t	off
	)

Add a directory entry to the buffer

Buffer needs to be large enough to hold the entry. If it's not, then the entry is not filled in but the size of the entry is still returned. The caller can check this by comparing the bufsize parameter with the returned entry size. If the entry size is larger than the buffer size, the operation failed.

From the 'stbuf' argument the st_ino field and bits 12-15 of the st_mode field are used. The other fields are ignored.

Note: offsets do not necessarily represent physical offsets, and could be any marker, that enables the implementation to find a specific point in the directory stream.

Parameters

req	request handle
buf	the point where the new entry will be added to the buffer
bufsize	remaining size of the buffer
name	the name of the entry
stbuf	the file attributes
off	the offset of the next entry

Returns

the space needed for the entry

size_t fuse_chan_bufsize

(

struct fuse_chan *

ch

)

Query the minimal receive buffer size

Parameters

ch	the channel

Returns

the buffer size passed to fuse_chan_new()

void* fuse_chan_data

(

struct fuse_chan *

ch

)

Query the user data

Parameters

ch	the channel

Returns

the user data passed to fuse_chan_new()

void fuse_chan_destroy

(

struct fuse_chan *

ch

)

Destroy a channel

Parameters

ch	the channel

int fuse_chan_fd

(

struct fuse_chan *

ch

)

Query the file descriptor of the channel

Parameters

ch	the channel

Returns

the file descriptor passed to fuse_chan_new()

struct fuse_chan* fuse_chan_new	(	struct fuse_chan_ops *	op,
		int	fd,
		size_t	bufsize,
		void *	data
	)

Create a new channel

Parameters

op	channel operations
fd	file descriptor of the channel
bufsize	the minimal receive buffer size
data	user data

Returns

the new channel object, or NULL on failure

int fuse_chan_recv	(	struct fuse_chan **	ch,
		char *	buf,
		size_t	size
	)

Receive a raw request

A return value of -ENODEV means, that the filesystem was unmounted

Parameters

ch	pointer to the channel
buf	the buffer to store the request in
size	the size of the buffer

Returns

the actual size of the raw request, or -errno on error

int fuse_chan_send	(	struct fuse_chan *	ch,
		const struct iovec	iov[],
		size_t	count
	)

Send a raw reply

A return value of -ENOENT means, that the request was interrupted, and the reply was discarded

Parameters

ch	the channel
iov	vector of blocks
count	the number of blocks in vector

Returns

zero on success, -errno on failure

struct fuse_session* fuse_chan_session

(

struct fuse_chan *

ch

)

Query the session to which this channel is assigned

Parameters

ch	the channel

Returns

the session, or NULL if the channel is not assigned

struct fuse_session* fuse_lowlevel_new	(	struct fuse_args *	args,
		const struct fuse_lowlevel_ops *	op,
		size_t	op_size,
		void *	userdata
	)

Create a low level session

Parameters

args	argument vector
op	the low level filesystem operations
op_size	sizeof(struct fuse_lowlevel_ops)
userdata	user data

Returns

the created session object, or NULL on failure

int fuse_lowlevel_notify_delete	(	struct fuse_chan *	ch,
		fuse_ino_t	parent,
		fuse_ino_t	child,
		const char *	name,
		size_t	namelen
	)

Notify to invalidate parent attributes and delete the dentry matching parent/name if the dentry's inode number matches child (otherwise it will invalidate the matching dentry).

To avoid a deadlock don't call this function from a filesystem operation and don't call it with a lock held that can also be held by a filesystem operation.

Parameters

ch	the channel through which to send the notification
parent	inode number
child	inode number
name	file name
namelen	strlen() of file name

Returns

zero for success, -errno for failure

int fuse_lowlevel_notify_inval_entry	(	struct fuse_chan *	ch,
		fuse_ino_t	parent,
		const char *	name,
		size_t	namelen
	)

Notify to invalidate parent attributes and the dentry matching parent/name

To avoid a deadlock don't call this function from a filesystem operation and don't call it with a lock held that can also be held by a filesystem operation.

Parameters

ch	the channel through which to send the invalidation
parent	inode number
name	file name
namelen	strlen() of file name

Returns

zero for success, -errno for failure

int fuse_lowlevel_notify_inval_inode	(	struct fuse_chan *	ch,
		fuse_ino_t	ino,
		off_t	off,
		off_t	len
	)

Notify to invalidate cache for an inode

Parameters

ch	the channel through which to send the invalidation
ino	the inode number
off	the offset in the inode where to start invalidating or negative to invalidate attributes only
len	the amount of cache to invalidate or 0 for all

Returns

zero for success, -errno for failure

int fuse_lowlevel_notify_poll

(

struct fuse_pollhandle *

ph

)

Notify IO readiness event

For more information, please read comment for poll operation.

Parameters

ph	poll handle to notify IO readiness event for

int fuse_lowlevel_notify_retrieve	(	struct fuse_chan *	ch,
		fuse_ino_t	ino,
		size_t	size,
		off_t	offset,
		void *	cookie
	)

Retrieve data from the kernel buffers

Retrieve data in the kernel buffers belonging to the given inode. If successful then the retrieve_reply() method will be called with the returned data.

Only present pages are returned in the retrieve reply. Retrieving stops when it finds a non-present page and only data prior to that is returned.

If this function returns an error, then the retrieve will not be completed and no reply will be sent.

This function doesn't change the dirty state of pages in the kernel buffer. For dirty pages the write() method will be called regardless of having been retrieved previously.

Parameters

ch	the channel through which to send the invalidation
ino	the inode number
size	the number of bytes to retrieve
offset	the starting offset into the file to retrieve from
cookie	user data to supply to the reply callback

Returns

zero for success, -errno for failure

int fuse_lowlevel_notify_store	(	struct fuse_chan *	ch,
		fuse_ino_t	ino,
		off_t	offset,
		struct fuse_bufvec *	bufv,
		enum fuse_buf_copy_flags	flags
	)

Store data to the kernel buffers

Synchronously store data in the kernel buffers belonging to the given inode. The stored data is marked up-to-date (no read will be performed against it, unless it's invalidated or evicted from the cache).

If the stored data overflows the current file size, then the size is extended, similarly to a write(2) on the filesystem.

If this function returns an error, then the store wasn't fully completed, but it may have been partially completed.

Parameters

ch	the channel through which to send the invalidation
ino	the inode number
offset	the starting offset into the file to store to
bufv	buffer vector
flags	flags controlling the copy

Returns

zero for success, -errno for failure

int fuse_reply_attr	(	fuse_req_t	req,
		const struct stat *	attr,
		double	attr_timeout
	)

Reply with attributes

Possible requests: getattr, setattr

Parameters

req	request handle
attr	the attributes
attr_timeout	validity timeout (in seconds) for the attributes

Returns

zero for success, -errno for failure to send reply

int fuse_reply_bmap	(	fuse_req_t	req,
		uint64_t	idx
	)

Reply with block index

Possible requests: bmap

Parameters

req	request handle
idx	block index within device

Returns

zero for success, -errno for failure to send reply

int fuse_reply_buf	(	fuse_req_t	req,
		const char *	buf,
		size_t	size
	)

Reply with data

Possible requests: read, readdir, getxattr, listxattr

Parameters

req	request handle
buf	buffer containing data
size	the size of data in bytes

Returns

zero for success, -errno for failure to send reply

int fuse_reply_create	(	fuse_req_t	req,
		const struct fuse_entry_param *	e,
		const struct fuse_file_info *	fi
	)

Reply with a directory entry and open parameters

currently the following members of 'fi' are used: fh, direct_io, keep_cache

Possible requests: create

Side effects: increments the lookup count on success

Parameters

req	request handle
e	the entry parameters
fi	file information

Returns

zero for success, -errno for failure to send reply

int fuse_reply_data	(	fuse_req_t	req,
		struct fuse_bufvec *	bufv,
		enum fuse_buf_copy_flags	flags
	)

Reply with data copied/moved from buffer(s)

Possible requests: read, readdir, getxattr, listxattr

Parameters

req	request handle
bufv	buffer vector
flags	flags controlling the copy

Returns

zero for success, -errno for failure to send reply

int fuse_reply_entry	(	fuse_req_t	req,
		const struct fuse_entry_param *	e
	)

Reply with a directory entry

Possible requests: lookup, mknod, mkdir, symlink, link

Side effects: increments the lookup count on success

Parameters

req	request handle
e	the entry parameters

Returns

zero for success, -errno for failure to send reply

int fuse_reply_err	(	fuse_req_t	req,
		int	err
	)

Reply with an error code or success

Possible requests: all except forget

unlink, rmdir, rename, flush, release, fsync, fsyncdir, setxattr, removexattr and setlk may send a zero code

Parameters

req	request handle
err	the positive error value, or zero for success

Returns

zero for success, -errno for failure to send reply

int fuse_reply_ioctl	(	fuse_req_t	req,
		int	result,
		const void *	buf,
		size_t	size
	)

Reply to finish ioctl

Possible requests: ioctl

Parameters

req	request handle
result	result to be passed to the caller
buf	buffer containing output data
size	length of output data

int fuse_reply_ioctl_iov	(	fuse_req_t	req,
		int	result,
		const struct iovec *	iov,
		int	count
	)

Reply to finish ioctl with iov buffer

Possible requests: ioctl

Parameters

req	request handle
result	result to be passed to the caller
iov	the vector containing the data
count	the size of vector

int fuse_reply_ioctl_retry	(	fuse_req_t	req,
		const struct iovec *	in_iov,
		size_t	in_count,
		const struct iovec *	out_iov,
		size_t	out_count
	)

Reply to ask for data fetch and output buffer preparation. ioctl will be retried with the specified input data fetched and output buffer prepared.

Possible requests: ioctl

Parameters

req	request handle
in_iov	iovec specifying data to fetch from the caller
in_count	number of entries in in_iov
out_iov	iovec specifying addresses to write output to
out_count	number of entries in out_iov

Returns

zero for success, -errno for failure to send reply

int fuse_reply_iov	(	fuse_req_t	req,
		const struct iovec *	iov,
		int	count
	)

Reply with data vector

Possible requests: read, readdir, getxattr, listxattr

Parameters

req	request handle
iov	the vector containing the data
count	the size of vector

Returns

zero for success, -errno for failure to send reply

int fuse_reply_lock	(	fuse_req_t	req,
		const struct flock *	lock
	)

Reply with file lock information

Possible requests: getlk

Parameters

req	request handle
lock	the lock information

Returns

zero for success, -errno for failure to send reply

void fuse_reply_none

(

fuse_req_t

req

)

Don't send reply

Possible requests: forget

Parameters

req	request handle

int fuse_reply_open	(	fuse_req_t	req,
		const struct fuse_file_info *	fi
	)

Reply with open parameters

currently the following members of 'fi' are used: fh, direct_io, keep_cache

Possible requests: open, opendir

Parameters

req	request handle
fi	file information

Returns

zero for success, -errno for failure to send reply

int fuse_reply_poll	(	fuse_req_t	req,
		unsigned	revents
	)

Reply with poll result event mask

Parameters

req	request handle
revents	poll result event mask

int fuse_reply_readlink	(	fuse_req_t	req,
		const char *	link
	)

Reply with the contents of a symbolic link

Possible requests: readlink

Parameters

req	request handle
link	symbolic link contents

Returns

zero for success, -errno for failure to send reply

int fuse_reply_statfs	(	fuse_req_t	req,
		const struct statvfs *	stbuf
	)

Reply with filesystem statistics

Possible requests: statfs

Parameters

req	request handle
stbuf	filesystem statistics

Returns

zero for success, -errno for failure to send reply

int fuse_reply_write	(	fuse_req_t	req,
		size_t	count
	)

Reply with number of bytes written

Possible requests: write

Parameters

req	request handle
count	the number of bytes written

Returns

zero for success, -errno for failure to send reply

int fuse_reply_xattr	(	fuse_req_t	req,
		size_t	count
	)

Reply with needed buffer size

Possible requests: getxattr, listxattr

Parameters

req	request handle
count	the buffer size needed in bytes

Returns

zero for success, -errno for failure to send reply

const struct fuse_ctx* fuse_req_ctx

(

fuse_req_t

req

)

Get the context from the request

The pointer returned by this function will only be valid for the request's lifetime

Parameters

req	request handle

Returns

the context structure

int fuse_req_getgroups	(	fuse_req_t	req,
		int	size,
		gid_t	list[]
	)

Get the current supplementary group IDs for the specified request

Similar to the getgroups(2) system call, except the return value is always the total number of group IDs, even if it is larger than the specified size.

The current fuse kernel module in linux (as of 2.6.30) doesn't pass the group list to userspace, hence this function needs to parse "/proc/$TID/task/$TID/status" to get the group IDs.

This feature may not be supported on all operating systems. In such a case this function will return -ENOSYS.

Parameters

req	request handle
size	size of given array
list	array of group IDs to be filled in

Returns

the total number of supplementary group IDs or -errno on failure

void fuse_req_interrupt_func	(	fuse_req_t	req,
		fuse_interrupt_func_t	func,
		void *	data
	)

Register/unregister callback for an interrupt

If an interrupt has already happened, then the callback function is called from within this function, hence it's not possible for interrupts to be lost.

Parameters

req	request handle
func	the callback function or NULL for unregister
data	user data passed to the callback function

int fuse_req_interrupted

(

fuse_req_t

req

)

Check if a request has already been interrupted

Parameters

req	request handle

Returns

1 if the request has been interrupted, 0 otherwise

void* fuse_req_userdata

(

fuse_req_t

req

)

Get the userdata from the request

Parameters

req	request handle

Returns

the user data passed to fuse_lowlevel_new()

void fuse_session_add_chan	(	struct fuse_session *	se,
		struct fuse_chan *	ch
	)

Assign a channel to a session

Note: currently only a single channel may be assigned. This may change in the future

If a session is destroyed, the assigned channel is also destroyed

Parameters

se	the session
ch	the channel

void* fuse_session_data

(

struct fuse_session *

se

)

Get the user data provided to the session

Parameters

se	the session

Returns

the user data

void fuse_session_destroy

(

struct fuse_session *

se

)

Destroy a session

Parameters

se	the session

void fuse_session_exit

(

struct fuse_session *

se

)

Exit a session

Parameters

se	the session

int fuse_session_exited

(

struct fuse_session *

se

)

Query the exited status of a session

Parameters

se	the session

Returns

1 if exited, 0 if not exited

int fuse_session_loop

(

struct fuse_session *

se

)

Enter a single threaded event loop

Parameters

se	the session

Returns

0 on success, -1 on error

int fuse_session_loop_mt

(

struct fuse_session *

se

)

Enter a multi-threaded event loop

Parameters

se	the session

Returns

0 on success, -1 on error

struct fuse_session* fuse_session_new	(	struct fuse_session_ops *	op,
		void *	data
	)

Create a new session

Parameters

op	session operations
data	user data

Returns

new session object, or NULL on failure

struct fuse_chan* fuse_session_next_chan	(	struct fuse_session *	se,
		struct fuse_chan *	ch
	)

Iterate over the channels assigned to a session

The iterating function needs to start with a NULL channel, and after that needs to pass the previously returned channel to the function.

Parameters

se	the session
ch	the previous channel, or NULL

Returns

the next channel, or NULL if no more channels exist

void fuse_session_process	(	struct fuse_session *	se,
		const char *	buf,
		size_t	len,
		struct fuse_chan *	ch
	)

Process a raw request

Parameters

se	the session
buf	buffer containing the raw request
len	request length
ch	channel on which the request was received

void fuse_session_process_buf	(	struct fuse_session *	se,
		const struct fuse_buf *	buf,
		struct fuse_chan *	ch
	)

Process a raw request supplied in a generic buffer

This is a more generic version of fuse_session_process(). The fuse_buf may contain a memory buffer or a pipe file descriptor.

Parameters

se	the session
buf	the fuse_buf containing the request
ch	channel on which the request was received

int fuse_session_receive_buf	(	struct fuse_session *	se,
		struct fuse_buf *	buf,
		struct fuse_chan **	chp
	)

Receive a raw request supplied in a generic buffer

This is a more generic version of fuse_chan_recv(). The fuse_buf supplied to this function contains a suitably allocated memory buffer. This may be overwritten with a file descriptor buffer.

Parameters

se	the session
buf	the fuse_buf to store the request in
chp	pointer to the channel

Returns

the actual size of the raw request, or -errno on error

void fuse_session_remove_chan

(

struct fuse_chan *

ch

)

Remove a channel from a session

If the channel is not assigned to a session, then this is a no-op

Parameters

ch	the channel to remove

void fuse_session_reset

(

struct fuse_session *

se

)

Reset the exited status of a session

Parameters

se	the session