Skip to contentSkip to conversation

procfs: document proc timestamps

PATCH In review Luis Chamberlain 3 participants 5 messages Jul 22, 2022 – Jul 23, 2022

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

cover procfs: document proc timestamps

This adds some documentation to procfs for the timestamps of inodes. While at it, nuke some ancient silly boiler plate which resemebles a bible disclaimer of some sort.

Luis Chamberlain (2):
Documentation/filesystems/proc.rst: remove ancient boiler plate Documentation/filesystems/proc.rst: document procfs inode timestamps

 Documentation/filesystems/proc.rst | 71 +++++++-----------------------
 1 file changed, 16 insertions(+), 55 deletions(-)
Signature · 1 line
2.35.1
#1 lore raw

PATCH 1/2 Documentation/filesystems/proc.rst: remove ancient boiler plate

The proc.rst has some ancient verbiage which dates back to 1999 which is simply just creating noise at this point for documentation. Remove that cruft.

---
 Documentation/filesystems/proc.rst | 55 ------------------------------
 1 file changed, 55 deletions(-)
Documentation/filesystems/proc.rst +0 -55
index 47e95dbc820d..9fd5249f1a5f 100644
@@ -4,22 +4,8 @@
 The /proc Filesystem
 ====================
 
-=====================  =======================================  ================
-/proc/sys              Terrehon Bowden <[email protected]>,  October 7 1999
-                       Bodo Bauer <[email protected]>
-2.4.x update	       Jorge Nerin <[email protected]>   November 14 2000
-move /proc/sys	       Shen Feng <[email protected]>	        April 1 2009
-fixes/update part 1.1  Stefani Seibold <[email protected]>    June 9 2009
-=====================  =======================================  ================
-
-
-
 .. Table of Contents
 
-  0     Preface
-  0.1	Introduction/Credits
-  0.2	Legal Stuff
-
   1	Collecting System Information
   1.1	Process-Specific Subdirectories
   1.2	Kernel data
@@ -56,47 +42,6 @@ fixes/update part 1.1  Stefani Seibold <[email protected]>    June 9 2009
 Preface
 =======
 
-0.1 Introduction/Credits
-------------------------
-
-This documentation is  part of a soon (or  so we hope) to be  released book on
-the SuSE  Linux distribution. As  there is  no complete documentation  for the
-/proc file system and we've used  many freely available sources to write these
-chapters, it  seems only fair  to give the work  back to the  Linux community.
-This work is  based on the 2.2.*  kernel version and the  upcoming 2.4.*. I'm
-afraid it's still far from complete, but we  hope it will be useful. As far as
-we know, it is the first 'all-in-one' document about the /proc file system. It
-is focused  on the Intel  x86 hardware,  so if you  are looking for  PPC, ARM,
-SPARC, AXP, etc., features, you probably  won't find what you are looking for.
-It also only covers IPv4 networking, not IPv6 nor other protocols - sorry. But
-additions and patches  are welcome and will  be added to this  document if you
-mail them to Bodo.
-
-We'd like  to  thank Alan Cox, Rik van Riel, and Alexey Kuznetsov and a lot of
-other people for help compiling this documentation. We'd also like to extend a
-special thank  you to Andi Kleen for documentation, which we relied on heavily
-to create  this  document,  as well as the additional information he provided.
-Thanks to  everybody  else  who contributed source or docs to the Linux kernel
-and helped create a great piece of software... :)
-
-If you  have  any comments, corrections or additions, please don't hesitate to
-contact Bodo  Bauer  at  [email protected].  We'll  be happy to add them to this
-document.
-
-The   latest   version    of   this   document   is    available   online   at
-http://tldp.org/LDP/Linux-Filesystem-Hierarchy/html/proc.html
-
-If  the above  direction does  not works  for you,  you could  try the  kernel
-mailing  list  at  [email protected]  and/or try  to  reach  me  at
[email protected].
-
-0.2 Legal Stuff
----------------
-
-We don't  guarantee  the  correctness  of this document, and if you come to us
-complaining about  how  you  screwed  up  your  system  because  of  incorrect
-documentation, we won't feel responsible...
-
 Chapter 1: Collecting System Information
 ========================================
 
Signature · 1 line
2.35.1
#2 lore raw

PATCH 2/2 Documentation/filesystems/proc.rst: document procfs inode timestamps

In reply to Luis Chamberlain

The timestamps for procfs files are not well understood and can confuse users and developers [0] in particular for the timestamp for the start time or a process. Clarify what they mean and that they are a reflection of the ephemeral nature of the filesystem inodes.

The procfs inodes are created when you first read them and then stuffed in the page cache. If the page cache and indodes are reclaimed they can be removed, and re-created with a new timestamp after read again. Document this little bit of tribal knowledge.

[0] https://lkml.kernel.org/r/[email protected]

---
 Documentation/filesystems/proc.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
Documentation/filesystems/proc.rst +16 -0
index 9fd5249f1a5f..9defe9af683a 100644
@@ -59,6 +59,15 @@ The proc  file  system acts as an interface to internal data structures in the
 kernel. It  can  be  used to obtain information about the system and to change
 certain kernel parameters at runtime (sysctl).
 
+The proc files are dynamic in nature and allow for developers to make the
+content to be changed each time a file is read. The proc files and directories
+inodes are created when someone first reads a respective proc file or directory,
+as such the timestamps of the proc files reflect this time. As with other
+filesystems, these proc inodes can be removed through reclaim under memory
+pressure and so the timestamps of the proc files can change if the proc files
+are destroyed and re-created (echo 3 > /proc/sys/vm/drop_caches forces and
+illustrate the reclaim of inodes and page cache).
+
 First, we'll  take  a  look  at the read-only parts of /proc. In Chapter 2, we
 show you how you can use /proc/sys to change settings.
 
@@ -328,6 +337,13 @@ It's slow but very precise.
 		system call
   ============= ===============================================================
 
+Note that the start_time inside the stat file is different than the timestamp
+of the stat file itself. The timestamp of the stat file simply reflects the
+first time the stat file was read. The proc inode for this file can be reclaimed
+under memory pressure and be recreated after this and so the timestamp can
+change. Userspace should rely on the start_time entry in the the stat file to
+get a process start time.
+
 The /proc/PID/maps file contains the currently mapped memory regions and
 their access permissions.
 
Signature · 1 line
2.35.1
reviewer
#3 lore raw

Re: [PATCH 2/2] Documentation/filesystems/proc.rst: document procfs inode timestamps

Hi--

Quoted 23 lines · Luis Chamberlain

The timestamps for procfs files are not well understood and can confuse users and developers [0] in particular for the timestamp for the start time or a process. Clarify what they mean and that they are a reflection of the ephemeral nature of the filesystem inodes.

The procfs inodes are created when you first read them and then stuffed in the page cache. If the page cache and indodes are reclaimed they can be removed, and re-created with a new timestamp after read again. Document this little bit of tribal knowledge.

[0] https://lkml.kernel.org/r/[email protected]

---
 Documentation/filesystems/proc.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
Documentation/filesystems/proc.rst +0 -0
index 9fd5249f1a5f..9defe9af683a 100644

Documentation/filesystems/proc.rst The proc file system acts as an interface to internal data structures in the · line 62

Quoted 4 lines
Documentation/filesystems/proc.rst +1 -0
@@ -59,6 +59,15 @@ The proc  file  system acts as an interface to internal data structures in the
 kernel. It  can  be  used to obtain information about the system and to change
 certain kernel parameters at runtime (sysctl).
 
+The proc files are dynamic in nature and allow for developers to make the

Awkward. How about:

The proc files are dynamic and allow for the content to be changed each time a file is read.

Documentation/filesystems/proc.rst The proc file system acts as an interface to internal data structures in the · line 63

Quoted 1 line
Documentation/filesystems/proc.rst +1 -0
+content to be changed each time a file is read. The proc files and directories

The proc files and directory

Documentation/filesystems/proc.rst The proc file system acts as an interface to internal data structures in the · line 72

Quoted 9 lines
Documentation/filesystems/proc.rst +7 -0
+inodes are created when someone first reads a respective proc file or directory,
+as such the timestamps of the proc files reflect this time. As with other
+filesystems, these proc inodes can be removed through reclaim under memory
+pressure and so the timestamps of the proc files can change if the proc files
+are destroyed and re-created (echo 3 > /proc/sys/vm/drop_caches forces and
+illustrate the reclaim of inodes and page cache).
+
 First, we'll  take  a  look  at the read-only parts of /proc. In Chapter 2, we
 show you how you can use /proc/sys to change settings.

Thanks.

Signature · 1 line
~Randy
#4 lore raw

Re: [PATCH 2/2] Documentation/filesystems/proc.rst: document procfs inode timestamps

In reply to Luis Chamberlain
Quoted 25 lines · Luis Chamberlain

The timestamps for procfs files are not well understood and can confuse users and developers [0] in particular for the timestamp for the start time or a process. Clarify what they mean and that they are a reflection of the ephemeral nature of the filesystem inodes.

The procfs inodes are created when you first read them and then stuffed in the page cache. If the page cache and indodes are reclaimed they can be removed, and re-created with a new timestamp after read again. Document this little bit of tribal knowledge.

[0] https://lkml.kernel.org/r/[email protected]

---
 Documentation/filesystems/proc.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
Documentation/filesystems/proc.rst +0 -0
index 9fd5249f1a5f..9defe9af683a 100644
@@ -59,6 +59,15 @@ The proc  file  system acts as an interface to internal data structures in the
 kernel. It  can  be  used to obtain information about the system and to change

Documentation/filesystems/proc.rst The proc file system acts as an interface to internal data structures in the · line 69

Quoted 10 lines
Documentation/filesystems/proc.rst +8 -0
 certain kernel parameters at runtime (sysctl).
 
+The proc files are dynamic in nature and allow for developers to make the
+content to be changed each time a file is read. The proc files and directories
+inodes are created when someone first reads a respective proc file or directory,
+as such the timestamps of the proc files reflect this time. As with other
+filesystems, these proc inodes can be removed through reclaim under memory
+pressure and so the timestamps of the proc files can change if the proc files
+are destroyed and re-created (echo 3 > /proc/sys/vm/drop_caches forces and
+illustrate the reclaim of inodes and page cache).

Thanks for fixing this.

Quoted 5 lines
Documentation/filesystems/proc.rst +1 -0
+
 First, we'll  take  a  look  at the read-only parts of /proc. In Chapter 2, we
 show you how you can use /proc/sys to change settings.
 

Documentation/filesystems/proc.rst It's slow but very precise. · line 346

Quoted 10 lines
Documentation/filesystems/proc.rst +7 -0
@@ -328,6 +337,13 @@ It's slow but very precise.
                system call
   ============= ===============================================================
 
+Note that the start_time inside the stat file is different than the timestamp
+of the stat file itself. The timestamp of the stat file simply reflects the
+first time the stat file was read. The proc inode for this file can be reclaimed
+under memory pressure and be recreated after this and so the timestamp can
+change. Userspace should rely on the start_time entry in the the stat file to
+get a process start time.
+

I'm not sure the value of those comments since the above description is already enough to tell people the timestamp of /proc files or directories can be changed in some cases, which already includes the case of /proc/PID/stat.

If we really want to take /proc/PID/stat as an example to show the timestamp is unstable, I think it is better to move those comments to the above section where you explain why the timestamp can be changed .

Thanks.

Quoted 6 lines
Documentation/filesystems/proc.rst +0 -1
 The /proc/PID/maps file contains the currently mapped memory regions and
 their access permissions.
 
--

2.35.1