svn commit: r349854 - stable/12/lib/libc/sys

[Konstantin Belousov]

Author: kib
Date: Tue Jul  9 07:19:36 2019
New Revision: 349854
URL: https://svnweb.freebsd.org/changeset/base/349854

Log:
  MFC r349794:
  Document atomicity for read(2) and write(2).

Modified:
  stable/12/lib/libc/sys/read.2
Directory Properties:
  stable/12/   (props changed)

Modified: stable/12/lib/libc/sys/read.2
==============================================================================
--- stable/12/lib/libc/sys/read.2	Mon Jul  8 22:20:25 2019	(r349853)
+++ stable/12/lib/libc/sys/read.2	Tue Jul  9 07:19:36 2019	(r349854)
@@ -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.