share/man/man9/fsetown.9

   1 .\"     $NetBSD: fsetown.9,v 1.8 2008/04/30 13:10:58 martin 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
  47 These functions handle file descriptor owner related ioctls and
  48 related signal delivery.
  49 Device drivers and other parts of the kernel call these functions from
  50 ioctl entry functions or I/O notification functions.
  51 .Pp
  52 .Fn fsetown
  53 sets the owner of file.
  54 .Fa cmd
  55 is an ioctl command, one of
  56 .Dv SIOCSPGRP ,
  57 .Dv FIOSETOWN ,
  58 and
  59 .Dv TIOCSPGRP .
  60 .Fa data
  61 is interpreted as a pointer to a signed integer, the integer being
  62 the ID of the owner.
  63 The
  64 .Fa cmd
  65 determines how exactly
  66 .Fa data
  67 should be interpreted.
  68 If
  69 .Fa cmd
  70 is
  71 .Dv TIOCSPGRP ,
  72 the ID needs to be positive and is interpreted as process group ID.
  73 For
  74 .Dv SIOCSPGRP
  75 and
  76 .Dv FIOSETOWN ,
  77 the passed ID is the process ID if positive, or the process group ID
  78 if negative.
  79 .Pp
  80 .Fn fgetown
  81 returns the current owner of the file.
  82 .Fa cmd
  83 is an ioctl command, one of
  84 .Dv SIOCGPGRP ,
  85 .Dv FIOGETOWN ,
  86 and
  87 .Dv TIOCGPGRP .
  88 .Fa data
  89 is interpreted as a pointer to a signed integer,
  90 and the value is set according to the passed
  91 .Fa cmd .
  92 For
  93 .Dv TIOCGPGRP ,
  94 the returned
  95 .Fa data
  96 value is positive process group ID if the owner is the process group,
  97 or negative process ID if the owner is a process.
  98 For other ioctls,
  99 the returned value is the positive process ID if the owner is a process,
 100 or the negative process group ID if the owner is a process group.
 101 .Pp
 102 .Fn fownsignal
 103 schedules the
 104 .Fa signo
 105 signal to be sent to the current file descriptor owner.
 106 The signals typically used with this function are
 107 .Dv SIGIO
 108 and
 109 .Dv SIGURG .
 110 The
 111 .Fa code
 112 and
 113 .Fa band
 114 arguments are sent along with the signal as additional signal specific
 115 information if
 116 .Dv SA_SIGINFO
 117 is activated.
 118 If the information is not available from the context of the
 119 .Fn fownsignal
 120 call, these should be passed as zero.
 121 .Fa fdescdata
 122 is used to lookup the file descriptor for
 123 .Dv SA_SIGINFO
 124 signals.
 125 If it is specified, the file descriptor number is sent along with
 126 the signal as additional signal specific information.
 127 If file descriptor data pointer is not available in the context of the
 128 .Fn fownsignal
 129 call,
 130 .Dv NULL
 131 should be used instead.
 132 .Pp
 133 Note that a
 134 .Xr fcntl 2
 135 .Dv F_SETOWN request
 136 is translated by the kernel to a
 137 .Dv FIOSETOWN
 138 ioctl, and
 139 .Dv F_GETOWN
 140 is translated to
 141 .Dv FIOGETOWN .
 142 This is done transparently by generic code, before the device- or
 143 subsystem-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
 151 These kernel functions appeared in
 152 .Nx 2.0 .