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