share/man/man9/devfs_set_cdevpriv.9

   1 .\" Copyright (c) 2008 Konstantin Belousov
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: head/share/man/man9/devfs_set_cdevpriv.9 291653 2015-12-02 18:27:30Z jhb $
  26 .\"
  27 .Dd May 25, 2021
  28 .Dt DEVFS_SET_CDEVPRIV 9
  29 .Os
  30 .Sh NAME
  31 .Nm devfs_set_cdevpriv ,
  32 .Nm devfs_get_cdevpriv ,
  33 .Nm devfs_clear_cdevpriv
  34 .Nd manage per-open filedescriptor data for devices
  35 .Sh SYNOPSIS
  36 .In sys/devfs.h
  37 .Bd -literal
  38 typedef void d_priv_dtor_t(void *data);
  39 .Ed
  40 .Ft int
  41 .Fn devfs_set_cdevpriv "struct file *fp" "void *priv" "d_priv_dtor_t *dtr"
  42 .Ft int
  43 .Fn devfs_get_cdevpriv "struct file *fp" "void **datap"
  44 .Ft void
  45 .Fn devfs_clear_cdevpriv "struct file *fp"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn devfs_xxx_cdevpriv
  49 family of functions allows the device driver methods to associate some
  50 driver-specific data with each user process
  51 .Xr open 2
  52 of the device special file.
  53 Currently, functioning of these functions is restricted to the context
  54 of the
  55 .Vt dev_ops
  56 switch method calls performed as
  57 .Xr devfs 5
  58 operations in response to system calls that use file descriptors.
  59 .Pp
  60 The
  61 .Fn devfs_set_cdevpriv
  62 function associates a data pointed by
  63 .Fa priv
  64 with the calling context (file descriptor) specified by
  65 .Fa fp .
  66 The data may be retrieved later by
  67 .Fn devfs_get_cdevpriv ,
  68 possibly from another call
  69 performed on this file descriptor.
  70 .Pp
  71 The
  72 .Fn devfs_clear_cdevpriv
  73 function disassociates the previously attached data from the
  74 context specified by
  75 .Fa fp .
  76 At the end of
  77 .Fn devfs_clear_cdevpriv
  78 operation, the previously associated
  79 .Fa dtr
  80 callback is called, with private data supplied its
  81 .Fa data
  82 argument.
  83 The
  84 .Fn devfs_clear_cdevpriv
  85 function will be automatically called upon the
  86 .Xr close 2
  87 of the file descriptor.
  88 .Sh RETURN VALUES
  89 If successful, the functions return 0.
  90 .Pp
  91 The function
  92 .Fn devfs_set_cdevpriv
  93 returns the following values on error:
  94 .Bl -tag -width Er
  95 .It Bq Er ENOENT
  96 The passed
  97 .Fa fp
  98 argument is
  99 .Va NULL .
 100 .It Bq Er EBUSY
 101 The private driver data is already associated with the given
 102 .Fa fp .
 103 .El
 104 .Pp
 105 The function
 106 .Fn devfs_get_cdevpriv
 107 returns the following values on error:
 108 .Bl -tag -width Er
 109 .It Bq Er EBADF
 110 The passed
 111 .Fa fp
 112 argument is
 113 .Va NULL .
 114 .It Bq Er ENOENT
 115 The private driver data was not associated with the given
 116 .Fa fp ,
 117 or
 118 .Fn devfs_clear_cdevpriv
 119 was called.
 120 .El
 121 .Sh SEE ALSO
 122 .Xr close 2 ,
 123 .Xr open 2 ,
 124 .Xr devfs 5
 125 .Sh HISTORY
 126 The
 127 .Fn devfs_xxx_cdevpriv
 128 family of functions first appeared in
 129 .Fx 7.1 ,
 130 and was implemented in
 131 .Dx 3.8 .