Add lowlevel ioctl examples and tests

Examples help to understand what needs to be done for ioctls.

Signed-off-by: Bernd Schubert <bernd@bsbernd.com>
This commit is contained in:
Bernd Schubert
2026-01-02 12:17:24 +01:00
parent 37dac0ee01
commit a32cec008c
5 changed files with 717 additions and 12 deletions
+10 -3
View File
@@ -10,13 +10,20 @@
/** @file
* @tableofcontents
*
* Header file to share definitions between the ioctl.c example file
* system and the ioctl_client.c test program.
* Header file to share definitions between the ioctl example file
* systems (ioctl.c, ioctl_ll.c, cuse.c) and their test programs
* (ioctl_client.c, ioctl_ll_client.c, cuse_client.c).
*
* Restricted ioctls (FIOC_GET_SIZE, FIOC_SET_SIZE):
* Use _IOR/_IOW encoding - kernel handles data transfer automatically.
*
* Unrestricted ioctls (FIOC_READ, FIOC_WRITE):
* Use _IO encoding - require fuse_reply_ioctl_retry() in low-level API.
* Only work with CUSE (fuse kernel restriction).
*
* \include ioctl.h
*/
#include <sys/types.h>
#include <sys/uio.h>
#include <sys/ioctl.h>
+472
View File
@@ -0,0 +1,472 @@
/*
* FUSE fioc_ll: FUSE ioctl example (low-level API)
* Copyright (C) 2008 SUSE Linux Products GmbH
* Copyright (C) 2008 Tejun Heo <teheo@suse.de>
* Copyright (C) 2026 libfuse maintainers
*
* This program can be distributed under the terms of the GNU GPLv2.
* See the file GPL2.txt.
*/
/** @file
* @tableofcontents
*
* This example illustrates how to write a FUSE low-level file system
* that can process ioctls. It demonstrates both:
*
* 1. Restricted ioctls (FIOC_GET_SIZE, FIOC_SET_SIZE) - use _IOR/_IOW
* encoding, kernel handles data transfer automatically
*
* 2. Unrestricted ioctls (FIOC_READ, FIOC_WRITE) - use _IO encoding,
* require fuse_reply_ioctl_retry() to request data from kernel
*
* Note: Unrestricted ioctls only work with CUSE (character devices).
* The kernel blocks fuse_reply_ioctl_retry() for regular FUSE mounts,
* returning -EIO regardless of privileges. This is by design - FUSE is
* for filesystems, CUSE is for character devices with arbitrary ioctls.
*
* Compile with:
*
* gcc -Wall ioctl_ll.c `pkg-config fuse3 --cflags --libs` -o ioctl_ll
*
* ## Source code ##
* \include ioctl_ll.c
*/
#define FUSE_USE_VERSION FUSE_MAKE_VERSION(3, 19)
#include <fuse_lowlevel.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <fcntl.h>
#include <unistd.h>
#include <assert.h>
#include "ioctl.h"
#define FIOC_NAME "fioc"
enum {
FIOC_NONE,
FIOC_ROOT,
FIOC_FILE,
};
static void *fioc_buf;
static size_t fioc_size;
static int fioc_resize(size_t new_size)
{
void *new_buf;
if (new_size == fioc_size)
return 0;
new_buf = realloc(fioc_buf, new_size);
if (!new_buf && new_size)
return -ENOMEM;
if (new_size > fioc_size)
memset((char *)new_buf + fioc_size, 0, new_size - fioc_size);
fioc_buf = new_buf;
fioc_size = new_size;
return 0;
}
static int fioc_expand(size_t new_size)
{
if (new_size > fioc_size)
return fioc_resize(new_size);
return 0;
}
static int fioc_stat(fuse_ino_t ino, struct stat *stbuf)
{
stbuf->st_ino = ino;
stbuf->st_uid = getuid();
stbuf->st_gid = getgid();
switch (ino) {
case 1:
stbuf->st_mode = S_IFDIR | 0755;
stbuf->st_nlink = 2;
break;
case 2:
stbuf->st_mode = S_IFREG | 0644;
stbuf->st_nlink = 1;
stbuf->st_size = fioc_size;
break;
default:
return -1;
}
return 0;
}
static void fioc_ll_init(void *userdata, struct fuse_conn_info *conn)
{
(void)userdata;
(void)conn;
}
static void fioc_ll_getattr(fuse_req_t req, fuse_ino_t ino,
struct fuse_file_info *fi)
{
struct stat stbuf;
(void)fi;
memset(&stbuf, 0, sizeof(stbuf));
if (fioc_stat(ino, &stbuf) == -1)
fuse_reply_err(req, ENOENT);
else
fuse_reply_attr(req, &stbuf, 1.0);
}
static void fioc_ll_lookup(fuse_req_t req, fuse_ino_t parent, const char *name)
{
struct fuse_entry_param ep;
if (parent != 1 || strcmp(name, FIOC_NAME) != 0) {
fuse_reply_err(req, ENOENT);
return;
}
memset(&ep, 0, sizeof(ep));
ep.ino = 2;
ep.attr_timeout = 1.0;
ep.entry_timeout = 1.0;
fioc_stat(ep.ino, &ep.attr);
fuse_reply_entry(req, &ep);
}
struct dirbuf {
char *p;
size_t size;
};
static void dirbuf_add(fuse_req_t req, struct dirbuf *b, const char *name,
fuse_ino_t ino)
{
struct stat stbuf;
size_t oldsize = b->size;
b->size += fuse_add_direntry(req, NULL, 0, name, NULL, 0);
b->p = (char *)realloc(b->p, b->size);
memset(&stbuf, 0, sizeof(stbuf));
stbuf.st_ino = ino;
fuse_add_direntry(req, b->p + oldsize, b->size - oldsize, name, &stbuf,
b->size);
}
#define min(x, y) ((x) < (y) ? (x) : (y))
static int reply_buf_limited(fuse_req_t req, const char *buf, size_t bufsize,
off_t off, size_t maxsize)
{
if (off < bufsize)
return fuse_reply_buf(req, buf + off,
min(bufsize - off, maxsize));
else
return fuse_reply_buf(req, NULL, 0);
}
static void fioc_ll_readdir(fuse_req_t req, fuse_ino_t ino, size_t size,
off_t off, struct fuse_file_info *fi)
{
(void)fi;
if (ino != 1) {
fuse_reply_err(req, ENOTDIR);
return;
}
struct dirbuf b;
memset(&b, 0, sizeof(b));
dirbuf_add(req, &b, ".", 1);
dirbuf_add(req, &b, "..", 1);
dirbuf_add(req, &b, FIOC_NAME, 2);
reply_buf_limited(req, b.p, b.size, off, size);
free(b.p);
}
static void fioc_ll_open(fuse_req_t req, fuse_ino_t ino,
struct fuse_file_info *fi)
{
if (ino != 2) {
fuse_reply_err(req, EISDIR);
return;
}
fuse_reply_open(req, fi);
}
static void fioc_ll_read(fuse_req_t req, fuse_ino_t ino, size_t size,
off_t off, struct fuse_file_info *fi)
{
(void)fi;
assert(ino == 2);
if ((size_t)off >= fioc_size) {
fuse_reply_buf(req, NULL, 0);
return;
}
size_t len = min(fioc_size - off, size);
fuse_reply_buf(req, (char *)fioc_buf + off, len);
}
static void fioc_ll_write(fuse_req_t req, fuse_ino_t ino, const char *buf,
size_t size, off_t off, struct fuse_file_info *fi)
{
(void)fi;
assert(ino == 2);
if (fioc_expand(off + size)) {
fuse_reply_err(req, ENOMEM);
return;
}
memcpy((char *)fioc_buf + off, buf, size);
fuse_reply_write(req, size);
}
/*
* Unrestricted ioctl handler for FIOC_READ and FIOC_WRITE.
* These ioctls use _IO() encoding without size info, so the kernel
* cannot automatically transfer data. We must use fuse_reply_ioctl_retry()
* to tell the kernel what data to fetch/prepare.
*/
static void fioc_do_rw(fuse_req_t req, void *addr, const void *in_buf,
size_t in_bufsz, size_t out_bufsz, int is_read)
{
const struct fioc_rw_arg *arg;
struct iovec in_iov[2], out_iov[3], iov[3];
size_t cur_size;
/* First call: request the fioc_rw_arg structure */
in_iov[0].iov_base = addr;
in_iov[0].iov_len = sizeof(*arg);
if (!in_bufsz) {
fuse_reply_ioctl_retry(req, in_iov, 1, NULL, 0);
return;
}
arg = in_buf;
in_buf = (const char *)in_buf + sizeof(*arg);
in_bufsz -= sizeof(*arg);
/* Prepare output iovecs for prev_size and new_size */
out_iov[0].iov_base = (char *)addr + offsetof(struct fioc_rw_arg, prev_size);
out_iov[0].iov_len = sizeof(arg->prev_size);
out_iov[1].iov_base = (char *)addr + offsetof(struct fioc_rw_arg, new_size);
out_iov[1].iov_len = sizeof(arg->new_size);
/* Prepare client buffer iovec */
if (is_read) {
out_iov[2].iov_base = arg->buf;
out_iov[2].iov_len = arg->size;
if (!out_bufsz) {
fuse_reply_ioctl_retry(req, in_iov, 1, out_iov, 3);
return;
}
} else {
in_iov[1].iov_base = arg->buf;
in_iov[1].iov_len = arg->size;
if (arg->size && !in_bufsz) {
fuse_reply_ioctl_retry(req, in_iov, 2, out_iov, 2);
return;
}
}
/* All data available, perform the operation */
cur_size = fioc_size;
iov[0].iov_base = &cur_size;
iov[0].iov_len = sizeof(cur_size);
iov[1].iov_base = &fioc_size;
iov[1].iov_len = sizeof(fioc_size);
if (is_read) {
size_t off = arg->offset;
size_t sz = arg->size;
if (off >= fioc_size)
off = fioc_size;
if (sz > fioc_size - off)
sz = fioc_size - off;
iov[2].iov_base = (char *)fioc_buf + off;
iov[2].iov_len = sz;
fuse_reply_ioctl_iov(req, sz, iov, 3);
} else {
if (fioc_expand(arg->offset + in_bufsz)) {
fuse_reply_err(req, ENOMEM);
return;
}
memcpy((char *)fioc_buf + arg->offset, in_buf, in_bufsz);
fuse_reply_ioctl_iov(req, in_bufsz, iov, 2);
}
}
/*
* Ioctl handler for low-level API.
*
* Restricted ioctls (FIOC_GET_SIZE, FIOC_SET_SIZE):
* - Use _IOR/_IOW encoding with size information
* - Kernel automatically handles data transfer
* - in_buf contains input data, out_bufsz indicates expected output size
*
* Unrestricted ioctls (FIOC_READ, FIOC_WRITE):
* - Use _IO encoding without size information
* - Require fuse_reply_ioctl_retry() to request data
* - Only work with CUSE or privileged mounts
*/
static void fioc_ll_ioctl(fuse_req_t req, fuse_ino_t ino, unsigned int cmd,
void *arg, struct fuse_file_info *fi,
unsigned int flags, const void *in_buf,
size_t in_bufsz, size_t out_bufsz)
{
(void)fi;
if (ino != 2) {
fuse_reply_err(req, EINVAL);
return;
}
if (flags & FUSE_IOCTL_COMPAT) {
fuse_reply_err(req, ENOSYS);
return;
}
switch (cmd) {
case FIOC_GET_SIZE:
/*
* Restricted ioctl: kernel decoded _IOR and knows we want
* to return sizeof(size_t) bytes. Just reply with the data.
*/
if (!out_bufsz) {
/* Unrestricted path: request output buffer */
struct iovec iov = { arg, sizeof(size_t) };
fuse_reply_ioctl_retry(req, NULL, 0, &iov, 1);
} else {
fuse_reply_ioctl(req, 0, &fioc_size, sizeof(fioc_size));
}
break;
case FIOC_SET_SIZE:
/*
* Restricted ioctl: kernel decoded _IOW and provides
* the input data in in_buf.
*/
if (!in_bufsz) {
/* Unrestricted path: request input data */
struct iovec iov = { arg, sizeof(size_t) };
fuse_reply_ioctl_retry(req, &iov, 1, NULL, 0);
} else {
fioc_resize(*(const size_t *)in_buf);
fuse_reply_ioctl(req, 0, NULL, 0);
}
break;
case FIOC_READ:
/* Unrestricted ioctl: requires retry mechanism */
fioc_do_rw(req, arg, in_buf, in_bufsz, out_bufsz, 1);
break;
case FIOC_WRITE:
/* Unrestricted ioctl: requires retry mechanism */
fioc_do_rw(req, arg, in_buf, in_bufsz, out_bufsz, 0);
break;
default:
fuse_reply_err(req, EINVAL);
}
}
static const struct fuse_lowlevel_ops fioc_ll_oper = {
.init = fioc_ll_init,
.lookup = fioc_ll_lookup,
.getattr = fioc_ll_getattr,
.readdir = fioc_ll_readdir,
.open = fioc_ll_open,
.read = fioc_ll_read,
.write = fioc_ll_write,
.ioctl = fioc_ll_ioctl,
};
int main(int argc, char *argv[])
{
struct fuse_args args = FUSE_ARGS_INIT(argc, argv);
struct fuse_session *se;
struct fuse_cmdline_opts opts;
struct fuse_loop_config *config;
int ret = -1;
if (fuse_parse_cmdline(&args, &opts) != 0)
return 1;
if (opts.show_help) {
printf("usage: %s [options] <mountpoint>\n\n", argv[0]);
fuse_cmdline_help();
fuse_lowlevel_help();
ret = 0;
goto err_out1;
} else if (opts.show_version) {
printf("FUSE library version %s\n", fuse_pkgversion());
fuse_lowlevel_version();
ret = 0;
goto err_out1;
}
if (opts.mountpoint == NULL) {
printf("usage: %s [options] <mountpoint>\n", argv[0]);
printf(" %s --help\n", argv[0]);
ret = 1;
goto err_out1;
}
se = fuse_session_new(&args, &fioc_ll_oper,
sizeof(fioc_ll_oper), NULL);
if (se == NULL)
goto err_out1;
if (fuse_set_signal_handlers(se) != 0)
goto err_out2;
if (fuse_session_mount(se, opts.mountpoint) != 0)
goto err_out3;
fuse_daemonize(opts.foreground);
if (opts.singlethread)
ret = fuse_session_loop(se);
else {
config = fuse_loop_cfg_create();
fuse_loop_cfg_set_clone_fd(config, opts.clone_fd);
fuse_loop_cfg_set_max_threads(config, opts.max_threads);
ret = fuse_session_loop_mt(se, config);
fuse_loop_cfg_destroy(config);
config = NULL;
}
fuse_session_unmount(se);
err_out3:
fuse_remove_signal_handlers(se);
err_out2:
fuse_session_destroy(se);
err_out1:
free(opts.mountpoint);
fuse_opt_free_args(&args);
return ret ? 1 : 0;
}
+176
View File
@@ -0,0 +1,176 @@
/*
* FUSE fioc_ll_client: FUSE ioctl example client for low-level API
* Copyright (C) 2008 SUSE Linux Products GmbH
* Copyright (C) 2008 Tejun Heo <teheo@suse.de>
* Copyright (C) 2024 libfuse maintainers
*
* This program can be distributed under the terms of the GNU GPLv2.
* See the file GPL2.txt.
*/
/** @file
*
* This program tests the ioctl_ll.c example file system.
* It tests both restricted ioctls (FIOC_GET_SIZE, FIOC_SET_SIZE) and
* unrestricted ioctls (FIOC_READ, FIOC_WRITE).
*
* Compile with:
*
* gcc -Wall ioctl_ll_client.c -o ioctl_ll_client
*
* ## Source code ##
* \include ioctl_ll_client.c
*/
#include <sys/types.h>
#include <fcntl.h>
#include <sys/stat.h>
#include <sys/ioctl.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include "ioctl.h"
static const char *usage =
"Usage: ioctl_ll_client <command> <fioc_file> [args]\n"
"\n"
"Commands:\n"
" get_size Get the current size (restricted ioctl)\n"
" set_size <size> Set the size (restricted ioctl)\n"
" read <offset> <size> Read data via ioctl (unrestricted)\n"
" write <offset> <data> Write data via ioctl (unrestricted)\n"
"\n"
"Examples:\n"
" ioctl_ll_client get_size /mnt/fioc\n"
" ioctl_ll_client set_size /mnt/fioc 100\n"
" ioctl_ll_client read /mnt/fioc 0 10\n"
" ioctl_ll_client write /mnt/fioc 0 hello\n"
"\n";
static int do_get_size(int fd)
{
size_t size;
if (ioctl(fd, FIOC_GET_SIZE, &size)) {
perror("ioctl(FIOC_GET_SIZE)");
return 1;
}
printf("%zu\n", size);
return 0;
}
static int do_set_size(int fd, const char *size_str)
{
size_t size = strtoul(size_str, NULL, 0);
if (ioctl(fd, FIOC_SET_SIZE, &size)) {
perror("ioctl(FIOC_SET_SIZE)");
return 1;
}
printf("Size set to %zu\n", size);
return 0;
}
static int do_read(int fd, const char *offset_str, const char *size_str)
{
struct fioc_rw_arg arg;
char *buf;
ssize_t ret;
size_t sz = strtoul(size_str, NULL, 0);
buf = malloc(sz + 1);
if (!buf) {
perror("malloc");
return 1;
}
memset(&arg, 0, sizeof(arg));
arg.offset = strtol(offset_str, NULL, 0);
arg.buf = buf;
arg.size = sz;
ret = ioctl(fd, FIOC_READ, &arg);
if (ret < 0) {
perror("ioctl(FIOC_READ)");
free(buf);
return 1;
}
buf[ret] = '\0';
printf("Read %zd bytes (prev_size=%zu, new_size=%zu): %s\n",
ret, arg.prev_size, arg.new_size, buf);
free(buf);
return 0;
}
static int do_write(int fd, const char *offset_str, const char *data)
{
struct fioc_rw_arg arg;
ssize_t ret;
memset(&arg, 0, sizeof(arg));
arg.offset = strtol(offset_str, NULL, 0);
arg.buf = (void *)data;
arg.size = strlen(data);
ret = ioctl(fd, FIOC_WRITE, &arg);
if (ret < 0) {
perror("ioctl(FIOC_WRITE)");
return 1;
}
printf("Wrote %zd bytes (prev_size=%zu, new_size=%zu)\n",
ret, arg.prev_size, arg.new_size);
return 0;
}
int main(int argc, char **argv)
{
int fd;
int ret = 0;
if (argc < 3) {
fprintf(stderr, "%s", usage);
return 1;
}
fd = open(argv[2], O_RDWR);
if (fd < 0) {
perror("open");
return 1;
}
if (strcmp(argv[1], "get_size") == 0) {
ret = do_get_size(fd);
} else if (strcmp(argv[1], "set_size") == 0) {
if (argc < 4) {
fprintf(stderr, "set_size requires a size argument\n");
ret = 1;
} else {
ret = do_set_size(fd, argv[3]);
}
} else if (strcmp(argv[1], "read") == 0) {
if (argc < 5) {
fprintf(stderr, "read requires offset and size\n");
ret = 1;
} else {
ret = do_read(fd, argv[3], argv[4]);
}
} else if (strcmp(argv[1], "write") == 0) {
if (argc < 5) {
fprintf(stderr, "write requires offset and data\n");
ret = 1;
} else {
ret = do_write(fd, argv[3], argv[4]);
}
} else {
fprintf(stderr, "Unknown command: %s\n", argv[1]);
fprintf(stderr, "%s", usage);
ret = 1;
}
close(fd);
return ret;
}
+2 -2
View File
@@ -1,7 +1,7 @@
examples = [ 'passthrough', 'passthrough_fh',
'hello', 'hello_ll',
'printcap', 'ioctl_client', 'poll_client',
'ioctl', 'cuse', 'cuse_client' ]
'printcap', 'ioctl_client', 'ioctl_ll_client', 'poll_client',
'ioctl', 'ioctl_ll', 'cuse', 'cuse_client' ]
if not platform.endswith('bsd') and platform != 'dragonfly'
examples += [ 'passthrough_ll', 'hello_ll_uds' ]