Mdoc cleanup, typo and grammar fixes.
This commit is contained in:
Christian Brueffer
parent
556f150a10
commit
b5112fafbb
@ -25,271 +25,263 @@
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd May 23, 2014
|
||||
.Dd June 6, 2014
|
||||
.Dt CUSE 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm libcuse
|
||||
.
|
||||
.Nd "Userland character device library"
|
||||
.
|
||||
.
|
||||
.Sh LIBRARY
|
||||
.
|
||||
.
|
||||
Userland character device library (libcuse -lcuse)
|
||||
.
|
||||
.
|
||||
.Lb libcuse
|
||||
.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
|
||||
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.
|
||||
.
|
||||
See
|
||||
.Dv CUSE_ERR_XXX
|
||||
for known error codes.
|
||||
If the cuse kernel module is not loaded,
|
||||
.Dv 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.
|
||||
.
|
||||
.
|
||||
See
|
||||
.Dv 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.
|
||||
.
|
||||
See
|
||||
.Dv 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
|
||||
This function stores a unique 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.
|
||||
See the
|
||||
.Fn 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.
|
||||
.
|
||||
See
|
||||
.Dv 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.
|
||||
.
|
||||
See
|
||||
.Dv 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.
|
||||
.
|
||||
.
|
||||
See
|
||||
.Dv 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.
|
||||
.
|
||||
bytes of memory.
|
||||
Only memory allocated by this function can be memory
|
||||
mapped by
|
||||
.Xr mmap 2 .
|
||||
This function returns a valid data pointer on success or
|
||||
.Dv 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()".
|
||||
and non-freed allocation, as returned by
|
||||
.Fn 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
|
||||
This function frees memory allocated by
|
||||
.Fn 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
|
||||
.Fn cuse_uninit
|
||||
function is called and that the number of unique
|
||||
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,
|
||||
parameters.
|
||||
This function returns a valid cuse_dev structure pointer
|
||||
on success or
|
||||
.Dv 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 *"
|
||||
,
|
||||
.Fn "cuse_dev_get_priv0" "struct cuse_dev *" ,
|
||||
.Ft "void *"
|
||||
.Fn "cuse_dev_get_priv1" "struct cuse_dev *"
|
||||
,
|
||||
.Fn "cuse_dev_get_priv1" "struct cuse_dev *" ,
|
||||
.Ft "void"
|
||||
.Fn "cuse_dev_set_priv0" "struct cuse_dev *" "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
|
||||
This function will block and do event processing.
|
||||
If parallel 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.
|
||||
.
|
||||
See
|
||||
.Dv CUSE_ERR_XXX
|
||||
for known error codes.
|
||||
.Pp
|
||||
.
|
||||
.Ft "void *"
|
||||
.Fn "cuse_dev_get_per_file_handle" "struct cuse_dev *"
|
||||
,
|
||||
.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
|
||||
This function instructs
|
||||
.Fn cuse_copy_out
|
||||
and
|
||||
.Fn 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.
|
||||
.
|
||||
Returns the current local state.
|
||||
See
|
||||
.Fn cuse_set_local .
|
||||
.Pp
|
||||
.
|
||||
.Ft "int"
|
||||
.Fn "cuse_copy_out" "const void *src" "void *peer_dst" "int len"
|
||||
,
|
||||
.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.
|
||||
application and the peer application.
|
||||
These functions must be used
|
||||
when operating on the data pointers passed to the
|
||||
.Fn cm_read ,
|
||||
.Fn cm_write ,
|
||||
and
|
||||
.Fn cm_ioctl
|
||||
callback functions.
|
||||
These functions return 0 on success or a negative value on failure.
|
||||
See CUSE_ERR_XXX for known error codes.
|
||||
.
|
||||
See
|
||||
.Dv 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
|
||||
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.
|
||||
.
|
||||
See
|
||||
.Dv 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.
|
||||
.
|
||||
currently executing command, by
|
||||
.Dv CUSE_CMD_XXX
|
||||
value.
|
||||
The
|
||||
.Ar pcmd
|
||||
argument
|
||||
is allowed to be
|
||||
.Dv NULL .
|
||||
This function should only be used inside the
|
||||
cuse file operation callbacks.
|
||||
On success a valid cuse device pointer
|
||||
is returned.
|
||||
On failure
|
||||
.Dv 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
|
||||
Transfer lengths for
|
||||
.Fn read ,
|
||||
.Fn write ,
|
||||
.Fn cuse_copy_in ,
|
||||
and
|
||||
.Fn cuse_copy_out
|
||||
should not exceed what can fit into a 32-bit signed integer and is
|
||||
defined by the CUSE_LENGTH_MAX macro.
|
||||
.
|
||||
defined by the
|
||||
.Fn CUSE_LENGTH_MAX
|
||||
macro.
|
||||
Transfer lengths for ioctls should not exceed what is defined by the
|
||||
CUSE_BUFFER_MAX macro.
|
||||
.
|
||||
.
|
||||
.Fn 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.
|
||||
.
|
||||
In general fflags are defined by
|
||||
.Dv CUSE_FFLAG_XXX
|
||||
and errors are defined by
|
||||
.Dv CUSE_ERR_XXX .
|
||||
.Bd -literal -offset indent
|
||||
enum {
|
||||
CUSE_ERR_NONE
|
||||
@ -324,55 +316,65 @@ enum {
|
||||
CUSE_CMD_MAX
|
||||
};
|
||||
.Ed
|
||||
.
|
||||
.Pp
|
||||
.
|
||||
.Ft "int"
|
||||
.Fn "cuse_open_t" "struct cuse_dev *" "int fflags"
|
||||
This functions returns a CUSE_ERR_XXX value.
|
||||
.
|
||||
This function returns a
|
||||
.Dv CUSE_ERR_XXX
|
||||
value.
|
||||
.Pp
|
||||
.
|
||||
.Ft "int"
|
||||
.Fn "cuse_close_t" "struct cuse_dev *" "int fflags"
|
||||
This functions returns a CUSE_ERR_XXX value.
|
||||
.
|
||||
This function returns a
|
||||
.Dv 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.
|
||||
.
|
||||
This function returns a
|
||||
.Dv CUSE_ERR_XXX
|
||||
value in case of failure or the
|
||||
actually transferred length in case of success.
|
||||
.Fn cuse_copy_in
|
||||
and
|
||||
.Fn cuse_copy_out
|
||||
must be used to transfer data to and from the
|
||||
.Ar 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.
|
||||
.
|
||||
This function returns a
|
||||
.Dv CUSE_ERR_XXX
|
||||
value in case of failure or the
|
||||
actually transferred length in case of success.
|
||||
.Fn cuse_copy_in
|
||||
and
|
||||
.Fn cuse_copy_out
|
||||
must be used to transfer data to and from the
|
||||
.Ar 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.
|
||||
.
|
||||
This function returns a
|
||||
.Dv CUSE_ERR_XXX
|
||||
value in case of failure or zero
|
||||
in case of success.
|
||||
.Fn cuse_copy_in
|
||||
and
|
||||
.Fn cuse_copy_out
|
||||
must be used to
|
||||
transfer data to and from the
|
||||
.Ar 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.
|
||||
.
|
||||
This function returns a mask of
|
||||
.Dv CUSE_POLL_XXX
|
||||
values in case of failure and success.
|
||||
The events argument is also a mask of
|
||||
.Dv CUSE_POLL_XXX
|
||||
values.
|
||||
.Pp
|
||||
.
|
||||
.Bd -literal -offset indent
|
||||
struct cuse_methods {
|
||||
cuse_open_t *cm_open;
|
||||
@ -383,11 +385,6 @@ struct cuse_methods {
|
||||
cuse_poll_t *cm_poll;
|
||||
};
|
||||
.Ed
|
||||
.
|
||||
.
|
||||
.Sh SEE ALSO
|
||||
.
|
||||
.Sh HISTORY
|
||||
.
|
||||
.Nm
|
||||
was written by Hans Petter Selasky .
|
||||
was written by Hans Petter Selasky.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user