CUSE4BSD(3) | Library Functions Manual | CUSE4BSD(3) |
NAME¶
libcuse4bsd
—
Userland character device library
LIBRARY¶
Userland character device library (libcuse4bsd -lcuse4bsd)
SYNOPSIS¶
To load the required kernel module at boot time, place the following line in loader.conf(5):
cuse4bsd_load="YES"
#include <cuse4bsd.h>
DESCRIPTION¶
The libcuse4bsd
library contains functions
to create a character device in userspace. The
libcuse4bsd
library is thread safe.
LIBRARY INITIALISATION / DEINITIALISATION¶
int
cuse_init
(void)
This function initialises libcuse4bsd
. Must be
called at the beginning of the program. This function returns 0 on success
or a negative CUSE_ERR_XXX value on failure. If the cuse4bsd kernel module
is not loaded, CUSE_ERR_NOT_LOADED is returned.
int
cuse_uninit
(void)
Deinitialise libcuse4bsd
. Can be called at the end
of the application. This function returns 0 on success or a negative
CUSE_ERR_XXX value on failure.
UNIT MANAGEMENT¶
int
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
CUSE_ERR_XXX value on failure.
int
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 cuse4bsd include
file. See the CUSE_ID_XXX() macros for more information. This function
returns 0 on success or a negative CUSE_ERR_XXX value on failure.
int
cuse_free_unit_number
(int)
This function frees the given allocated system unit number. This function
returns 0 on success or a negative CUSE_ERR_XXX value on failure.
int
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 CUSE_ERR_XXX value on failure.
LIBRARY USAGE¶
void *
cuse_vmalloc
(int
size) This function allocates 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.
void
cuse_vmfree
(void
*) This function frees memory allocated by cuse_vmalloc(). Note that
the cuse4bsd library will internally not free the memory until the
cuse_uninit() function is called and that the number of uniq allocations is
limited.
unsigned long
cuse_vmoffset
(void
*) This function returns the mmap offset that the client must use to
access the allocated memory.
struct cuse_dev *
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.
void
cuse_dev_destroy
(struct
cuse_dev *) This functions destroys a previously created character
device.
void *
cuse_dev_get_priv0
(struct
cuse_dev *) , void *
cuse_dev_get_priv1
(struct
cuse_dev *) , void
cuse_dev_set_priv0
(struct
cuse_dev *, void *) , void
cuse_dev_set_priv1
(struct
cuse_dev *, void *) These functions are used to
set and get the private data of the given cuse device.
int
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 CUSE_ERR_XXX value on
failure.
void
cuse_dev_set_per_file_handle
(struct
cuse_dev *, void *) , void
*
cuse_dev_get_per_file_handle
(struct
cuse_dev *) 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.
void
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.
int
cuse_copy_out
(const
void *src, void *peer_dst, int
len) , int
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 returns 0 on success or a
negative CUSE_ERR_XXX value on failure.
int
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 CUSE_ERR_XXX value.
struct cuse_dev *
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.
void
cuse_poll_wakeup
(void)
This function will wake up any file pollers.
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_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 };
int
cuse_open_t
(struct
cuse_dev *, int fflags) This functions returns a
CUSE_ERR_XXX value.
int
cuse_close_t
(struct
cuse_dev *, int fflags) This functions returns a
CUSE_ERR_XXX value.
int
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.
int
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.
int
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.
int
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.
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; };
SEE ALSO¶
HISTORY¶
libcuse4bsd
was written by Hans Petter
Selasky .
May 27, 2012 | Debian |