1.\" $FreeBSD$ 2.\" 3.\" Copyright (c) 2010-2013 Hans Petter Selasky 4.\" 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd April 17, 2019 29.Dt CUSE 3 30.Os 31.Sh NAME 32.Nm libcuse 33.Nd "Userland character device library" 34.Sh LIBRARY 35.Lb libcuse 36.Sh SYNOPSIS 37To load the required kernel module at boot time, place the following line in 38.Xr loader.conf 5 : 39.Bd -literal -offset indent 40cuse_load="YES" 41.Ed 42.Pp 43.In cuse.h 44.Sh DESCRIPTION 45The 46.Nm 47library contains functions to create a character device in userspace. 48The 49.Nm 50library is thread safe. 51.Sh LIBRARY INITIALISATION / DEINITIALISATION 52.Ft "int" 53.Fn "cuse_init" "void" 54This function initialises 55.Nm . 56Must be called at the beginning of the program. 57This function returns 0 on success or a negative value on failure. 58See 59.Dv CUSE_ERR_XXX 60for known error codes. 61If the cuse kernel module is not loaded, 62.Dv CUSE_ERR_NOT_LOADED 63is returned. 64.Pp 65.Ft "int" 66.Fn "cuse_uninit" "void" 67Deinitialise 68.Nm . 69Can be called at the end of the application. 70This function returns 0 on success or a negative value on failure. 71See 72.Dv CUSE_ERR_XXX 73for known error codes. 74.Sh UNIT MANAGEMENT 75.Ft "int" 76.Fn "cuse_alloc_unit_number" "int *" 77This function stores a uniq system unit number at the pointed 78integer loation. 79This function returns 0 on success or a negative value on failure. 80See 81.Dv CUSE_ERR_XXX 82for known error codes. 83.Pp 84.Ft "int" 85.Fn "cuse_alloc_unit_number_by_id" "int *" "int id" 86This function stores a unique system unit number at the pointed 87integer loation. 88The returned unit number is uniq within the given ID. 89Valid ID values are defined by the cuse include file. 90See the 91.Fn CUSE_ID_XXX 92macros for more information. 93This function returns 0 on success or a negative value on failure. 94See 95.Dv CUSE_ERR_XXX 96for known error codes. 97.Pp 98.Ft "int" 99.Fn "cuse_free_unit_number" "int" 100This function frees the given allocated system unit number. 101This function returns 0 on success or a negative value on failure. 102See 103.Dv CUSE_ERR_XXX 104for known error codes. 105.Pp 106.Ft "int" 107.Fn "cuse_free_unit_number_by_id" "int unit" "int id" 108This function frees the given allocated system unit number belonging 109to the given ID. 110If both the unit and id argument is -1, all allocated units will be freed. 111This function returns 0 on success or a negative value on failure. 112See 113.Dv CUSE_ERR_XXX 114for known error codes. 115.Sh LIBRARY USAGE 116.Ft "void *" 117.Fn "cuse_vmalloc" "int size" 118This function allocates 119.Ar size 120bytes of memory. 121Only memory allocated by this function can be memory 122mapped by 123.Xr mmap 2 . 124This function returns a valid data pointer on success or 125.Dv NULL 126on failure. 127.Pp 128.Ft "int" 129.Fn "cuse_is_vmalloc_addr" "void *" 130This function returns non-zero if the passed pointer points to a valid 131and non-freed allocation, as returned by 132.Fn cuse_vmalloc . 133Else this function returns zero. 134.Pp 135.Ft "void" 136.Fn "cuse_vmfree" "void *" 137This function frees memory allocated by 138.Fn cuse_vmalloc . 139Note that the 140cuse library will internally not free the memory until the 141.Fn cuse_uninit 142function is called and that the number of unique 143allocations is limited. 144.Pp 145.Ft "unsigned long" 146.Fn "cuse_vmoffset" "void *" 147This function returns the mmap offset that the client must use to 148access the allocated memory. 149.Pp 150.Ft "struct cuse_dev *" 151.Fn "cuse_dev_create" "const struct cuse_methods *mtod" "void *priv0" "void *priv1" "uid_t" "gid_t" "int permission" "const char *fmt" "..." 152This function creates a new character device according to the given 153parameters. 154This function returns a valid cuse_dev structure pointer 155on success or 156.Dv NULL 157on failure. 158The device name can only contain a-z, 159A-Z, 0-9, dot, / and underscore characters. 160.Pp 161.Ft "void" 162.Fn "cuse_dev_destroy" "struct cuse_dev *" 163This functions destroys a previously created character device. 164.Pp 165.Ft "void *" 166.Fn "cuse_dev_get_priv0" "struct cuse_dev *" , 167.Ft "void *" 168.Fn "cuse_dev_get_priv1" "struct cuse_dev *" , 169.Ft "void" 170.Fn "cuse_dev_set_priv0" "struct cuse_dev *" "void *" , 171.Ft "void" 172.Fn "cuse_dev_set_priv1" "struct cuse_dev *" "void *" 173These functions are used to set and get the private data of the given 174cuse device. 175.Pp 176.Ft "int" 177.Fn "cuse_wait_and_process" "void" 178This function will block and do event processing. 179If parallel I/O is 180required multiple threads must be created looping on this 181function. 182This function returns 0 on success or a negative value on failure. 183See 184.Dv CUSE_ERR_XXX 185for known error codes. 186.Pp 187.Ft "void *" 188.Fn "cuse_dev_get_per_file_handle" "struct cuse_dev *" , 189.Ft "void" 190.Fn "cuse_dev_set_per_file_handle" "struct cuse_dev *" "void *" 191These functions are used to set and get the per-file-open specific handle 192and should only be used inside the cuse file operation callbacks. 193.Pp 194.Ft "void" 195.Fn "cuse_set_local" "int" 196This function instructs 197.Fn cuse_copy_out 198and 199.Fn cuse_copy_in 200that the 201user pointer is local, if the argument passed to it is non-zero. 202Else the user pointer is assumed to be at the peer application. 203This function should only be used inside the cuse file operation callbacks. 204The value is reset to zero when the given file operation returns, and 205does not affect any other file operation callbacks. 206.Pp 207.Ft "int" 208.Fn "cuse_get_local" "void" 209Returns the current local state. 210See 211.Fn cuse_set_local . 212.Pp 213.Ft "int" 214.Fn "cuse_copy_out" "const void *src" "void *peer_dst" "int len" , 215.Ft "int" 216.Fn "cuse_copy_in" "const void *peer_src" "void *dst" "int len" 217These functions are used to transfer data between the local 218application and the peer application. 219These functions must be used 220when operating on the data pointers passed to the 221.Fn cm_read , 222.Fn cm_write , 223and 224.Fn cm_ioctl 225callback functions. 226These functions return 0 on success or a negative value on failure. 227See 228.Dv CUSE_ERR_XXX 229for known error codes. 230.Pp 231.Ft "int" 232.Fn "cuse_got_peer_signal" "void" 233This function is used to check if a signal has been delivered to the 234peer application and should only be used inside the cuse file 235operation callbacks. 236This function returns 0 if a signal has been 237delivered to the caller. 238Else it returns a negative value. 239See 240.Dv CUSE_ERR_XXX 241for known error codes. 242.Pp 243.Ft "struct cuse_dev *" 244.Fn "cuse_dev_get_current" "int *pcmd" 245This function is used to get the current cuse device pointer and the 246currently executing command, by 247.Dv CUSE_CMD_XXX 248value. 249The 250.Ar pcmd 251argument 252is allowed to be 253.Dv NULL . 254This function should only be used inside the 255cuse file operation callbacks. 256On success a valid cuse device pointer 257is returned. 258On failure 259.Dv NULL 260is returned. 261.Pp 262.Ft "void" 263.Fn "cuse_poll_wakeup" "void" 264This function will wake up any file pollers. 265.Sh LIBRARY LIMITATIONS 266Transfer lengths for 267.Fn read , 268.Fn write , 269.Fn cuse_copy_in , 270and 271.Fn cuse_copy_out 272should not exceed what can fit into a 32-bit signed integer and is 273defined by the 274.Fn CUSE_LENGTH_MAX 275macro. 276Transfer lengths for ioctls should not exceed what is defined by the 277.Fn CUSE_BUFFER_MAX 278macro. 279.Sh LIBRARY CALLBACK METHODS 280In general fflags are defined by 281.Dv CUSE_FFLAG_XXX 282and errors are defined by 283.Dv CUSE_ERR_XXX . 284.Bd -literal -offset indent 285enum { 286 CUSE_ERR_NONE 287 CUSE_ERR_BUSY 288 CUSE_ERR_WOULDBLOCK 289 CUSE_ERR_INVALID 290 CUSE_ERR_NO_MEMORY 291 CUSE_ERR_FAULT 292 CUSE_ERR_SIGNAL 293 CUSE_ERR_OTHER 294 CUSE_ERR_NOT_LOADED 295 CUSE_ERR_NO_DEVICE 296 297 CUSE_POLL_NONE 298 CUSE_POLL_READ 299 CUSE_POLL_WRITE 300 CUSE_POLL_ERROR 301 302 CUSE_FFLAG_NONE 303 CUSE_FFLAG_READ 304 CUSE_FFLAG_WRITE 305 CUSE_FFLAG_NONBLOCK 306 CUSE_FFLAG_COMPAT32 307 308 CUSE_CMD_NONE 309 CUSE_CMD_OPEN 310 CUSE_CMD_CLOSE 311 CUSE_CMD_READ 312 CUSE_CMD_WRITE 313 CUSE_CMD_IOCTL 314 CUSE_CMD_POLL 315 CUSE_CMD_SIGNAL 316 CUSE_CMD_SYNC 317 CUSE_CMD_MAX 318}; 319.Ed 320.Pp 321.Ft "int" 322.Fn "cuse_open_t" "struct cuse_dev *" "int fflags" 323This function returns a 324.Dv CUSE_ERR_XXX 325value. 326.Pp 327.Ft "int" 328.Fn "cuse_close_t" "struct cuse_dev *" "int fflags" 329This function returns a 330.Dv CUSE_ERR_XXX 331value. 332.Pp 333.Ft "int" 334.Fn "cuse_read_t" "struct cuse_dev *" "int fflags" "void *peer_ptr" "int len" 335This function returns a 336.Dv CUSE_ERR_XXX 337value in case of failure or the 338actually transferred length in case of success. 339.Fn cuse_copy_in 340and 341.Fn cuse_copy_out 342must be used to transfer data to and from the 343.Ar peer_ptr . 344.Pp 345.Ft "int" 346.Fn "cuse_write_t" "struct cuse_dev *" "int fflags" "const void *peer_ptr" "int len" 347This function returns a 348.Dv CUSE_ERR_XXX 349value in case of failure or the 350actually transferred length in case of success. 351.Fn cuse_copy_in 352and 353.Fn cuse_copy_out 354must be used to transfer data to and from the 355.Ar peer_ptr . 356.Pp 357.Ft "int" 358.Fn "cuse_ioctl_t" "struct cuse_dev *" "int fflags" "unsigned long cmd" "void *peer_data" 359This function returns a 360.Dv CUSE_ERR_XXX 361value in case of failure or zero 362in case of success. 363.Fn cuse_copy_in 364and 365.Fn cuse_copy_out 366must be used to 367transfer data to and from the 368.Ar peer_data . 369.Pp 370.Ft "int" 371.Fn "cuse_poll_t" "struct cuse_dev *" "int fflags" "int events" 372This function returns a mask of 373.Dv CUSE_POLL_XXX 374values in case of failure and success. 375The events argument is also a mask of 376.Dv CUSE_POLL_XXX 377values. 378.Bd -literal -offset indent 379struct cuse_methods { 380 cuse_open_t *cm_open; 381 cuse_close_t *cm_close; 382 cuse_read_t *cm_read; 383 cuse_write_t *cm_write; 384 cuse_ioctl_t *cm_ioctl; 385 cuse_poll_t *cm_poll; 386}; 387.Ed 388.Sh HISTORY 389.Nm 390was written by Hans Petter Selasky. 391