git: 1c8d7bb4cf7a - main - write.2: explain the atomicity guarantees of the writes

The branch main has been updated by kib:

URL: https://cgit.FreeBSD.org/src/commit/?id=1c8d7bb4cf7a6b19262333b2a9b1dacf3094b938

commit 1c8d7bb4cf7a6b19262333b2a9b1dacf3094b938
Author:     Konstantin Belousov <kib@FreeBSD.org>
AuthorDate: 2025-10-26 14:57:16 +0000
Commit:     Konstantin Belousov <kib@FreeBSD.org>
CommitDate: 2025-10-26 17:35:31 +0000

    write.2: explain the atomicity guarantees of the writes
    
    Also provide the pointer to the latest POSIX standard that justifies the
    requirement.
    
    Reviewed by:    emaste
    Discussed with: rmacklem
    Sponsored by:   The FreeBSD Foundation
    MFC after:      1 week
    Differential revision:  https://reviews.freebsd.org/D53361
---
 lib/libsys/write.2 | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/lib/libsys/write.2 b/lib/libsys/write.2
index d2ff41ceead9..77067893ab4c 100644
--- a/lib/libsys/write.2
+++ b/lib/libsys/write.2
@@ -132,6 +132,26 @@ and
 may write fewer bytes than requested;
 the return value must be noted,
 and the remainder of the operation should be retried when possible.
+.Sh ATOMICITY OF WRITES
+When operating on regular files on local file systems, the effects of
+.Fn write
+are atomic.
+As required by the POSIX standard,
+the
+.Fn read ,
+.Fn write ,
+and
+.Fn ftruncate
+functions and their variations are atomic with respect to
+each other on the file data and metadata for regular files.
+See for instance
+.St -p1003.1-2024
+Volume 2, Section 2.9.7 for more information.
+.Pp
+.Fx
+implements the requirement by taking
+a read/write range lock on the file byte range
+affected by the corresponding function.
 .Sh RETURN VALUES
 Upon successful completion the number of bytes which were written
 is returned.