stat.2: add note about stat being racy

Commit Message

Jann Horn April 20, 2015, 8:46 p.m. UTC

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(+)

Comments

Michael Kerrisk (man-pages) April 21, 2015, 12:44 p.m. UTC | #1

On 04/20/2015 10:46 PM, Jann Horn wrote:
> The same thing was fixed for execve() in commit
> 8b01fc86b9f425899f8a3a8fc1c47d73c2c20543, but for performance
> reasons, that simple patch won't work for stat().

Thanks, Jann! Applied.

Cheers,

Michael


> ---
>  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.
>

Patch

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.