CUSE(3)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💅 CUSE(3) — libcuse 💅

From the Library Functions Manual, bestie: this is the whole userland character-device situation, and it’s lowkey iconic.

🌸 NAME 🌸

libcuse — the userland character device library. No cap, that’s the vibe: character devices, but in userspace. 💖

📚 LIBRARY 📚

library “libcuse”

✨ SYNOPSIS ✨

To load the required kernel module at boot time, place the following line in loader.conf(5):

cuse_load="YES"

Then include this header:

#include <cuse.h>

💖 DESCRIPTION 💖

The libcuse library contains functions to create a character device in userspace. It is thread safe. Periodt. 💅

🎀 LIBRARY INITIALISATION / DEINITIALISATION 🎀

  • int cuse_init(void) — initialises libcuse. Must be called at the beginning of the program. Returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes. If the cuse kernel module is not loaded, CUSE_ERR_NOT_LOADED is returned.
  • int cuse_uninit(void) — deinitialises libcuse. Can be called at the end of the application. Returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.

🦋 UNIT MANAGEMENT 🦋

  • int cuse_alloc_unit_number(int *) — stores a unique system unit number at the pointed integer location. Returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.
  • int cuse_alloc_unit_number_by_id(int *, int id) — stores a unique system unit number at the pointed integer location. The returned unit number is unique within the given ID. Valid ID values are defined by the cuse include file. See the CUSE_ID_XXX() macros for more information. Returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.
  • int cuse_free_unit_number(int) — frees the given allocated system unit number. Returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.
  • int cuse_free_unit_number_by_id(int unit, int id) — frees the given allocated system unit number belonging to the given ID. If both the unit and id argument is -1, all allocated units will be freed. Returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.

🌈 LIBRARY USAGE 🌈

  • void * cuse_vmalloc(unsigned size) — allocates size bytes of memory. Only memory allocated by this function can be memory mapped by mmap(2). Returns a valid data pointer on success or NULL on failure. The returned pointer is always aligned to the system page size. The number and size of allocations is limited by the mmap(2) offset having to fit into a 32-bit variable, typically for 32-bit applications.
  • int cuse_is_vmalloc_addr(void *) — returns non-zero if the passed pointer points to a valid and non-freed allocation, as returned by cuse_vmalloc(). Else this function returns zero.
  • void cuse_vmfree(void *) — frees memory allocated by cuse_vmalloc(). This function is NULL safe.
  • unsigned long cuse_vmoffset(void *) — returns the mmap offset the client must use to access the allocated memory. The passed pointer must be aligned to the system page size.
  • struct cuse_dev * cuse_dev_create(const struct cuse_methods *mtod, void *priv0, void *priv1, uid_t, gid_t, int permission, const char *fmt, ...) — creates a new character device according to the given parameters. Returns a valid cuse_dev structure pointer on success or NULL on failure.
The device name can only contain a-z, A-Z, 0-9, dot, / and underscore characters. That’s the rule, bestie. 🙈
  • void cuse_dev_destroy(struct cuse_dev *) — destroys a previously created character device.
  • void * cuse_dev_get_priv0(struct cuse_dev *) — gets private data of the given cuse device.
  • void * cuse_dev_get_priv1(struct cuse_dev *) — gets private data of the given cuse device.
  • void cuse_dev_set_priv0(struct cuse_dev *, void *) — sets private data of the given cuse device.
  • void cuse_dev_set_priv1(struct cuse_dev *, void *) — sets private data of the given cuse device.

These functions are used to set and get the private data of the given cuse device.

  • int cuse_wait_and_process(void) — blocks and does event processing. If parallel I/O is required, multiple threads must be created looping on this function. Returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.
  • void * cuse_dev_get_per_file_handle(struct cuse_dev *) — gets the per-file-open specific handle. Should only be used inside the cuse file operation callbacks.
  • void cuse_dev_set_per_file_handle(struct cuse_dev *, void *) — sets the per-file-open specific handle. Should only be used inside the cuse file operation callbacks.
  • void cuse_set_local(int) — instructs cuse_copy_out() and cuse_copy_in() that the user pointer is local, if the argument passed to it is non-zero. Else the user pointer is assumed to be at the peer application. Should only be used inside the cuse file operation callbacks. The value is reset to zero when the given file operation returns, and does not affect any other file operation callbacks.
  • int cuse_get_local(void) — returns the current local state. See cuse_set_local().
  • int cuse_copy_out(const void *src, void *peer_dst, int len) — transfers data between the local application and the peer application. Must be used when operating on the data pointers passed to the cm_read(), cm_write(), and cm_ioctl() callback functions. Returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.
  • int cuse_copy_in(const void *peer_src, void *dst, int len) — transfers data between the local application and the peer application. Must be used when operating on the data pointers passed to the cm_read(), cm_write(), and cm_ioctl() callback functions. Returns 0 on success or a negative value on failure. See CUSE_ERR_XXX for known error codes.
  • int cuse_got_peer_signal(void) — used to check if a signal has been delivered to the peer application. Should only be used inside the cuse file operation callbacks. Returns 0 if a signal has been delivered to the caller. Else it returns a negative value. See CUSE_ERR_XXX for known error codes.
  • struct cuse_dev * cuse_dev_get_current(int *pcmd) — used to get the current cuse device pointer and the currently executing command, by CUSE_CMD_XXX value. The pcmd argument is allowed to be NULL. Should only be used inside the cuse file operation callbacks. On success a valid cuse device pointer is returned. On failure NULL is returned.
  • void cuse_poll_wakeup(void) — wakes up any file pollers.

⭐ LIBRARY LIMITATIONS ⭐

Transfer lengths for read(), write(), cuse_copy_in(), and cuse_copy_out() should not exceed what can fit into a 32-bit signed integer and is defined by the CUSE_LENGTH_MAX() macro. Transfer lengths for ioctls should not exceed what is defined by the CUSE_BUFFER_MAX() macro.

This is one of those “respect the limits” situations, bestie. Don’t test it. 💀

🔥 LIBRARY CALLBACK METHODS 🔥

In general fflags are defined by CUSE_FFLAG_XXX and errors are defined by CUSE_ERR_XXX.

enum {
  CUSE_ERR_NONE
  CUSE_ERR_BUSY
  CUSE_ERR_WOULDBLOCK
  CUSE_ERR_INVALID
  CUSE_ERR_NO_MEMORY
  CUSE_ERR_FAULT
  CUSE_ERR_SIGNAL
  CUSE_ERR_OTHER
  CUSE_ERR_NOT_LOADED
  CUSE_ERR_NO_DEVICE

  CUSE_POLL_NONE
  CUSE_POLL_READ
  CUSE_POLL_WRITE
  CUSE_POLL_ERROR

  CUSE_FFLAG_NONE
  CUSE_FFLAG_READ
  CUSE_FFLAG_WRITE
  CUSE_FFLAG_NONBLOCK
  CUSE_FFLAG_COMPAT32

  CUSE_CMD_NONE
  CUSE_CMD_OPEN
  CUSE_CMD_CLOSE
  CUSE_CMD_READ
  CUSE_CMD_WRITE
  CUSE_CMD_IOCTL
  CUSE_CMD_POLL
  CUSE_CMD_SIGNAL
  CUSE_CMD_SYNC
  CUSE_CMD_MAX
};
  • int cuse_open_t(struct cuse_dev *, int fflags) — returns a CUSE_ERR_XXX value.
  • int cuse_close_t(struct cuse_dev *, int fflags) — returns a CUSE_ERR_XXX value.
  • int cuse_read_t(struct cuse_dev *, int fflags, void *peer_ptr, int len) — returns a CUSE_ERR_XXX value in case of failure or the actually transferred length in case of success. cuse_copy_in() and cuse_copy_out() must be used to transfer data to and from the peer_ptr.
  • int cuse_write_t(struct cuse_dev *, int fflags, const void *peer_ptr, int len) — returns a CUSE_ERR_XXX value in case of failure or the actually transferred length in case of success. cuse_copy_in() and cuse_copy_out() must be used to transfer data to and from the peer_ptr.
  • int cuse_ioctl_t(struct cuse_dev *, int fflags, unsigned long cmd, void *peer_data) — returns a CUSE_ERR_XXX value in case of failure or zero in case of success. cuse_copy_in() and cuse_copy_out() must be used to transfer data to and from the peer_data.
  • int cuse_poll_t(struct cuse_dev *, int fflags, int events) — returns a mask of CUSE_POLL_XXX values in case of failure and success. The events argument is also a mask of CUSE_POLL_XXX values.
struct cuse_methods {
  cuse_open_t *cm_open;
  cuse_close_t *cm_close;
  cuse_read_t *cm_read;
  cuse_write_t *cm_write;
  cuse_ioctl_t *cm_ioctl;
  cuse_poll_t *cm_poll;
};

👑 HISTORY 👑

libcuse was written by Hans Petter Selasky.

That’s the page, bestie. Source/version: Debian, dated July 18, 2022 — CUSE(3). Slay. 💖✨

📦 where this page comes from