[PATCH] stat.2: add note about stat being racy

[Jann Horn <jann-XZ1E9jl8jIdeoWH0uzbU5w@public.gmane.org>]

[-- Attachment #1: Type: text/plain, Size: 1203 bytes --]

The same thing was fixed for execve() in commit
8b01fc86b9f425899f8a3a8fc1c47d73c2c20543, but for performance
reasons, that simple patch won't work for stat().
---
 man2/stat.2 | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/man2/stat.2 b/man2/stat.2
index 0d244af..69ec6a4 100644
--- a/man2/stat.2
+++ b/man2/stat.2
@@ -175,6 +175,29 @@ that may be present between some fields on various architectures.
 Consult the glibc and kernel source code
 if you need to know the details.
 
+\# Background: inode attributes are modified with i_mutex held, but
+\# read by stat() without taking the mutex.
+.I Note:
+For performance and simplicity reasons, different fields in the
+.I stat
+structure may contain state information from different moments
+during the execution of the syscall. For example, if
+.IR st_mode ,
+.IR st_uid
+and
+.IR st_gid
+are changed by another process by calling
+.BR chown (2) ,
+.BR stat ()
+might return the old
+.I st_mode
+together with the new
+.IR st_uid ,
+or the old
+.I st_uid
+together with the new
+.IR st_mode .
+
 The
 .I st_dev
 field describes the device on which this file resides.
-- 
2.1.4

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]