From owner-freebsd-doc Sun Jun 23 18:10:27 2002 Delivered-To: freebsd-doc@hub.freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21]) by hub.freebsd.org (Postfix) with ESMTP id 6C24F37B403 for ; Sun, 23 Jun 2002 18:10:01 -0700 (PDT) Received: (from gnats@localhost) by freefall.freebsd.org (8.11.6/8.11.6) id g5O1A1668487; Sun, 23 Jun 2002 18:10:01 -0700 (PDT) (envelope-from gnats) Received: from mailgate.rz.uni-karlsruhe.de (mailgate.rz.uni-karlsruhe.de [129.13.64.97]) by hub.freebsd.org (Postfix) with ESMTP id 5D5DF37B400 for ; Sun, 23 Jun 2002 18:07:02 -0700 (PDT) Received: from nce2.hadiko.de (root@hadince2.hadiko.uni-karlsruhe.de [172.20.32.2]) by mailgate.rz.uni-karlsruhe.de with esmtp (Exim 3.36 #1) id 17MIJp-00079r-00; Mon, 24 Jun 2002 03:07:01 +0200 Received: from i609a.hadiko.de (hadii609a.hadiko.uni-karlsruhe.de [172.20.49.159]) by nce2.hadiko.de (8.12.3/8.12.3/Debian -4) with ESMTP id g5O16w0W003143 (version=TLSv1/SSLv3 cipher=EDH-RSA-DES-CBC3-SHA bits=168 verify=NO) for ; Mon, 24 Jun 2002 03:07:01 +0200 Received: from i609a.hadiko.de (localhost [127.0.0.1]) by i609a.hadiko.de (8.12.4/8.12.4) with ESMTP id g5O16wUF003714 for ; Mon, 24 Jun 2002 03:06:58 +0200 (CEST) (envelope-from p@i609a.hadiko.de) Received: (from p@localhost) by i609a.hadiko.de (8.12.4/8.12.4/Submit) id g5O16vhl003713; Mon, 24 Jun 2002 03:06:57 +0200 (CEST) Message-Id: <200206240106.g5O16vhl003713@i609a.hadiko.de> Date: Mon, 24 Jun 2002 03:06:57 +0200 (CEST) From: Philipp Mergenthaler Reply-To: Philipp Mergenthaler To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Subject: docs/39748: [PATCH] Some changes to aio_*(2) Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org >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