From owner-svn-src-all@freebsd.org Mon Aug 22 17:52:12 2016 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 0338FBC27D4; Mon, 22 Aug 2016 17:52:12 +0000 (UTC) (envelope-from jhb@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id CC59D1BCA; Mon, 22 Aug 2016 17:52:11 +0000 (UTC) (envelope-from jhb@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id u7MHqAwR042848; Mon, 22 Aug 2016 17:52:10 GMT (envelope-from jhb@FreeBSD.org) Received: (from jhb@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id u7MHqARe042844; Mon, 22 Aug 2016 17:52:10 GMT (envelope-from jhb@FreeBSD.org) Message-Id: <201608221752.u7MHqARe042844@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: jhb set sender to jhb@FreeBSD.org using -f From: John Baldwin Date: Mon, 22 Aug 2016 17:52:10 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-stable@freebsd.org, svn-src-stable-10@freebsd.org Subject: svn commit: r304617 - in stable: 10/lib/libc/sys 11/lib/libc/sys 9/lib/libc/sys X-SVN-Group: stable-10 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 22 Aug 2016 17:52:12 -0000 Author: jhb Date: Mon Aug 22 17:52:10 2016 New Revision: 304617 URL: https://svnweb.freebsd.org/changeset/base/304617 Log: MFC 304476: Fix various nits in the aio operation manpages. - Avoid double use of "request" in a single sentence. Instead, describe aio_sigevent as being used to request notification of the associated operation's completion. This matches the language used to describe aio_sigevent in aio(4). - Simplify the prohibition on modifying buffers while requests are in flight. - Fix case mismatch. - Drop note about not using stack variables. C programmers should be able to figure out if a stack variable is safe based on the later warning about the life cycle requirements of control blocks. - Remove prohibition on modifying the I/O buffer for aio_fsync() since it does not use an I/O buffer. For aio_mlock(), prohibit modifications to the mapping (e.g. due to mprotect, munmap, mmap, etc.) but do not prohibit modifications to the memory backing the buffer (stores into the pages backing the buffer). Modified: stable/10/lib/libc/sys/aio_fsync.2 stable/10/lib/libc/sys/aio_mlock.2 stable/10/lib/libc/sys/aio_read.2 stable/10/lib/libc/sys/aio_write.2 Directory Properties: stable/10/ (props changed) Changes in other areas also in this revision: Modified: stable/11/lib/libc/sys/aio_fsync.2 stable/11/lib/libc/sys/aio_mlock.2 stable/11/lib/libc/sys/aio_read.2 stable/11/lib/libc/sys/aio_write.2 stable/9/lib/libc/sys/aio_fsync.2 stable/9/lib/libc/sys/aio_read.2 stable/9/lib/libc/sys/aio_write.2 Directory Properties: stable/11/ (props changed) stable/9/lib/libc/ (props changed) stable/9/lib/libc/sys/ (props changed) Modified: stable/10/lib/libc/sys/aio_fsync.2 ============================================================================== --- stable/10/lib/libc/sys/aio_fsync.2 Mon Aug 22 17:45:30 2016 (r304616) +++ stable/10/lib/libc/sys/aio_fsync.2 Mon Aug 22 17:52:10 2016 (r304617) @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 15, 2016 +.Dd August 19, 2016 .Dt AIO_FSYNC 2 .Os .Sh NAME @@ -74,16 +74,14 @@ the call returns without having enqueued .Pp The .Fa iocb->aio_sigevent -structure can be used to request notification of the request's +structure can be used to request notification of the operation's completion as described in .Xr aio 4 . .Sh RESTRICTIONS -The asynchronous I/O Control Block structure pointed to by +The Asynchronous I/O Control Block structure pointed to by .Fa iocb must remain valid until the operation has completed. -For this reason, use of auto (stack) variables -for these objects is discouraged. .Pp The asynchronous I/O control buffer .Fa iocb @@ -91,9 +89,8 @@ should be zeroed before the .Fn aio_fsync call to avoid passing bogus context information to the kernel. .Pp -Modifications of the Asynchronous I/O Control Block structure or the -buffer contents after the request has been enqueued, but before the -request has completed, are not allowed. +Modification of the Asynchronous I/O Control Block structure is not allowed +while the request is queued. .Sh RETURN VALUES .Rv -std aio_fsync .Sh ERRORS Modified: stable/10/lib/libc/sys/aio_mlock.2 ============================================================================== --- stable/10/lib/libc/sys/aio_mlock.2 Mon Aug 22 17:45:30 2016 (r304616) +++ stable/10/lib/libc/sys/aio_mlock.2 Mon Aug 22 17:52:10 2016 (r304617) @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 15, 2016 +.Dd August 19, 2016 .Dt AIO_MLOCK 2 .Os .Sh NAME @@ -67,7 +67,7 @@ then the call returns without having enq .Pp The .Fa iocb->aio_sigevent -structure can be used to request notification of the request's +structure can be used to request notification of the operation's completion as described in .Xr aio 4 . .Sh RESTRICTIONS @@ -77,8 +77,6 @@ and the buffer that the .Fa iocb->aio_buf member of that structure references must remain valid until the operation has completed. -For this reason, use of auto (stack) variables -for these objects is discouraged. .Pp The asynchronous I/O control buffer .Fa iocb @@ -87,8 +85,8 @@ should be zeroed before the call to avoid passing bogus context information to the kernel. .Pp Modifications of the Asynchronous I/O Control Block structure or the -buffer contents after the request has been enqueued, but before the -request has completed, are not allowed. +memory mapping described by the virtual address range are not allowed +while the request is queued. .Sh RETURN VALUES .Rv -std aio_mlock .Sh ERRORS Modified: stable/10/lib/libc/sys/aio_read.2 ============================================================================== --- stable/10/lib/libc/sys/aio_read.2 Mon Aug 22 17:45:30 2016 (r304616) +++ stable/10/lib/libc/sys/aio_read.2 Mon Aug 22 17:52:10 2016 (r304617) @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 15, 2016 +.Dd August 19, 2016 .Dt AIO_READ 2 .Os .Sh NAME @@ -82,7 +82,7 @@ not be referenced after the request is e .Pp The .Fa iocb->aio_sigevent -structure can be used to request notification of the request's +structure can be used to request notification of the operation's completion as described in .Xr aio 4 . .Sh RESTRICTIONS @@ -92,8 +92,6 @@ and the buffer that the .Fa iocb->aio_buf member of that structure references must remain valid until the operation has completed. -For this reason, use of auto (stack) variables -for these objects is discouraged. .Pp The asynchronous I/O control buffer .Fa iocb @@ -102,8 +100,7 @@ should be zeroed before the call to avoid passing bogus context information to the kernel. .Pp Modifications of the Asynchronous I/O Control Block structure or the -buffer contents after the request has been enqueued, but before the -request has completed, are not allowed. +buffer contents are not allowed while the request is queued. .Pp If the file offset in .Fa iocb->aio_offset Modified: stable/10/lib/libc/sys/aio_write.2 ============================================================================== --- stable/10/lib/libc/sys/aio_write.2 Mon Aug 22 17:45:30 2016 (r304616) +++ stable/10/lib/libc/sys/aio_write.2 Mon Aug 22 17:52:10 2016 (r304617) @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 15, 2016 +.Dd August 19, 2016 .Dt AIO_WRITE 2 .Os .Sh NAME @@ -88,7 +88,7 @@ be referenced after the request is enque .Pp The .Fa iocb->aio_sigevent -structure can be used to request notification of the request's +structure can be used to request notification of the operation's completion as described in .Xr aio 4 . .Sh RESTRICTIONS @@ -98,8 +98,6 @@ and the buffer that the .Fa iocb->aio_buf member of that structure references must remain valid until the operation has completed. -For this reason, use of auto (stack) variables -for these objects is discouraged. .Pp The asynchronous I/O control buffer .Fa iocb @@ -108,8 +106,7 @@ should be zeroed before the system call to avoid passing bogus context information to the kernel. .Pp Modifications of the Asynchronous I/O Control Block structure or the -buffer contents after the request has been enqueued, but before the -request has completed, are not allowed. +buffer contents are not allowed while the request is queued. .Pp If the file offset in .Fa iocb->aio_offset