fuse_lowlevel_new(3) – initialise and destroy a FUSE session

NAME

fuse_lowlevel_new, fuse_session_destroy, fuse_add_direntry — initialise and destroy a FUSE session

SYNOPSIS

/* -lfuse */
#include <fuse_lowlevel.h>

struct fuse_session *
fuse_lowlevel_new(struct fuse_args *args, const struct fuse_lowlevel_ops *ops, size_t ops_size, void *userdata);

void
fuse_session_destroy(struct fuse_session *se);

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

The fuse_lowlevel_new() function creates a new FUSE session using the low-level API. The low-level API gives the file system full control over request handling. This session handles communication between the kernel and the user-space filesystem implementation. The returned session must later be destroyed with fuse_session_destroy(). To begin processing requests, the caller must mount the file system with fuse_mount(3) and then enter a loop to process kernel requests, such as with fuse_session_loop(3).

The args parameter points to arguments that are used to configure the session. These arguments can be initialised from command-line arguments using FUSE_ARGS_INIT(3), or args may be NULL if no arguments need to be parsed. The following arguments are supported:

-d, -odebug: Enable debug output that prints details of each request received to standard error output.
-h, --help: Print a usage message to standard error output.
--V, --version: Print FUSE library version to standard error output.
-omax_write: The maximum number of bytes that the filesystem can handle in one write request.

The ops parameter points to the file system operations supported by the user-space file system daemon. See below.

The op_size parameter specifies the size of the struct fuse_lowlevel_ops structure in bytes. This allows forward compatibility when new operations are added.

The userdata parameter is a pointer to user-defined data that will be passed to the init() and destroy() handlers.

This function does not mount the filesystem or start the event loop. After creating the session, fuse_session_loop(3) can be called to begin handling requests.

FUSE operations work in the same way as their UNIX file system counterparts. A functional file system must implement at least lookup(), getattr(), readdir(), open(), read() and statfs(). The other functions are optional, and the struct members pointing to them can be set to NULL.

The fuse_lowlevel_ops structure contains one function pointer to each of the functions listed below. The return type of each function pointer is void.

The first parameter to each of these operations (except for init() and destroy()) is a reference to the kernel request. The relevant parameters from the requested file system operations are passed as arguments to each function.

All operations can report failure with fuse_reply_err(3). If no other response is indicated below, then operations must report success by passing 0 to the errno argument of fuse_reply_err(3).

The operations defined in the struct fuse_lowlevel_ops structure are:

access(fuse_req_t req, fuse_ino_t ino, int mask);

Not implemented. OpenBSD always behaves as if the default_permissions mount option was specified. See fuse_mount(3).

create(fuse_req_t req, fuse_ino_t parent, const char *name, most_t mode, struct fuse_file_info *ffi);

Not implemented. File systems must implement mknod() instead.

destroy(void *userdata)

This is the last handler called when the file system is unmounted.

flush(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *ffi);

Called when a regular file is closed by the close(2) system call. This is the only way for a file system to report an error on close.

The ino argument identifies the file to be closed.

The ffi argument is a struct fuse_file_info that contains the following fields:

fh: The file handle returned by the file system when the file was opened.
flush: 1 if the file should be flushed before being closed, or 0 otherwise.

fsync(fuse_req_t req, fuse_ino_t ino, int datasync, struct fuse_file_info *ffi);

Optional function that implements fsync(2) and fdatasync(2). The datasync parameter specifies whether the operation is as a result of a call to fdatasync(2) and is currently always 0 (false). ffi.fh is the file handle returned by the file system when the file was opened.

fsyncdir(fuse_req_t req, fuse_ino_t ino, int datasync, struct fuse_file_info *ffi);

Not implemented.

getattr(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *ffi);

Corresponds to the stat(2) system call.

On success, respond with fuse_reply_attr(3).

init(void *userdata, struct fuse_conn_info *fci);

This is the first handler called by the kernel when the file system is mounted. userdata is a pointer to the data passed to fuse_lowlevel_new(). fci contains connection information in the following structure:

struct fuse_conn_info {
        uint32_t        proto_major;
        uint32_t        proto_minor;
        uint32_t        async_read;
        uint32_t        max_write;
        uint32_t        max_readahead;
        uint32_t        capable;
        uint32_t        want;
        uint32_t        max_background;
        uint32_t        congestion_threshold;
        uint32_t        reserved[23];
};

link(fuse_req_t req, fuse_ino_t ino, fuse_ino_t newparent, const char *name);

Create a hard link to ino in directory parent with name.

On success, respond with fuse_reply_entry(3).

lookup(fuse_req_t req, fuse_ino_t newparent, const char *name);

Looks up an entry name in the directory specified by parent.

If the entry cannot be found then this operation should reply with ENOENT. Alternatively, an entry with ino = 0 can be returned. This is intended to indicate that the negative result can be cached for entry_timeout seconds. However, OpenBSD does not cache lookups so this is equivalent to returning ENOENT.

Valid responses are fuse_reply_err(3) and fuse_reply_entry(3).

mkdir(fuse_req_t req, fuse_ino_t parent, const char *name, mode_t mode);

Called on mkdir(2) to create a new directory name in directory parent with mode mode.

On success, respond with fuse_reply_entry(3).

mknod(fuse_req_t req, fuse_ino_t parent, const char *name, mode_t mode, dev_t rdev);

Called on open(2) and mknod(2) to create regular files, pipes and device special files with name in the directory specified by parent. mode specifies the file type and mode with which to create the file. rdev specifies the device number if creating a device.

On success, respond with fuse_reply_entry(3).

open(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *ffi);

Called on open(2) to open the file specified by ino. If the same file is opened more than once with the same access mode (O_RDONLY, O_WRONLY, or O_RDWR), no matter whether by the same process or by different processes, the OpenBSD kernel only calls the open() operation once, namely when the respective (file, mode) pair first occurs. The flags are available in the flags member of ffi. The O_CREAT and O_TRUNC flags are never passed from the kernel to open(); instead, the kernel invokes the mknod() and truncate() operations before open().

On success, respond with fuse_reply_open(3).

opendir(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *ffi);

Called when a directory is opened for reading.

On success, respond with fuse_reply_open(3).

read(fuse_req_t req, fuse_ino_t ino, size_t size, off_t off, struct fuse_file_info *ffi);

Read the contents of file ino at offset off.

On success, respond with fuse_reply_buf(3).

readdir(fuse_req_t req, fuse_ino_t ino, size_t size, off_t off, struct fuse_file_info *ffi);

Called to read the entries in a directory specified by ino. The file system implementation must use the fuse_add_direntry() function to add each entry to a buffer. The buffer must be large enough to hold the entry but no larger than size. If the remaining space in the buffer is too small, the entry won't be written, but the required size will still be returned. To check for success, compare the buffer size (bufsize) with the returned entry size. If the entry size is greater than the buffer size, the operation failed. The size required can be determined by calling fuse_add_direntry() with buf set to NULL.

On success, respond with fuse_reply_buf(3).

readlink(fuse_req_t req, fuse_ino_t ino);

Called to read the target of a symbolic link. The target must be NUL-terminated.

On success, respond with fuse_reply_readlink(3).

release(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *ffi);

Called when there are no more references to the file specified by ino.

releasedir(fuse_req_t req, fuse_ino_t ino, struct fuse_file_info *ffi);

Called when there are no more references to the directory specified by ino.

rename(fuse_req_t req, fuse_ino_t parent, const char *name, fuse_ino_t newparent, const char *newname);

Rename the directory entry name to newname. newparent specifies the inode of the new parent directory.

rmdir(fuse_req_t req, fuse_ino_t parent, const char *name);

Delete directory name from directory parent.

symlink(fuse_req_t req, const char *target, fuse_ino_t parent, const char *name);

Create a symbolic link in parent pointing from name to the absolute or relative path target.

On success, respond with fuse_reply_entry(3).

setattr(fuse_req_t req, fuse_ino_t ino, struct stat *attr, int flags, struct fuse_file_info *ffi);

Called when file attributes are changed such as access permissions or the file owner or group via chown(2) and chmod(2) system calls.

The flags argument is the bitwise OR of one or more of the bitmasks from the following list, requesting that the corresponding fields in attr be set on ino:

FUSE_SET_ATTR_MODE
FUSE_SET_ATTR_UID
FUSE_SET_ATTR_GID
FUSE_SET_ATTR_SIZE
FUSE_SET_ATTR_ATIME
FUSE_SET_ATTR_MTIME
FUSE_SET_ATTR_ATIME_NOW
FUSE_SET_ATTR_MTIME_NOW

On success, return the updated attributes with fuse_reply_attr(3).

statfs(fuse_req_t req, fuse_ino_t ino);

Provide file system information.

On success, respond with fuse_reply_statfs(3).

unlink(fuse_req_t req, fuse_ino_t ino, const char *name);

Delete file name from directory parent.

write(fuse_req_t req, fuse_ino_t ino, char char *buf, size_t size, off_t off, struct fuse_file_info *ffi);

Write size bytes from buf to file ino at offset off.

On success, respond with fuse_reply_write(3).

fuse_session_destroy() destroys the FUSE session se, freeing all associated resources. This should be called after the session loop completes and the file system has been unmounted.

fuse_add_direntry() formats a single directory entry and appends it to a buffer suitable for returning to the kernel. buf points to the location in the buffer where the new dirent should be added and bufsize specifies the remaining size of the buffer. name is a NUL-terminated string for the name of the new entry. Only the st_ino field and bits 12-15 of the st_mode field from the stbuf argument are used. All other fields are ignored. off is a file system specific offset of the next entry.

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUES

SEE ALSO

STANDARDS

HISTORY

AUTHORS