d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Mdoc cleanup, typo and grammar fixes.

Browse Source
This commit is contained in:
Christian Brueffer 2014-06-06 12:06:40 +00:00
parent 556f150a10
commit b5112fafbb
1 changed files with 154 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

311
lib/libcuse/cuse.3
View File

@ -25,271 +25,263 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE. .\" SUCH DAMAGE.
.\" .\"
.Dd May 23, 2014 .Dd June 6, 2014
.Dt CUSE 3 .Dt CUSE 3
.Os .Os
.Sh NAME .Sh NAME
.Nm libcuse .Nm libcuse
.
.Nd "Userland character device library" .Nd "Userland character device library"
.
.
.Sh LIBRARY .Sh LIBRARY
. .Lb libcuse
.
Userland character device library (libcuse -lcuse)
.
.
.Sh SYNOPSIS .Sh SYNOPSIS
.
.Pp
To load the required kernel module at boot time, place the following line in To load the required kernel module at boot time, place the following line in
.Xr loader.conf 5 : .Xr loader.conf 5 :
.Bd -literal -offset indent .Bd -literal -offset indent
cuse_load="YES" cuse_load="YES"
.Ed .Ed
.
.Pp .Pp
.
.In cuse.h .In cuse.h
.
.
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Nm .Nm
library contains functions to create a character device in userspace. The library contains functions to create a character device in userspace.
The
.Nm .Nm
library is thread safe. library is thread safe.
.
.
.Sh LIBRARY INITIALISATION / DEINITIALISATION .Sh LIBRARY INITIALISATION / DEINITIALISATION
.
.Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_init" "void" .Fn "cuse_init" "void"
This function initialises This function initialises
.Nm . .Nm .
Must be called at the beginning of the program. Must be called at the beginning of the program.
This function returns 0 on success or a negative value on failure. This function returns 0 on success or a negative value on failure.
See CUSE_ERR_XXX for known error codes. See
If the cuse kernel module is not loaded, CUSE_ERR_NOT_LOADED is .Dv CUSE_ERR_XXX
returned. for known error codes.
. If the cuse kernel module is not loaded,
.Dv CUSE_ERR_NOT_LOADED
is returned.
.Pp .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_uninit" "void" .Fn "cuse_uninit" "void"
Deinitialise Deinitialise
.Nm . .Nm .
Can be called at the end of the application. Can be called at the end of the application.
This function returns 0 on success or a negative value on failure. 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 .Sh UNIT MANAGEMENT
.
.Ft "int" .Ft "int"
.Fn "cuse_alloc_unit_number" "int *" .Fn "cuse_alloc_unit_number" "int *"
This function stores a uniq system unit number at the pointed This function stores a uniq system unit number at the pointed
integer loation. integer loation.
This function returns 0 on success or a negative value on failure. 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 .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_alloc_unit_number_by_id" "int *" "int id" .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. integer loation.
The returned unit number is uniq within the given ID. The returned unit number is uniq within the given ID.
Valid ID values are defined by the cuse include file. 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. 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 .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_free_unit_number" "int" .Fn "cuse_free_unit_number" "int"
This function frees the given allocated system unit number. This function frees the given allocated system unit number.
This function returns 0 on success or a negative value on failure. 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 .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_free_unit_number_by_id" "int unit" "int id" .Fn "cuse_free_unit_number_by_id" "int unit" "int id"
This function frees the given allocated system unit number belonging This function frees the given allocated system unit number belonging
to the given ID. to the given ID.
If both the unit and id argument is -1, all allocated units will be freed. 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. 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 .Sh LIBRARY USAGE
.
.
.Ft "void *" .Ft "void *"
.Fn "cuse_vmalloc" "int size" .Fn "cuse_vmalloc" "int size"
This function allocates This function allocates
.Ar size .Ar size
bytes of memory. Only memory allocated by this function can be memory bytes of memory.
mapped by mmap(). This function returns a valid data pointer on success or Only memory allocated by this function can be memory
NULL on failure. mapped by
. .Xr mmap 2 .
This function returns a valid data pointer on success or
.Dv NULL
on failure.
.Pp .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_is_vmalloc_addr" "void *" .Fn "cuse_is_vmalloc_addr" "void *"
This function returns non-zero if the passed pointer points to a valid 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. Else this function returns zero.
.
.Pp .Pp
.
.Ft "void" .Ft "void"
.Fn "cuse_vmfree" "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 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. allocations is limited.
.
.
.Pp .Pp
.
.Ft "unsigned long" .Ft "unsigned long"
.Fn "cuse_vmoffset" "void *" .Fn "cuse_vmoffset" "void *"
This function returns the mmap offset that the client must use to This function returns the mmap offset that the client must use to
access the allocated memory. access the allocated memory.
.
.Pp .Pp
.
.Ft "struct cuse_dev *" .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" "..." .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 This function creates a new character device according to the given
parameters. This function returns a valid cuse_dev structure pointer parameters.
on success or NULL on failure. The device name can only contain a-z, 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. A-Z, 0-9, dot, / and underscore characters.
.
.Pp .Pp
.
.Ft "void" .Ft "void"
.Fn "cuse_dev_destroy" "struct cuse_dev *" .Fn "cuse_dev_destroy" "struct cuse_dev *"
This functions destroys a previously created character device. This functions destroys a previously created character device.
.
.Pp .Pp
.
.
.Ft "void *" .Ft "void *"
.Fn "cuse_dev_get_priv0" "struct cuse_dev *" .Fn "cuse_dev_get_priv0" "struct cuse_dev *" ,
,
.Ft "void *" .Ft "void *"
.Fn "cuse_dev_get_priv1" "struct cuse_dev *" .Fn "cuse_dev_get_priv1" "struct cuse_dev *" ,
,
.Ft "void" .Ft "void"
.Fn "cuse_dev_set_priv0" "struct cuse_dev *" "void *" .Fn "cuse_dev_set_priv0" "struct cuse_dev *" "void *" ,
,
.Ft "void" .Ft "void"
.Fn "cuse_dev_set_priv1" "struct cuse_dev *" "void *" .Fn "cuse_dev_set_priv1" "struct cuse_dev *" "void *"
These functions are used to set and get the private data of the given These functions are used to set and get the private data of the given
cuse device. cuse device.
.
.Pp .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_wait_and_process" "void" .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 required multiple threads must be created looping on this
function. function.
This function returns 0 on success or a negative value on failure. 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 .Pp
.
.Ft "void *" .Ft "void *"
.Fn "cuse_dev_get_per_file_handle" "struct cuse_dev *" .Fn "cuse_dev_get_per_file_handle" "struct cuse_dev *" ,
,
.Ft "void" .Ft "void"
.Fn "cuse_dev_set_per_file_handle" "struct cuse_dev *" "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 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. and should only be used inside the cuse file operation callbacks.
.
.Pp .Pp
.
.Ft "void" .Ft "void"
.Fn "cuse_set_local" "int" .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. 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. Else the user pointer is assumed to be at the peer application.
This function should only be used inside the cuse file operation callbacks. 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 The value is reset to zero when the given file operation returns, and
does not affect any other file operation callbacks. does not affect any other file operation callbacks.
.
.Pp .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_get_local" "void" .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 .Pp
.
.Ft "int" .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" .Ft "int"
.Fn "cuse_copy_in" "const void *peer_src" "void *dst" "int len" .Fn "cuse_copy_in" "const void *peer_src" "void *dst" "int len"
These functions are used to transfer data between the local These functions are used to transfer data between the local
application and the peer application. These functions must be used application and the peer application.
when operating on the data pointers passed to the cm_read(), These functions must be used
cm_write() and cm_ioctl() callback functions. 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. 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 .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_got_peer_signal" "void" .Fn "cuse_got_peer_signal" "void"
This function is used to check if a signal has been delivered to the 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 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. delivered to the caller.
Else it returns a negative value. Else it returns a negative value.
See CUSE_ERR_XXX for known error codes. See
. .Dv CUSE_ERR_XXX
for known error codes.
.Pp .Pp
.
.Ft "struct cuse_dev *" .Ft "struct cuse_dev *"
.Fn "cuse_dev_get_current" "int *pcmd" .Fn "cuse_dev_get_current" "int *pcmd"
This function is used to get the current cuse device pointer and the This function is used to get the current cuse device pointer and the
currently executing command, by CUSE_CMD_XXX value. The pcmd argument currently executing command, by
is allowed to be NULL. This function should only be used inside the .Dv CUSE_CMD_XXX
cuse file operation callbacks. On success a valid cuse device pointer value.
is returned. On failure NULL is returned. 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 .Pp
.
.Ft "void" .Ft "void"
.Fn "cuse_poll_wakeup" "void" .Fn "cuse_poll_wakeup" "void"
This function will wake up any file pollers. This function will wake up any file pollers.
.
.Pp .Pp
.
.Sh LIBRARY LIMITATIONS .Sh LIBRARY LIMITATIONS
. Transfer lengths for
. .Fn read ,
Transfer lengths for read, write, cuse_copy_in and cuse_copy_out .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 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 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 .Sh LIBRARY CALLBACK METHODS
. In general fflags are defined by
In general fflags are defined by CUSE_FFLAG_XXX and errors are defined by CUSE_ERR_XXX. .Dv CUSE_FFLAG_XXX
. and errors are defined by
.Dv CUSE_ERR_XXX .
.Bd -literal -offset indent .Bd -literal -offset indent
enum { enum {
CUSE_ERR_NONE CUSE_ERR_NONE
@ -324,55 +316,65 @@ enum {
CUSE_CMD_MAX CUSE_CMD_MAX
}; };
.Ed .Ed
.
.Pp .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_open_t" "struct cuse_dev *" "int fflags" .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 .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_close_t" "struct cuse_dev *" "int fflags" .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 .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_read_t" "struct cuse_dev *" "int fflags" "void *peer_ptr" "int len" .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 This function returns a
actually transferred length in case of success. cuse_copy_in() and .Dv CUSE_ERR_XXX
cuse_copy_out() must be used to transfer data to and from the value in case of failure or the
peer_ptr. 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 .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_write_t" "struct cuse_dev *" "int fflags" "const void *peer_ptr" "int len" .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 This function returns a
actually transferred length in case of success. cuse_copy_in() and .Dv CUSE_ERR_XXX
cuse_copy_out() must be used to transfer data to and from the value in case of failure or the
peer_ptr. 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 .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_ioctl_t" "struct cuse_dev *" "int fflags" "unsigned long cmd" "void *peer_data" .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 This function returns a
in case of success. cuse_copy_in() and cuse_copy_out() must be used to .Dv CUSE_ERR_XXX
transfer data to and from the peer_data. 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 .Pp
.
.Ft "int" .Ft "int"
.Fn "cuse_poll_t" "struct cuse_dev *" "int fflags" "int events" .Fn "cuse_poll_t" "struct cuse_dev *" "int fflags" "int events"
This functions returns a mask of CUSE_POLL_XXX values in case of This function returns a mask of
failure and success. The events argument is also a mask of .Dv CUSE_POLL_XXX
CUSE_POLL_XXX values. values in case of failure and success.
. The events argument is also a mask of
.Dv CUSE_POLL_XXX
values.
.Pp .Pp
.
.Bd -literal -offset indent .Bd -literal -offset indent
struct cuse_methods { struct cuse_methods {
cuse_open_t *cm_open; cuse_open_t *cm_open;
@ -383,11 +385,6 @@ struct cuse_methods {
cuse_poll_t *cm_poll; cuse_poll_t *cm_poll;
}; };
.Ed .Ed
.
.
.Sh SEE ALSO
.
.Sh HISTORY .Sh HISTORY
.
.Nm .Nm
was written by Hans Petter Selasky . was written by Hans Petter Selasky.