The CUSE library is a wrapper for the devfs kernel functionality which is exposed through /dev/cuse . In order to function the CUSE kernel code must either be enabled in the kernel configuration file or loaded separately as a module. Currently none of the committed items are connected to the default builds, except for installing the needed header files. The CUSE code will be connected to the default world and kernel builds in a follow-up commit. The CUSE module was written by Hans Petter Selasky, somewhat inspired by similar functionality found in FUSE. The CUSE library can be used for many purposes. Currently CUSE is used when running Linux kernel drivers in user-space, which need to create a character device node to communicate with its applications. CUSE has full support for almost all devfs functionality found in the kernel: - kevents - read - write - ioctl - poll - open - close - mmap - private per file handle data Requested by several people. Also see "multimedia/cuse4bsd-kmod" in ports.
394 lines
10 KiB
Groff
394 lines
10 KiB
Groff
.\" $FreeBSD$
|
|
.\"
|
|
.\" Copyright (c) 2010-2013 Hans Petter Selasky
|
|
.\"
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd May 23, 2014
|
|
.Dt CUSE 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm libcuse
|
|
.
|
|
.Nd "Userland character device library"
|
|
.
|
|
.
|
|
.Sh LIBRARY
|
|
.
|
|
.
|
|
Userland character device library (libcuse -lcuse)
|
|
.
|
|
.
|
|
.Sh SYNOPSIS
|
|
.
|
|
.Pp
|
|
To load the required kernel module at boot time, place the following line in
|
|
.Xr loader.conf 5 :
|
|
.Bd -literal -offset indent
|
|
cuse_load="YES"
|
|
.Ed
|
|
.
|
|
.Pp
|
|
.
|
|
.In cuse.h
|
|
.
|
|
.
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
library contains functions to create a character device in userspace. The
|
|
.Nm
|
|
library is thread safe.
|
|
.
|
|
.
|
|
.Sh LIBRARY INITIALISATION / DEINITIALISATION
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_init" "void"
|
|
This function initialises
|
|
.Nm .
|
|
Must be called at the beginning of the program.
|
|
This function 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.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_uninit" "void"
|
|
Deinitialise
|
|
.Nm .
|
|
Can be called at the end of the application.
|
|
This function returns 0 on success or a negative value on failure.
|
|
See CUSE_ERR_XXX for known error codes.
|
|
.
|
|
.
|
|
.Sh UNIT MANAGEMENT
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_alloc_unit_number" "int *"
|
|
This function stores a uniq system unit number at the pointed
|
|
integer loation.
|
|
This function returns 0 on success or a negative value on failure.
|
|
See CUSE_ERR_XXX for known error codes.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_alloc_unit_number_by_id" "int *" "int id"
|
|
This function stores a uniq system unit number at the pointed
|
|
integer loation.
|
|
The returned unit number is uniq within the given ID.
|
|
Valid ID values are defined by the cuse include file.
|
|
See the CUSE_ID_XXX() macros for more information.
|
|
This function returns 0 on success or a negative value on failure.
|
|
See CUSE_ERR_XXX for known error codes.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_free_unit_number" "int"
|
|
This function frees the given allocated system unit number.
|
|
This function returns 0 on success or a negative value on failure.
|
|
See CUSE_ERR_XXX for known error codes.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_free_unit_number_by_id" "int unit" "int id"
|
|
This function 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.
|
|
This function returns 0 on success or a negative value on failure.
|
|
See CUSE_ERR_XXX for known error codes.
|
|
.
|
|
.
|
|
.Sh LIBRARY USAGE
|
|
.
|
|
.
|
|
.Ft "void *"
|
|
.Fn "cuse_vmalloc" "int size"
|
|
This function allocates
|
|
.Ar size
|
|
bytes of memory. Only memory allocated by this function can be memory
|
|
mapped by mmap(). This function returns a valid data pointer on success or
|
|
NULL on failure.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_is_vmalloc_addr" "void *"
|
|
This function 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.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "void"
|
|
.Fn "cuse_vmfree" "void *"
|
|
This function frees memory allocated by cuse_vmalloc(). Note that the
|
|
cuse library will internally not free the memory until the
|
|
cuse_uninit() function is called and that the number of uniq
|
|
allocations is limited.
|
|
.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "unsigned long"
|
|
.Fn "cuse_vmoffset" "void *"
|
|
This function returns the mmap offset that the client must use to
|
|
access the allocated memory.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "struct cuse_dev *"
|
|
.Fn "cuse_dev_create" "const struct cuse_methods *mtod" "void *priv0" "void *priv1" "uid_t" "gid_t" "int permission" "const char *fmt" "..."
|
|
This function creates a new character device according to the given
|
|
parameters. This function 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.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "void"
|
|
.Fn "cuse_dev_destroy" "struct cuse_dev *"
|
|
This functions destroys a previously created character device.
|
|
.
|
|
.Pp
|
|
.
|
|
.
|
|
.Ft "void *"
|
|
.Fn "cuse_dev_get_priv0" "struct cuse_dev *"
|
|
,
|
|
.Ft "void *"
|
|
.Fn "cuse_dev_get_priv1" "struct cuse_dev *"
|
|
,
|
|
.Ft "void"
|
|
.Fn "cuse_dev_set_priv0" "struct cuse_dev *" "void *"
|
|
,
|
|
.Ft "void"
|
|
.Fn "cuse_dev_set_priv1" "struct cuse_dev *" "void *"
|
|
These functions are used to set and get the private data of the given
|
|
cuse device.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_wait_and_process" "void"
|
|
This function will block and do event processing. If parallell I/O is
|
|
required multiple threads must be created looping on this
|
|
function.
|
|
This function returns 0 on success or a negative value on failure.
|
|
See CUSE_ERR_XXX for known error codes.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "void *"
|
|
.Fn "cuse_dev_get_per_file_handle" "struct cuse_dev *"
|
|
,
|
|
.Ft "void"
|
|
.Fn "cuse_dev_set_per_file_handle" "struct cuse_dev *" "void *"
|
|
These functions are used to set and get the per-file-open specific handle
|
|
and should only be used inside the cuse file operation callbacks.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "void"
|
|
.Fn "cuse_set_local" "int"
|
|
This function 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.
|
|
This function 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.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_get_local" "void"
|
|
Return current local state. See "cuse_set_local" function.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_copy_out" "const void *src" "void *peer_dst" "int len"
|
|
,
|
|
.Ft "int"
|
|
.Fn "cuse_copy_in" "const void *peer_src" "void *dst" "int len"
|
|
These functions are used to transfer data between the local
|
|
application and the peer application. These functions must be used
|
|
when operating on the data pointers passed to the cm_read(),
|
|
cm_write() and cm_ioctl() callback functions.
|
|
These functions return 0 on success or a negative value on failure.
|
|
See CUSE_ERR_XXX for known error codes.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_got_peer_signal" "void"
|
|
This function is used to check if a signal has been delivered to the
|
|
peer application and should only be used inside the cuse file
|
|
operation callbacks. This function 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.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "struct cuse_dev *"
|
|
.Fn "cuse_dev_get_current" "int *pcmd"
|
|
This function is 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. This function should only be used inside the
|
|
cuse file operation callbacks. On success a valid cuse device pointer
|
|
is returned. On failure NULL is returned.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "void"
|
|
.Fn "cuse_poll_wakeup" "void"
|
|
This function will wake up any file pollers.
|
|
.
|
|
.Pp
|
|
.
|
|
.Sh 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.
|
|
.
|
|
.
|
|
.Sh LIBRARY CALLBACK METHODS
|
|
.
|
|
In general fflags are defined by CUSE_FFLAG_XXX and errors are defined by CUSE_ERR_XXX.
|
|
.
|
|
.Bd -literal -offset indent
|
|
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_POLL_NONE
|
|
CUSE_POLL_READ
|
|
CUSE_POLL_WRITE
|
|
CUSE_POLL_ERROR
|
|
|
|
CUSE_FFLAG_NONE
|
|
CUSE_FFLAG_READ
|
|
CUSE_FFLAG_WRITE
|
|
CUSE_FFLAG_NONBLOCK
|
|
|
|
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
|
|
};
|
|
.Ed
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_open_t" "struct cuse_dev *" "int fflags"
|
|
This functions returns a CUSE_ERR_XXX value.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_close_t" "struct cuse_dev *" "int fflags"
|
|
This functions returns a CUSE_ERR_XXX value.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_read_t" "struct cuse_dev *" "int fflags" "void *peer_ptr" "int len"
|
|
This functions 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.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_write_t" "struct cuse_dev *" "int fflags" "const void *peer_ptr" "int len"
|
|
This functions 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.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_ioctl_t" "struct cuse_dev *" "int fflags" "unsigned long cmd" "void *peer_data"
|
|
This functions 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.
|
|
.
|
|
.Pp
|
|
.
|
|
.Ft "int"
|
|
.Fn "cuse_poll_t" "struct cuse_dev *" "int fflags" "int events"
|
|
This functions 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.
|
|
.
|
|
.Pp
|
|
.
|
|
.Bd -literal -offset indent
|
|
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;
|
|
};
|
|
.Ed
|
|
.
|
|
.
|
|
.Sh SEE ALSO
|
|
.
|
|
.Sh HISTORY
|
|
.
|
|
.Nm
|
|
was written by Hans Petter Selasky .
|