From 4d653f431856ad42f27352d36b130a9d9eda592a Mon Sep 17 00:00:00 2001
From: christos <christos@NetBSD.org>
Date: Sun, 19 Dec 2010 16:54:10 +0000
Subject: [PATCH] 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.

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

diff --git a/lib/libc/sys/ioctl.2 b/lib/libc/sys/ioctl.2
index 92e07691a2d7..100b258c9a7b 100644
--- a/lib/libc/sys/ioctl.2
+++ b/lib/libc/sys/ioctl.2
@@ -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 @@ The argument
 .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 @@ These include:
 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 @@ In non-blocking mode,
 .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 @@ descriptor.
 .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