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