xref: /dflybsd-src/share/man/man9/devfs_set_cdevpriv.9 (revision c470a9c00bc0525f671a380c3660c86dc22080b3)

.\" Copyright (c) 2008 Konstantin Belousov
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: head/share/man/man9/devfs_set_cdevpriv.9 291653 2015-12-02 18:27:30Z jhb $
.\"
.Dd May 25, 2021
.Dt DEVFS_SET_CDEVPRIV 9
.Os
.Sh NAME
.Nm devfs_set_cdevpriv ,
.Nm devfs_get_cdevpriv ,
.Nm devfs_clear_cdevpriv
.Nd manage per-open filedescriptor data for devices
.Sh SYNOPSIS
.In sys/devfs.h
.Bd -literal
typedef	void d_priv_dtor_t(void *data);
.Ed
.Ft int
.Fn devfs_set_cdevpriv "struct file *fp" "void *priv" "d_priv_dtor_t *dtr"
.Ft int
.Fn devfs_get_cdevpriv "struct file *fp" "void **datap"
.Ft void
.Fn devfs_clear_cdevpriv "struct file *fp"
.Sh DESCRIPTION
The
.Fn devfs_xxx_cdevpriv
family of functions allows the device driver methods to associate some
driver-specific data with each user process
.Xr open 2
of the device special file.
Currently, functioning of these functions is restricted to the context
of the
.Vt dev_ops
switch method calls performed as
.Xr devfs 5
operations in response to system calls that use file descriptors.
.Pp
The
.Fn devfs_set_cdevpriv
function associates a data pointed by
.Fa priv
with the calling context (file descriptor) specified by
.Fa fp .
The data may be retrieved later by
.Fn devfs_get_cdevpriv ,
possibly from another call
performed on this file descriptor.
.Pp
The
.Fn devfs_clear_cdevpriv
function disassociates the previously attached data from the
context specified by
.Fa fp .
At the end of
.Fn devfs_clear_cdevpriv
operation, the previously associated
.Fa dtr
callback is called, with private data supplied its
.Fa data
argument.
The
.Fn devfs_clear_cdevpriv
function will be automatically called upon the
.Xr close 2
of the file descriptor.
.Sh RETURN VALUES
If successful, the functions return 0.
.Pp
The function
.Fn devfs_set_cdevpriv
returns the following values on error:
.Bl -tag -width Er
.It Bq Er ENOENT
The passed
.Fa fp
argument is
.Va NULL .
.It Bq Er EBUSY
The private driver data is already associated with the given
.Fa fp .
.El
.Pp
The function
.Fn devfs_get_cdevpriv
returns the following values on error:
.Bl -tag -width Er
.It Bq Er EBADF
The passed
.Fa fp
argument is
.Va NULL .
.It Bq Er ENOENT
The private driver data was not associated with the given
.Fa fp ,
or
.Fn devfs_clear_cdevpriv
was called.
.El
.Sh SEE ALSO
.Xr close 2 ,
.Xr open 2 ,
.Xr devfs 5
.Sh HISTORY
The
.Fn devfs_xxx_cdevpriv
family of functions first appeared in
.Fx 7.1 ,
and was implemented in
.Dx 3.8 .