[src/trunk]: src add manpage for fsetown(9), fgetown(9), fownsignal(9)

[jdolecek <jdolecek%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/e9d98b78605e
branches:  trunk
changeset: 552222:e9d98b78605e
user:      jdolecek <jdolecek%NetBSD.org@localhost>
date:      Sun Sep 21 19:35:42 2003 +0000

description:
add manpage for fsetown(9), fgetown(9), fownsignal(9)

diffstat:

 distrib/sets/lists/comp/mi |    8 ++-
 share/man/man9/Makefile    |    5 +-
 share/man/man9/fsetown.9   |  148 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 159 insertions(+), 2 deletions(-)

diffs (207 lines):

diff -r c8dee4b9f5e4 -r e9d98b78605e distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Sun Sep 21 19:33:59 2003 +0000
+++ b/distrib/sets/lists/comp/mi        Sun Sep 21 19:35:42 2003 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.618 2003/09/18 09:16:27 jdolecek Exp $
+#      $NetBSD: mi,v 1.619 2003/09/21 19:35:42 jdolecek Exp $
 ./usr/bin/addr2line            comp-debug-bin
 ./usr/bin/ar                   comp-util-bin
 ./usr/bin/as                   comp-util-bin
@@ -4014,6 +4014,9 @@
 ./usr/share/man/cat9/fork1.0           comp-sys-catman
 ./usr/share/man/cat9/format_bytes.0            comp-sys-catman
 ./usr/share/man/cat9/free.0            comp-sys-catman
+./usr/share/man/cat9/fgetown.0         comp-sys-catman
+./usr/share/man/cat9/fownsignal.0      comp-sys-catman
+./usr/share/man/cat9/fsetown.0         comp-sys-catman
 ./usr/share/man/cat9/fubyte.0          comp-sys-catman
 ./usr/share/man/cat9/fuibyte.0         comp-sys-catman
 ./usr/share/man/cat9/fuiword.0         comp-sys-catman
@@ -7472,6 +7475,9 @@
 ./usr/share/man/man9/fork1.9           comp-sys-man
 ./usr/share/man/man9/format_bytes.9            comp-sys-man
 ./usr/share/man/man9/free.9            comp-sys-man
+./usr/share/man/man9/fgetown.9         comp-sys-man
+./usr/share/man/man9/fownsignal.9      comp-sys-man
+./usr/share/man/man9/fsetown.9         comp-sys-man
 ./usr/share/man/man9/fubyte.9          comp-sys-man
 ./usr/share/man/man9/fuibyte.9         comp-sys-man
 ./usr/share/man/man9/fuiword.9         comp-sys-man
diff -r c8dee4b9f5e4 -r e9d98b78605e share/man/man9/Makefile
--- a/share/man/man9/Makefile   Sun Sep 21 19:33:59 2003 +0000
+++ b/share/man/man9/Makefile   Sun Sep 21 19:35:42 2003 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.145 2003/09/07 21:14:22 seb Exp $
+#       $NetBSD: Makefile,v 1.146 2003/09/21 19:35:46 jdolecek Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -14,6 +14,7 @@
        ctxsw.9 curproc.9 delay.9 disk.9 disklabel.9 dofileread.9 \
        dopowerhooks.9 doshutdownhooks.9 driver.9 ethersubr.9 evcnt.9 \
        extent.9 fetch.9 file.9 filedesc.9 fork1.9 \
+       fsetown.9 \
        hash.9 hardclock.9 humanize_number.9 hz.9 \
        in4_cksum.9 inittodr.9 intro.9 ioasic.9 ioctl.9 ipkdb.9 isa.9 \
        isapnp.9 itimerfix.9 kcopy.9 \
@@ -200,6 +201,8 @@
        filedesc.9 fdremove.9 \
        filedesc.9 fdshare.9 \
        filedesc.9 fdunshare.9
+MLINKS+=fsetown.9 fgetown.9 \
+       fsetown.9 fownsignal.9
 MLINKS+=hash.9 hash32_buf.9 hash.9 hash32_str.9 hash.9 hash32_strn.9
 MLINKS+=humanize_number.9 format_bytes.9
 MLINKS+=in4_cksum.9 in_cksum.9 \
diff -r c8dee4b9f5e4 -r e9d98b78605e share/man/man9/fsetown.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/fsetown.9  Sun Sep 21 19:35:42 2003 +0000
@@ -0,0 +1,148 @@
+.\"     $NetBSD: fsetown.9,v 1.1 2003/09/21 19:35:47 jdolecek Exp $
+.\"
+.\" Copyright (c) 2003 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.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" 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 September 21, 2003
+.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 proc *p" "pid_t *pgid" "int cmd" "const void *data"
+.Ft int
+.Fn fgetown "struct proc *p" "pid_t pgid" "int cmd" "void *data"
+.Ft void
+.Fn fownsignal "pid_t pgid" "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 kernel call these functions from
+ioctl entry functions or I/O notification functions.
+.Pp
+.Fn fsetown
+sets the owner of file.
+.Fa cmd
+is a ioctl command, one of
+.Dv SIOCSPGRP ,
+.Dv FIOSETOWN ,
+.Dv TIOCSPGRP .
+.Fa data
+is interpreted as pointer to signed integer, the integer being ID of owner.
+The
+.Fa cmd
+determines how exactly would
+.Fa data
+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 ,
+passed ID is process ID if positive, or process group ID
+if negative.
+.Pp
+.Fn fgetown
+returns the current owner of file.
+.Fa cmd
+is ioctl command, one of
+.Dv SIOCGPGRP ,
+.Dv FIOGETOWN ,
+.Dv TIOCGPGRP .
+.Fa data
+is interpreted as pointer to signed integer,
+and the value is set according to passed
+.Fa cmd .
+For
+.Dv TIOCGPGRP ,
+the returned
+.Fa data
+value is positive process group ID if owner is process group,
+or negative process ID if the owner is a process.
+For other ioctls,
+returned value is positive process ID if owner is a process,
+or negative process group ID if the owner is a process group.
+.Pp
+.Fn fownsignal
+schedules the
+.Dv SIGIO
+signal to be sent to current file descriptor owner.
+.Fa code
+and
+.Fa band
+is sent along the signal as additional signal specific information,
+if
+.Dv SA_SIGINFO
+is activated. If the information is not available from context
+of
+.Fn fownsignal
+call, these should be passed as zero.
+.Fa fdescdata
+is used to lookup file descriptor for
+.Sa SA_SIGINFO
+signals. If it's specified, the file descriptor number
+is sent along the signal as additional signal
+specific information. If file descriptor data pointer
+is not available in the context of
+.Fn fownsignal
+call,
+.Dv NULL
+should be used instead.
+.Pp
+Note that
+.Xr fcntl 3
+.Dv F_SETOWN request
+is translated by kernel to
+.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 3 ,
+.Xr signal 7 ,
+.Xr ioctl 9 ,
+.Xr signal 9
+.Sh HISTORY
+These kernel functions appeared in
+.Nx 2.0 .