svn commit: r349794 - head/lib/libc/sys

[Konstantin Belousov]

Author: kib
Date: Sat Jul  6 20:31:37 2019
New Revision: 349794
URL: https://svnweb.freebsd.org/changeset/base/349794

Log:
  Document atomicity for read(2) and write(2).
  
  Take part of the text from POSIX 2018 edition and describe the
  atomicity requirements for read and write syscalls.  See p1003.1-2018,
  Vol.2, 2.9.7 Threads interaction with Regular File Operations.
  
  Reviewed by:	asomers
  Sponsored by:	The FreeBSD Foundation
  MFC after:	3 days
  Differential revision:	https://reviews.freebsd.org/D20867

Modified:
  head/lib/libc/sys/read.2

Modified: head/lib/libc/sys/read.2
==============================================================================
--- head/lib/libc/sys/read.2	Sat Jul  6 18:02:29 2019	(r349793)
+++ head/lib/libc/sys/read.2	Sat Jul  6 20:31:37 2019	(r349794)
@@ -28,7 +28,7 @@
 .\"     @(#)read.2	8.4 (Berkeley) 2/26/94
 .\" $FreeBSD$
 .\"
-.Dd December 1, 2017
+.Dd July 6, 2019
 .Dt READ 2
 .Os
 .Sh NAME
@@ -128,6 +128,25 @@ return the number of bytes actually read and placed in
 The system guarantees to read the number of bytes requested if
 the descriptor references a normal file that has that many bytes left
 before the end-of-file, but in no other case.
+.Pp
+In accordance with
+.St -p1003.1-2004 ,
+both
+.Xr read 2
+and
+.Xr write 2
+syscalls are atomic with respect to each other in the effects on file
+content, when they operate on regular files.
+If two threads each call one of the
+.Xr read 2
+or
+.Xr write 2 ,
+syscalls, each call will see either all of the changes of the other call,
+or none of them.
+The
+.Fx
+kernel implements this guarantee by locking the file ranges affected by
+the calls.
 .Sh RETURN VALUES
 If successful, the
 number of bytes actually read is returned.