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