Date: Mon, 24 Jun 2002 03:06:57 +0200 (CEST) From: Philipp Mergenthaler <philipp.mergenthaler@stud.uni-karlsruhe.de> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/39748: [PATCH] Some changes to aio_*(2) Message-ID: <200206240106.g5O16vhl003713@i609a.hadiko.de>
next in thread | raw e-mail | index | archive | help
>Number: 39748
>Category: docs
>Synopsis: [PATCH] Some changes to aio_*(2)
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Sun Jun 23 18:10:00 PDT 2002
>Closed-Date:
>Last-Modified:
>Originator: Philipp Mergenthaler
>Release: FreeBSD 5.0-CURRENT i386
>Organization:
University of Karlsruhe, Germany
>Environment:
System: FreeBSD i609a.hadiko.de 5.0-CURRENT FreeBSD 5.0-CURRENT #552: Sun Jun 23 12:49:32 CEST 2002 p@i609a.hadiko.de:/usr/src/sys/i386/compile/I609 i386
>Description:
1)
- aio_read(2) has a DIAGNOSTICS section, which isn't appropriate for
a system call
- aio_read(2) and aio_write(2) lack Xrefs to the other aio_*(2) calls
- all aio_*(2) pages lack an Xref to aio_waitcomplete(2)
- in aio_cancel(2), aio_return(2) and aio_suspend(2), the "SEE ALSO"
section comes before the ERRORS section
2)
The aio_* system calls are only available if the kernel has been
configured with "options VFS_AIO". IMHO, this should be mentioned
in the man pages.
>How-To-Repeat:
>Fix:
The first patch fixes the bugs listed in 1). The second patch adds
a comment to all aio_* man pages about the kernel option. I also
mention LINT/NOTES because of a security-related warning there.
This could perhaps be formulated better :-)
(There isn't a macro which, under RELENG_4 evaluates to "LINT" and,
under -current, evaluates to "NOTES", is there?)
Index: aio_cancel.2
===================================================================
RCS file: /ncvs/src/lib/libc/sys/aio_cancel.2,v
retrieving revision 1.16
diff -u -r1.16 aio_cancel.2
--- aio_cancel.2 1 Oct 2001 16:09:01 -0000 1.16
+++ aio_cancel.2 23 Jun 2002 22:47:15 -0000
@@ -72,12 +72,6 @@
.It Bq Dv AIO_ALLDONE
All of the requests meeting the criteria have finished.
.El
-.Sh SEE ALSO
-.Xr aio_error 2 ,
-.Xr aio_read 2 ,
-.Xr aio_return 2 ,
-.Xr aio_suspend 2 ,
-.Xr aio_write 2
.Sh ERRORS
An error return from
.Fn aio_cancel
@@ -87,6 +81,13 @@
.Fa fildes
is an invalid file descriptor.
.El
+.Sh SEE ALSO
+.Xr aio_error 2 ,
+.Xr aio_read 2 ,
+.Xr aio_return 2 ,
+.Xr aio_suspend 2 ,
+.Xr aio_waitcomplete 2 ,
+.Xr aio_write 2
.Sh STANDARDS
The
.Fn aio_cancel
Index: aio_error.2
===================================================================
RCS file: /ncvs/src/lib/libc/sys/aio_error.2,v
retrieving revision 1.12
diff -u -r1.12 aio_error.2
--- aio_error.2 1 Oct 2001 16:09:01 -0000 1.12
+++ aio_error.2 23 Jun 2002 22:36:52 -0000
@@ -75,6 +75,7 @@
.Xr aio_read 2 ,
.Xr aio_return 2 ,
.Xr aio_suspend 2 ,
+.Xr aio_waitcomplete 2 ,
.Xr aio_write 2 ,
.Xr fsync 2 ,
.Xr read 2 ,
Index: aio_read.2
===================================================================
RCS file: /ncvs/src/lib/libc/sys/aio_read.2,v
retrieving revision 1.11
diff -u -r1.11 aio_read.2
--- aio_read.2 1 Oct 2001 16:09:01 -0000 1.11
+++ aio_read.2 23 Jun 2002 22:48:12 -0000
@@ -105,8 +105,6 @@
no I/O will occur.
.Sh RETURN VALUES
.Rv -std aio_read
-.Sh DIAGNOSTICS
-None.
.Sh ERRORS
The
.Fn aio_read
@@ -179,6 +177,15 @@
.Fa iocb->aio_offset
would be invalid.
.El
+.Sh SEE ALSO
+.Xr aio_cancel 2 ,
+.Xr aio_error 2 ,
+.Xr aio_return 2 ,
+.Xr aio_suspend 2 ,
+.Xr aio_waitcomplete 2 ,
+.Xr aio_write 2 ,
+.Xr fsync 2 ,
+.Xr read 2
.Sh STANDARDS
The
.Fn aio_read
Index: aio_return.2
===================================================================
RCS file: /ncvs/src/lib/libc/sys/aio_return.2,v
retrieving revision 1.11
diff -u -r1.11 aio_return.2
--- aio_return.2 1 Oct 2001 16:09:01 -0000 1.11
+++ aio_return.2 23 Jun 2002 22:35:01 -0000
@@ -63,15 +63,6 @@
and sets
.Dv errno
to indicate the error condition.
-.Sh SEE ALSO
-.Xr aio_cancel 2 ,
-.Xr aio_error 2 ,
-.Xr aio_read 2 ,
-.Xr aio_suspend 2 ,
-.Xr aio_write 2 ,
-.Xr fsync 2 ,
-.Xr read 2 ,
-.Xr write 2
.Sh ERRORS
The
.Fn aio_return
@@ -81,6 +72,16 @@
.Fa iocb
does not reference an outstanding asynchronous I/O request.
.El
+.Sh SEE ALSO
+.Xr aio_cancel 2 ,
+.Xr aio_error 2 ,
+.Xr aio_read 2 ,
+.Xr aio_suspend 2 ,
+.Xr aio_waitcomplete 2 ,
+.Xr aio_write 2 ,
+.Xr fsync 2 ,
+.Xr read 2 ,
+.Xr write 2
.Sh STANDARDS
.Fn aio_return
is expected to conform to the
Index: aio_suspend.2
===================================================================
RCS file: /ncvs/src/lib/libc/sys/aio_suspend.2,v
retrieving revision 1.13
diff -u -r1.13 aio_suspend.2
--- aio_suspend.2 1 Oct 2001 16:09:01 -0000 1.13
+++ aio_suspend.2 23 Jun 2002 22:49:52 -0000
@@ -67,12 +67,6 @@
returns 0. Otherwise it returns -1 and sets
.Va errno
to indicate the error, as enumerated below.
-.Sh SEE ALSO
-.Xr aio_cancel 2 ,
-.Xr aio_error 2 ,
-.Xr aio_read 2 ,
-.Xr aio_suspend 2 ,
-.Xr aio_write 2
.Sh ERRORS
The
.Fn aio_suspend
@@ -91,6 +85,13 @@
.It Bq Er EINTR
the suspend was interrupted by a signal.
.El
+.Sh SEE ALSO
+.Xr aio_cancel 2 ,
+.Xr aio_error 2 ,
+.Xr aio_read 2 ,
+.Xr aio_suspend 2 ,
+.Xr aio_waitcomplete 2 ,
+.Xr aio_write 2
.Sh STANDARDS
.Fn aio_suspend
is expected to conform to the
Index: aio_write.2
===================================================================
RCS file: /ncvs/src/lib/libc/sys/aio_write.2,v
retrieving revision 1.11
diff -u -r1.11 aio_write.2
--- aio_write.2 16 Oct 2001 00:49:19 -0000 1.11
+++ aio_write.2 23 Jun 2002 22:51:55 -0000
@@ -173,6 +173,15 @@
.Fa iocb->aio_offset
would be invalid.
.El
+.Sh SEE ALSO
+.Xr aio_cancel 2 ,
+.Xr aio_error 2 ,
+.Xr aio_read 2 ,
+.Xr aio_return 2 ,
+.Xr aio_suspend 2 ,
+.Xr aio_waitcomplete 2 ,
+.Xr fsync 2 ,
+.Xr write 2
.Sh STANDARDS
.Fn aio_write
is expected to conform to the
diff -ur lib/libc/sys/aio_cancel.2 lib/libc/sys_new/aio_cancel.2
--- lib/libc/sys/aio_cancel.2 Mon Jun 24 02:19:35 2002
+++ lib/libc/sys_new/aio_cancel.2 Mon Jun 24 02:09:06 2002
@@ -49,6 +49,12 @@
Normal asynchronous notification occurs for cancelled requests.
Requests complete with an error result of
.Er ECANCELED .
+.Pp
+Note that you must have
+.Dq options VFS_AIO
+in your kernel configuration file to use this function.
+See also the comment in the LINT or NOTES kernel configuration file,
+respectively.
.Sh RESTRICTIONS
The
.Fn aio_cancel
diff -ur lib/libc/sys/aio_error.2 lib/libc/sys_new/aio_error.2
--- lib/libc/sys/aio_error.2 Mon Jun 24 02:19:35 2002
+++ lib/libc/sys_new/aio_error.2 Mon Jun 24 02:09:06 2002
@@ -42,6 +42,12 @@
function returns the error status of the asynchronous I/O request
associated with the structure pointed to by
.Fa iocb .
+.Pp
+Note that you must have
+.Dq options VFS_AIO
+in your kernel configuration file to use this function.
+See also the comment in the LINT or NOTES kernel configuration file,
+respectively.
.Sh RETURN VALUES
If the asynchronous I/O request has completed successfully,
.Fn aio_error
diff -ur lib/libc/sys/aio_read.2 lib/libc/sys_new/aio_read.2
--- lib/libc/sys/aio_read.2 Mon Jun 24 02:19:35 2002
+++ lib/libc/sys_new/aio_read.2 Mon Jun 24 02:09:06 2002
@@ -79,6 +79,12 @@
.Fa iocb->aio_offset
can be modified during the request as context, so this value must
not be referenced after the request is enqueued.
+.Pp
+Note that you must have
+.Dq options VFS_AIO
+in your kernel configuration file to use this function.
+See also the comment in the LINT or NOTES kernel configuration file,
+respectively.
.Sh RESTRICTIONS
The Asynchronous I/O Control Block structure pointed to by
.Fa iocb
diff -ur lib/libc/sys/aio_return.2 lib/libc/sys_new/aio_return.2
--- lib/libc/sys/aio_return.2 Mon Jun 24 02:19:35 2002
+++ lib/libc/sys_new/aio_return.2 Mon Jun 24 02:09:06 2002
@@ -49,6 +49,12 @@
.Xr aio_error 2
returns something other than
.Er EINPROGRESS .
+.Pp
+Note that you must have
+.Dq options VFS_AIO
+in your kernel configuration file to use this function.
+See also the comment in the LINT or NOTES kernel configuration file,
+respectively.
.Sh RETURN VALUES
If the asynchronous I/O request has completed, the status is returned
as described in
diff -ur lib/libc/sys/aio_suspend.2 lib/libc/sys_new/aio_suspend.2
--- lib/libc/sys/aio_suspend.2 Mon Jun 24 02:19:35 2002
+++ lib/libc/sys_new/aio_suspend.2 Mon Jun 24 02:09:06 2002
@@ -60,6 +60,12 @@
poll, the
.Fa timeout
should point to a zero-value timespec structure.
+.Pp
+Note that you must have
+.Dq options VFS_AIO
+in your kernel configuration file to use this function.
+See also the comment in the LINT or NOTES kernel configuration file,
+respectively.
.Sh RETURN VALUES
If one or more of the specified asynchronous I/O requests have
completed,
diff -ur lib/libc/sys/aio_waitcomplete.2 lib/libc/sys_new/aio_waitcomplete.2
--- lib/libc/sys/aio_waitcomplete.2 Mon Jun 24 02:19:35 2002
+++ lib/libc/sys_new/aio_waitcomplete.2 Mon Jun 24 02:09:06 2002
@@ -70,6 +70,12 @@
.Fn aio_return
should not be called for the control block returned in
.Fa iocbp .
+.Pp
+Note that you must have
+.Dq options VFS_AIO
+in your kernel configuration file to use this function.
+See also the comment in the LINT or NOTES kernel configuration file,
+respectively.
.Sh RETURN VALUES
If an asynchronous I/O request has completed,
.Fa iocbp
diff -ur lib/libc/sys/aio_write.2 lib/libc/sys_new/aio_write.2
--- lib/libc/sys/aio_write.2 Mon Jun 24 02:19:35 2002
+++ lib/libc/sys_new/aio_write.2 Mon Jun 24 02:09:06 2002
@@ -83,6 +83,12 @@
.Fa iocb->aio_offset
can be modified during the request as context, so this value must not
be referenced after the request is enqueued.
+.Pp
+Note that you must have
+.Dq options VFS_AIO
+in your kernel configuration file to use this function.
+See also the comment in the LINT or NOTES kernel configuration file,
+respectively.
.Sh RESTRICTIONS
The Asynchronous I/O Control Block structure pointed to by
.Fa iocb
>Release-Note:
>Audit-Trail:
>Unformatted:
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200206240106.g5O16vhl003713>