.\"     $NetBSD: fsetown.9,v 1.9 2009/03/12 12:44:08 joerg Exp $
.\"
.\" Copyright (c) 2003, 2005 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Jaromir Dolecek.
.\"
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.\"
.Dd December 20, 2005
.Dt FSETOWN 9
.Os
.Sh NAME
.Nm fsetown ,
.Nm fgetown ,
.Nm fownsignal
.Nd file descriptor owner handling functions
.Sh SYNOPSIS
.In sys/file.h
.Ft int
.Fn fsetown "struct lwp *l" "pid_t *pgid" "int cmd" "const void *data"
.Ft int
.Fn fgetown "struct lwp *l" "pid_t pgid" "int cmd" "void *data"
.Ft void
.Fn fownsignal "pid_t pgid" "int signo" "int code" "int band" "void *fdescdata"
.Sh DESCRIPTION
These functions handle file descriptor owner related ioctls and
related signal delivery.
Device drivers and other parts of the kernel call these functions from
ioctl entry functions or I/O notification functions.
.Pp
.Fn fsetown
sets the owner of file.
.Fa cmd
is an ioctl command, one of
.Dv SIOCSPGRP ,
.Dv FIOSETOWN ,
and
.Dv TIOCSPGRP .
.Fa data
is interpreted as a pointer to a signed integer, the integer being
the ID of the owner.
The
.Fa cmd
determines how exactly
.Fa data
should be interpreted.
If
.Fa cmd
is
.Dv TIOCSPGRP ,
the ID needs to be positive and is interpreted as process group ID.
For
.Dv SIOCSPGRP
and
.Dv FIOSETOWN ,
the passed ID is the process ID if positive, or the process group ID
if negative.
.Pp
.Fn fgetown
returns the current owner of the file.
.Fa cmd
is an ioctl command, one of
.Dv SIOCGPGRP ,
.Dv FIOGETOWN ,
and
.Dv TIOCGPGRP .
.Fa data
is interpreted as a pointer to a signed integer,
and the value is set according to the passed
.Fa cmd .
For
.Dv TIOCGPGRP ,
the returned
.Fa data
value is positive process group ID if the owner is the process group,
or negative process ID if the owner is a process.
For other ioctls,
the returned value is the positive process ID if the owner is a process,
or the negative process group ID if the owner is a process group.
.Pp
.Fn fownsignal
schedules the
.Fa signo
signal to be sent to the current file descriptor owner.
The signals typically used with this function are
.Dv SIGIO
and
.Dv SIGURG .
The
.Fa code
and
.Fa band
arguments are sent along with the signal as additional signal specific
information if
.Dv SA_SIGINFO
is activated.
If the information is not available from the context of the
.Fn fownsignal
call, these should be passed as zero.
.Fa fdescdata
is used to lookup the file descriptor for
.Dv SA_SIGINFO
signals.
If it is specified, the file descriptor number is sent along with
the signal as additional signal specific information.
If file descriptor data pointer is not available in the context of the
.Fn fownsignal
call,
.Dv NULL
should be used instead.
.Pp
Note that a
.Xr fcntl 2
.Dv F_SETOWN request
is translated by the kernel to a
.Dv FIOSETOWN
ioctl, and
.Dv F_GETOWN
is translated to
.Dv FIOGETOWN .
This is done transparently by generic code, before the device- or
subsystem-specific ioctl entry function is called.
.Sh SEE ALSO
.Xr fcntl 2 ,
.Xr siginfo 2 ,
.Xr signal 7 ,
.Xr ioctl 9 ,
.Xr signal 9
.Sh HISTORY
These kernel functions appeared in
.Nx 2.0 .