lib/libcuse/cuse.3

   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 .
  40 Userland character device library (libcuse -lcuse)
  41 .
  42 .
  43 .Sh SYNOPSIS
  44 .
  45 .Pp
  46 To load the required kernel module at boot time, place the following line in
  47 .Xr loader.conf 5 :
  48 .Bd -literal -offset indent
  49 cuse_load="YES"
  50 .Ed
  51 .
  52 .Pp
  53 .
  54 .In cuse.h
  55 .
  56 .
  57 .Sh DESCRIPTION
  58 The
  59 .Nm
  60 library contains functions to create a character device in userspace. The
  61 .Nm
  62 library is thread safe.
  63 .
  64 .
  65 .Sh LIBRARY INITIALISATION / DEINITIALISATION
  66 .
  67 .Pp
  68 .
  69 .Ft "int"
  70 .Fn "cuse_init" "void"
  71 This function initialises
  72 .Nm .
  73 Must be called at the beginning of the program.
  74 This function returns 0 on success or a negative value on failure.
  75 See CUSE_ERR_XXX for known error codes.
  76 If the cuse kernel module is not loaded, CUSE_ERR_NOT_LOADED is
  77 returned.
  78 .
  79 .Pp
  80 .
  81 .Ft "int"
  82 .Fn "cuse_uninit" "void"
  83 Deinitialise
  84 .Nm .
  85 Can be called at the end of the application.
  86 This function returns 0 on success or a negative value on failure.
  87 See CUSE_ERR_XXX for known error codes.
  88 .
  89 .
  90 .Sh UNIT MANAGEMENT
  91 .
  92 .Ft "int"
  93 .Fn "cuse_alloc_unit_number" "int *"
  94 This function stores a uniq system unit number at the pointed
  95 integer loation.
  96 This function returns 0 on success or a negative value on failure.
  97 See 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"
 103 This function stores a uniq system unit number at the pointed
 104 integer loation.
 105 The returned unit number is uniq within the given ID.
 106 Valid ID values are defined by the cuse include file.
 107 See the CUSE_ID_XXX() macros for more information.
 108 This function returns 0 on success or a negative value on failure.
 109 See CUSE_ERR_XXX for known error codes.
 110 .
 111 .Pp
 112 .
 113 .Ft "int"
 114 .Fn "cuse_free_unit_number" "int"
 115 This function frees the given allocated system unit number.
 116 This function returns 0 on success or a negative value on failure.
 117 See 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"
 123 This function frees the given allocated system unit number belonging
 124 to the given ID.
 125 If both the unit and id argument is -1, all allocated units will be freed.
 126 This function returns 0 on success or a negative value on failure.
 127 See CUSE_ERR_XXX for known error codes.
 128 .
 129 .
 130 .Sh LIBRARY USAGE
 131 .
 132 .
 133 .Ft "void *"
 134 .Fn "cuse_vmalloc" "int size"
 135 This function allocates
 136 .Ar size
 137 bytes of memory. Only memory allocated by this function can be memory
 138 mapped by mmap(). This function returns a valid data pointer on success or
 139 NULL on failure.
 140 .
 141 .Pp
 142 .
 143 .Ft "int"
 144 .Fn "cuse_is_vmalloc_addr" "void *"
 145 This function returns non-zero if the passed pointer points to a valid
 146 and non-freed allocation, as returned by "cuse_vmalloc()".
 147 Else this function returns zero.
 148 .
 149 .Pp
 150 .
 151 .Ft "void"
 152 .Fn "cuse_vmfree" "void *"
 153 This function frees memory allocated by cuse_vmalloc(). Note that the
 154 cuse library will internally not free the memory until the
 155 cuse_uninit() function is called and that the number of uniq
 156 allocations is limited.
 157 .
 158 .
 159 .Pp
 160 .
 161 .Ft "unsigned long"
 162 .Fn "cuse_vmoffset" "void *"
 163 This function returns the mmap offset that the client must use to
 164 access 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" "..."
 170 This function creates a new character device according to the given
 171 parameters. This function returns a valid cuse_dev structure pointer
 172 on success or NULL on failure. The device name can only contain a-z,
 173 A-Z, 0-9, dot, / and underscore characters.
 174 .
 175 .Pp
 176 .
 177 .Ft "void"
 178 .Fn "cuse_dev_destroy" "struct cuse_dev *"
 179 This 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 *"
 195 These functions are used to set and get the private data of the given
 196 cuse device.
 197 .
 198 .Pp
 199 .
 200 .Ft "int"
 201 .Fn "cuse_wait_and_process" "void"
 202 This function will block and do event processing. If parallell I/O is
 203 required multiple threads must be created looping on this
 204 function.
 205 This function returns 0 on success or a negative value on failure.
 206 See 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 *"
 215 These functions are used to set and get the per-file-open specific handle
 216 and should only be used inside the cuse file operation callbacks.
 217 .
 218 .Pp
 219 .
 220 .Ft "void"
 221 .Fn "cuse_set_local" "int"
 222 This function instructs cuse_copy_out() and cuse_copy_in() that the
 223 user pointer is local, if the argument passed to it is non-zero.
 224 Else the user pointer is assumed to be at the peer application.
 225 This function should only be used inside the cuse file operation callbacks.
 226 The value is reset to zero when the given file operation returns, and
 227 does not affect any other file operation callbacks.
 228 .
 229 .Pp
 230 .
 231 .Ft "int"
 232 .Fn "cuse_get_local" "void"
 233 Return 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"
 242 These functions are used to transfer data between the local
 243 application and the peer application. These functions must be used
 244 when operating on the data pointers passed to the cm_read(),
 245 cm_write() and cm_ioctl() callback functions.
 246 These functions return 0 on success or a negative value on failure.
 247 See CUSE_ERR_XXX for known error codes.
 248 .
 249 .Pp
 250 .
 251 .Ft "int"
 252 .Fn "cuse_got_peer_signal" "void"
 253 This function is used to check if a signal has been delivered to the
 254 peer application and should only be used inside the cuse file
 255 operation callbacks. This function returns 0 if a signal has been
 256 delivered to the caller.
 257 Else it returns a negative value.
 258 See CUSE_ERR_XXX for known error codes.
 259 .
 260 .Pp
 261 .
 262 .Ft "struct cuse_dev *"
 263 .Fn "cuse_dev_get_current" "int *pcmd"
 264 This function is used to get the current cuse device pointer and the
 265 currently executing command, by CUSE_CMD_XXX value. The pcmd argument
 266 is allowed to be NULL. This function should only be used inside the
 267 cuse file operation callbacks. On success a valid cuse device pointer
 268 is returned. On failure NULL is returned.
 269 .
 270 .Pp
 271 .
 272 .Ft "void"
 273 .Fn "cuse_poll_wakeup" "void"
 274 This function will wake up any file pollers.
 275 .
 276 .Pp
 277 .
 278 .Sh LIBRARY LIMITATIONS
 279 .
 280 .
 281 Transfer lengths for read, write, cuse_copy_in and cuse_copy_out
 282 should not exceed what can fit into a 32-bit signed integer and is
 283 defined by the CUSE_LENGTH_MAX macro.
 284 .
 285 Transfer lengths for ioctls should not exceed what is defined by the
 286 CUSE_BUFFER_MAX macro.
 287 .
 288 .
 289 .Sh LIBRARY CALLBACK METHODS
 290 .
 291 In general fflags are defined by CUSE_FFLAG_XXX and errors are defined by CUSE_ERR_XXX.
 292 .
 293 .Bd -literal -offset indent
 294 enum {
 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"
 332 This functions returns a CUSE_ERR_XXX value.
 333 .
 334 .Pp
 335 .
 336 .Ft "int"
 337 .Fn "cuse_close_t" "struct cuse_dev *" "int fflags"
 338 This 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"
 344 This functions returns a CUSE_ERR_XXX value in case of failure or the
 345 actually transferred length in case of success. cuse_copy_in() and
 346 cuse_copy_out() must be used to transfer data to and from the
 347 peer_ptr.
 348 .
 349 .Pp
 350 .
 351 .Ft "int"
 352 .Fn "cuse_write_t" "struct cuse_dev *" "int fflags" "const void *peer_ptr" "int len"
 353 This functions returns a CUSE_ERR_XXX value in case of failure or the
 354 actually transferred length in case of success. cuse_copy_in() and
 355 cuse_copy_out() must be used to transfer data to and from the
 356 peer_ptr.
 357 .
 358 .Pp
 359 .
 360 .Ft "int"
 361 .Fn "cuse_ioctl_t" "struct cuse_dev *" "int fflags" "unsigned long cmd" "void *peer_data"
 362 This functions returns a CUSE_ERR_XXX value in case of failure or zero
 363 in case of success. cuse_copy_in() and cuse_copy_out() must be used to
 364 transfer 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"
 370 This functions returns a mask of CUSE_POLL_XXX values in case of
 371 failure and success. The events argument is also a mask of
 372 CUSE_POLL_XXX values.
 373 .
 374 .Pp
 375 .
 376 .Bd -literal -offset indent
 377 struct 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
 393 was written by Hans Petter Selasky .