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
38typedef	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
47The
48.Fn devfs_xxx_cdevpriv
49family of functions allows the device driver methods to associate some
50driver-specific data with each user process
51.Xr open 2
52of the device special file.
53Currently, functioning of these functions is restricted to the context
54of the
55.Vt dev_ops
56switch method calls performed as
57.Xr devfs 5
58operations in response to system calls that use file descriptors.
59.Pp
60The
61.Fn devfs_set_cdevpriv
62function associates a data pointed by
63.Fa priv
64with the calling context (file descriptor) specified by
65.Fa fp .
66The data may be retrieved later by
67.Fn devfs_get_cdevpriv ,
68possibly from another call
69performed on this file descriptor.
70.Pp
71The
72.Fn devfs_clear_cdevpriv
73function disassociates the previously attached data from the
74context specified by
75.Fa fp .
76At the end of
77.Fn devfs_clear_cdevpriv
78operation, the previously associated
79.Fa dtr
80callback is called, with private data supplied its
81.Fa data
82argument.
83The
84.Fn devfs_clear_cdevpriv
85function will be automatically called upon the
86.Xr close 2
87of the file descriptor.
88.Sh RETURN VALUES
89If successful, the functions return 0.
90.Pp
91The function
92.Fn devfs_set_cdevpriv
93returns the following values on error:
94.Bl -tag -width Er
95.It Bq Er ENOENT
96The passed
97.Fa fp
98argument is
99.Va NULL .
100.It Bq Er EBUSY
101The private driver data is already associated with the given
102.Fa fp .
103.El
104.Pp
105The function
106.Fn devfs_get_cdevpriv
107returns the following values on error:
108.Bl -tag -width Er
109.It Bq Er EBADF
110The passed
111.Fa fp
112argument is
113.Va NULL .
114.It Bq Er ENOENT
115The private driver data was not associated with the given
116.Fa fp ,
117or
118.Fn devfs_clear_cdevpriv
119was called.
120.El
121.Sh SEE ALSO
122.Xr close 2 ,
123.Xr open 2 ,
124.Xr devfs 5
125.Sh HISTORY
126The
127.Fn devfs_xxx_cdevpriv
128family of functions first appeared in
129.Fx 7.1 ,
130and was implemented in
131.Dx 3.8 .
132