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.Dd March 23, 2024 26.Dt DEVFS_CDEVPRIV 9 27.Os 28.Sh NAME 29.Nm devfs_set_cdevpriv , 30.Nm devfs_get_cdevpriv , 31.Nm devfs_clear_cdevpriv , 32.Nm devfs_foreach_cdevpriv 33.Nd manage per-open filedescriptor data for devices 34.Sh SYNOPSIS 35.In sys/param.h 36.In sys/conf.h 37.Bd -literal 38typedef void d_priv_dtor_t(void *data); 39.Ed 40.Ft int 41.Fn devfs_get_cdevpriv "void **datap" 42.Ft int 43.Fn devfs_set_cdevpriv "void *priv" "d_priv_dtor_t *dtr" 44.Ft void 45.Fn devfs_clear_cdevpriv "void" 46.Ft int 47.Fo devfs_foreach_cdevpriv 48.Fa "struct cdev *dev" 49.Fa "int (*cb)(void *data, void *arg)" 50.Fa "void *arg" 51.Fc 52.Sh DESCRIPTION 53The 54.Fn devfs_xxx_cdevpriv 55family of functions allows the 56.Fa cdev 57driver methods to associate some driver-specific data with each 58user process 59.Xr open 2 60of the device special file. 61Currently, functioning of these functions is restricted to the context 62of the 63.Fa cdevsw 64switch method calls performed as 65.Xr devfs 4 66operations in response to system calls that use filedescriptors. 67.Pp 68The 69.Fn devfs_set_cdevpriv 70function associates a data pointed by 71.Va priv 72with current calling context (filedescriptor). 73The data may be retrieved later, possibly from another call 74performed on this filedescriptor, by the 75.Fn devfs_get_cdevpriv 76function. 77The 78.Fn devfs_clear_cdevpriv 79disassociates previously attached data from context. 80Immediately after 81.Fn devfs_clear_cdevpriv 82finished operating, the 83.Va dtr 84callback is called, with private data supplied 85.Va data 86argument. 87The 88.Fn devfs_clear_cdevpriv 89function will be also be called if the open callback 90function returns an error code. 91.Pp 92On the last filedescriptor close, system automatically arranges 93.Fn devfs_clear_cdevpriv 94call. 95.Pp 96If successful, the functions return 0. 97.Pp 98The function 99.Fn devfs_set_cdevpriv 100returns the following values on error: 101.Bl -tag -width Er 102.It Bq Er ENOENT 103The current call is not associated with some filedescriptor. 104.It Bq Er EBUSY 105The private driver data is already associated with current 106filedescriptor. 107.El 108.Pp 109The function 110.Fn devfs_get_cdevpriv 111returns the following values on error: 112.Bl -tag -width Er 113.It Bq Er EBADF 114The current call is not associated with some filedescriptor. 115.It Bq Er ENOENT 116The private driver data was not associated with current 117filedescriptor, or 118.Fn devfs_clear_cdevpriv 119was called. 120.El 121.Pp 122The function 123.Fn devfs_foreach_cdevpriv 124sequentially calls the function 125.Fa cb 126for each 127.Nm cdevpriv 128structure, currently associated with the 129.Fa cdev 130device. 131The iterated 132.Nm cdevpriv 133data pointer and the user-supplied context 134.Fa arg 135are passed to the function 136.Fa cb . 137If 138.Fa cb 139returns non-zero value, the iteration stops on that element. 140The 141.Fn devfs_foreach_cdevpriv 142returns the return value from the last call to 143.Fa cb , 144or zero if no 145.Nm cdevpriv 146data is currently associated with the device. 147.Pp 148Current implementation of the iterator makes it impossible to use 149any blockable locking inside the callback 150.Fa cb . 151.Sh SEE ALSO 152.Xr close 2 , 153.Xr open 2 , 154.Xr devfs 4 155.Sh HISTORY 156The 157.Fn devfs_cdevpriv 158family of functions first appeared in 159.Fx 7.1 . 160