1.\" $NetBSD: fsetown.9,v 1.6 2005/12/20 19:53:15 rpaulo Exp $ 2.\" 3.\" Copyright (c) 2003 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jaromir Dolecek. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd December 20, 2005 38.Dt FSETOWN 9 39.Os 40.Sh NAME 41.Nm fsetown , 42.Nm fgetown , 43.Nm fownsignal 44.Nd file descriptor owner handling functions 45.Sh SYNOPSIS 46.In sys/file.h 47.Ft int 48.Fn fsetown "struct lwp *l" "pid_t *pgid" "int cmd" "const void *data" 49.Ft int 50.Fn fgetown "struct lwp *l" "pid_t pgid" "int cmd" "void *data" 51.Ft void 52.Fn fownsignal "pid_t pgid" "int signo" "int code" "int band" "void *fdescdata" 53.Sh DESCRIPTION 54These functions handle file descriptor owner related ioctls and 55related signal delivery. 56Device drivers and other parts of the kernel call these functions from 57ioctl entry functions or I/O notification functions. 58.Pp 59.Fn fsetown 60sets the owner of file. 61.Fa cmd 62is an ioctl command, one of 63.Dv SIOCSPGRP , 64.Dv FIOSETOWN , 65and 66.Dv TIOCSPGRP . 67.Fa data 68is interpreted as a pointer to a signed integer, the integer being 69the ID of the owner. 70The 71.Fa cmd 72determines how exactly 73.Fa data 74should be interpreted. 75If 76.Fa cmd 77is 78.Dv TIOCSPGRP , 79the ID needs to be positive and is interpreted as process group ID. 80For 81.Dv SIOCSPGRP 82and 83.Dv FIOSETOWN , 84the passed ID is the process ID if positive, or the process group ID 85if negative. 86.Pp 87.Fn fgetown 88returns the current owner of the file. 89.Fa cmd 90is an ioctl command, one of 91.Dv SIOCGPGRP , 92.Dv FIOGETOWN , 93and 94.Dv TIOCGPGRP . 95.Fa data 96is interpreted as a pointer to a signed integer, 97and the value is set according to the passed 98.Fa cmd . 99For 100.Dv TIOCGPGRP , 101the returned 102.Fa data 103value is positive process group ID if the owner is the process group, 104or negative process ID if the owner is a process. 105For other ioctls, 106the returned value is the positive process ID if the owner is a process, 107or the negative process group ID if the owner is a process group. 108.Pp 109.Fn fownsignal 110schedules the 111.Fa signo 112signal to be sent to the current file descriptor owner. 113The signals typically used with this function are 114.Dv SIGIO 115and 116.Dv SIGURG . 117The 118.Fa code 119and 120.Fa band 121arguments are sent along with the signal as additional signal specific 122information if 123.Dv SA_SIGINFO 124is activated. 125If the information is not available from the context of the 126.Fn fownsignal 127call, these should be passed as zero. 128.Fa fdescdata 129is used to lookup the file descriptor for 130.Sa SA_SIGINFO 131signals. 132If it is specified, the file descriptor number is sent along with 133the signal as additional signal specific information. 134If file descriptor data pointer is not available in the context of the 135.Fn fownsignal 136call, 137.Dv NULL 138should be used instead. 139.Pp 140Note that a 141.Xr fcntl 2 142.Dv F_SETOWN request 143is translated by the kernel to a 144.Dv FIOSETOWN 145ioctl, and 146.Dv F_GETOWN 147is translated to 148.Dv FIOGETOWN . 149This is done transparently by generic code, before the device- or 150subsystem-specific ioctl entry function is called. 151.Sh SEE ALSO 152.Xr fcntl 2 , 153.Xr siginfo 2 , 154.Xr signal 7 , 155.Xr ioctl 9 , 156.Xr signal 9 157.Sh HISTORY 158These kernel functions appeared in 159.Nx 2.0 . 160