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