[src/trunk]: src/lib/libc/sys Make the ioctl prototype reflect reality and ex...

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

details:   https://anonhg.NetBSD.org/src/rev/e44660afd44c
branches:  trunk
changeset: 759894:e44660afd44c
user:      christos <christos%NetBSD.org@localhost>
date:      Sun Dec 19 16:54:10 2010 +0000

description:
Make the ioctl prototype reflect reality and explain why. Also mention that
the generic file descriptor manipulation ioctls are superceded by the
equivalent fcntl one.

diffstat:

 lib/libc/sys/ioctl.2 |  79 ++++++++++++++++++++++++++++++++++++++++-----------
 1 files changed, 61 insertions(+), 18 deletions(-)

diffs (140 lines):

diff -r 6d998b73a518 -r e44660afd44c lib/libc/sys/ioctl.2
--- a/lib/libc/sys/ioctl.2      Sun Dec 19 16:25:16 2010 +0000
+++ b/lib/libc/sys/ioctl.2      Sun Dec 19 16:54:10 2010 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: ioctl.2,v 1.21 2010/05/11 16:17:18 mbalmer Exp $
+.\"    $NetBSD: ioctl.2,v 1.22 2010/12/19 16:54:10 christos Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"     @(#)ioctl.2    8.2 (Berkeley) 12/11/93
 .\"
-.Dd May 11, 2010
+.Dd December 19, 2010
 .Dt IOCTL 2
 .Os
 .Sh NAME
@@ -40,7 +40,7 @@
 .Sh SYNOPSIS
 .In sys/ioctl.h
 .Ft int
-.Fn ioctl "int d" "unsigned long request" "void *argp"
+.Fn ioctl "int d" "unsigned long request" "..."
 .Sh DESCRIPTION
 The
 .Fn ioctl
@@ -54,20 +54,26 @@
 .Fa d
 must be an open file descriptor.
 .Pp
-An  ioctl
+An
+.Fn ioctl
 .Fa request
 has encoded in it whether the argument is an
-.Dq in
-parameter
+.Dq in ,
+.Dq out ,
 or
-.Dq out
-parameter, and the size of the argument
-.Fa argp
+.Dq inout
+parameter, and the size of the first varyadic argument
 in bytes.
-Macros and defines used in specifying an ioctl
+Note that there can be only one varyadic argument but cannot be represented as
+a
+.Ft "void *"
+argument in the prototype because this would require a cast to pass integral
+types without warnings.
+Macros and defines used in specifying an
+.Fn ioctl
 .Fa request
-are located in the file
-.Ao Pa sys/ioctl.h Ac .
+are located in the header
+.In sys/ioctl.h .
 .Sh GENERIC IOCTLS
 Some ioctls are applicable to any file descriptor.
 These include:
@@ -76,11 +82,25 @@
 Set close-on-exec flag.
 The file will be closed when
 .Xr exec 3
-is invoked.
+is invoked
+(This is equivalent to
+.Fn fcntl
+.Dv F_SETFD
+.Dv FD_CLOEXEC
+and the
+.Fn fcntl
+form should be preferred).
 .It Dv FIONCLEX
 Clear close-on-exec flag.
 The file will remain open across
-.Xr exec 3 .
+.Xr exec 3 
+(This is equivalent to
+.Fn fcntl
+.Dv F_SETFD
+.Dv 0
+and the
+.Fn fcntl
+form should be preferred).
 .El
 .Pp
 Some generic ioctls are not implemented for all types of file
@@ -115,13 +135,29 @@
 .Xr read 2
 or
 .Xr write 2
-calls return \-1 and set
+calls return
+.Dv \-1
+and set
 .Va errno
 to
 .Er EAGAIN
-immediately when no data is available.
+immediately when no data is available
+(This is equivalent to
+.Fn fcntl
+.Dv F_SETFL
+.Dv O_NONBLOCK
+and the
+.Fn fcntl
+form should be preferred).
 .It Dv FIOASYNC "int"
-Set asynchronous I/O mode if the argument is non-zero.
+Set asynchronous I/O mode if the argument is non-zero
+(This is equivalent to
+.Fn fcntl
+.Dv F_SETFL
+.Dv O_ASYNC
+and the
+.Fn fcntl
+form should be preferred).
 In asynchronous mode, the process or process group specified by
 .Dv FIOSETOWN
 will start receiving
@@ -134,7 +170,14 @@
 .It Dv FIOSETOWN, FIOGETOWN "int"
 Set/get the process or the process group (if negative) that should receive
 .Dv SIGIO
-signals when data is available.
+signals when data is available
+(This is equivalent to
+.Fn fcntl
+.Dv F_SETOWN
+.Ft pid_t 
+and the
+.Ft fcntl
+form should be preferred).
 .El
 .Sh RETURN VALUES
 If an error has occurred, a value of \-1 is returned and