Module Name: src
Committed By: christos
Date: Sun Dec 19 16:54:10 UTC 2010
Modified Files:
src/lib/libc/sys: ioctl.2
Log Message:
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.
To generate a diff of this commit:
cvs rdiff -u -r1.21 -r1.22 src/lib/libc/sys/ioctl.2
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/sys/ioctl.2
diff -u src/lib/libc/sys/ioctl.2:1.21 src/lib/libc/sys/ioctl.2:1.22
--- src/lib/libc/sys/ioctl.2:1.21 Tue May 11 12:17:18 2010
+++ src/lib/libc/sys/ioctl.2 Sun Dec 19 11:54:10 2010
@@ -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
