* [PATCH 0/2] procfs: document proc timestamps @ 2022-07-22 16:29 Luis Chamberlain 2022-07-22 16:29 ` [PATCH 1/2] Documentation/filesystems/proc.rst: remove ancient boiler plate Luis Chamberlain 2022-07-22 16:29 ` [PATCH 2/2] Documentation/filesystems/proc.rst: document procfs inode timestamps Luis Chamberlain 0 siblings, 2 replies; 5+ messages in thread From: Luis Chamberlain @ 2022-07-22 16:29 UTC (permalink / raw) To: ebiederm, corbet, keescook, yzaikin Cc: songmuchun, zhangyuchen.lcr, dhowells, deepa.kernel, hch, mcgrof, linux-doc, linux-api, linux-fsdevel, linux-kernel 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(-) -- 2.35.1 ^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH 1/2] Documentation/filesystems/proc.rst: remove ancient boiler plate 2022-07-22 16:29 [PATCH 0/2] procfs: document proc timestamps Luis Chamberlain @ 2022-07-22 16:29 ` Luis Chamberlain 2022-07-22 16:29 ` [PATCH 2/2] Documentation/filesystems/proc.rst: document procfs inode timestamps Luis Chamberlain 1 sibling, 0 replies; 5+ messages in thread From: Luis Chamberlain @ 2022-07-22 16:29 UTC (permalink / raw) To: ebiederm, corbet, keescook, yzaikin Cc: songmuchun, zhangyuchen.lcr, dhowells, deepa.kernel, hch, mcgrof, linux-doc, linux-api, linux-fsdevel, linux-kernel 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. Signed-off-by: Luis Chamberlain <mcgrof@kernel.org> --- Documentation/filesystems/proc.rst | 55 ------------------------------ 1 file changed, 55 deletions(-) diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 47e95dbc820d..9fd5249f1a5f 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -4,22 +4,8 @@ The /proc Filesystem ==================== -===================== ======================================= ================ -/proc/sys Terrehon Bowden <terrehon@pacbell.net>, October 7 1999 - Bodo Bauer <bb@ricochet.net> -2.4.x update Jorge Nerin <comandante@zaralinux.com> November 14 2000 -move /proc/sys Shen Feng <shen@cn.fujitsu.com> April 1 2009 -fixes/update part 1.1 Stefani Seibold <stefani@seibold.net> 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 <stefani@seibold.net> 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 bb@ricochet.net. 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 linux-kernel@vger.kernel.org and/or try to reach me at -comandante@zaralinux.com. - -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 ======================================== -- 2.35.1 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH 2/2] Documentation/filesystems/proc.rst: document procfs inode timestamps 2022-07-22 16:29 [PATCH 0/2] procfs: document proc timestamps Luis Chamberlain 2022-07-22 16:29 ` [PATCH 1/2] Documentation/filesystems/proc.rst: remove ancient boiler plate Luis Chamberlain @ 2022-07-22 16:29 ` Luis Chamberlain 2022-07-22 19:56 ` Randy Dunlap 2022-07-23 14:17 ` Muchun Song 1 sibling, 2 replies; 5+ messages in thread From: Luis Chamberlain @ 2022-07-22 16:29 UTC (permalink / raw) To: ebiederm, corbet, keescook, yzaikin Cc: songmuchun, zhangyuchen.lcr, dhowells, deepa.kernel, hch, mcgrof, linux-doc, linux-api, linux-fsdevel, linux-kernel 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/20220721081617.36103-1-zhangyuchen.lcr@bytedance.com Reported-by: Zhang Yuchen <zhangyuchen.lcr@bytedance.com> Signed-off-by: Luis Chamberlain <mcgrof@kernel.org> --- Documentation/filesystems/proc.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst index 9fd5249f1a5f..9defe9af683a 100644 --- a/Documentation/filesystems/proc.rst +++ b/Documentation/filesystems/proc.rst @@ -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. -- 2.35.1 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH 2/2] Documentation/filesystems/proc.rst: document procfs inode timestamps 2022-07-22 16:29 ` [PATCH 2/2] Documentation/filesystems/proc.rst: document procfs inode timestamps Luis Chamberlain @ 2022-07-22 19:56 ` Randy Dunlap 2022-07-23 14:17 ` Muchun Song 1 sibling, 0 replies; 5+ messages in thread From: Randy Dunlap @ 2022-07-22 19:56 UTC (permalink / raw) To: Luis Chamberlain, ebiederm, corbet, keescook, yzaikin Cc: songmuchun, zhangyuchen.lcr, dhowells, deepa.kernel, hch, linux-doc, linux-api, linux-fsdevel, linux-kernel Hi-- On 7/22/22 09:29, Luis Chamberlain wrote: > 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/20220721081617.36103-1-zhangyuchen.lcr@bytedance.com > Reported-by: Zhang Yuchen <zhangyuchen.lcr@bytedance.com> > Signed-off-by: Luis Chamberlain <mcgrof@kernel.org> > --- > Documentation/filesystems/proc.rst | 16 ++++++++++++++++ > 1 file changed, 16 insertions(+) > > diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst > index 9fd5249f1a5f..9defe9af683a 100644 > --- a/Documentation/filesystems/proc.rst > +++ b/Documentation/filesystems/proc.rst > @@ -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. > +content to be changed each time a file is read. The proc files and directories The proc files and directory > +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. -- ~Randy ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH 2/2] Documentation/filesystems/proc.rst: document procfs inode timestamps 2022-07-22 16:29 ` [PATCH 2/2] Documentation/filesystems/proc.rst: document procfs inode timestamps Luis Chamberlain 2022-07-22 19:56 ` Randy Dunlap @ 2022-07-23 14:17 ` Muchun Song 1 sibling, 0 replies; 5+ messages in thread From: Muchun Song @ 2022-07-23 14:17 UTC (permalink / raw) To: Luis Chamberlain Cc: Eric W. Biederman, Jonathan Corbet, Kees Cook, Iurii Zaikin, Zhang Yuchen, David Howells, Deepa Dinamani, Christoph Hellwig, Linux Doc Mailing List, linux-api, linux-fsdevel, LKML On Sat, Jul 23, 2022 at 12:29 AM Luis Chamberlain <mcgrof@kernel.org> wrote: > > 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/20220721081617.36103-1-zhangyuchen.lcr@bytedance.com > Reported-by: Zhang Yuchen <zhangyuchen.lcr@bytedance.com> > Signed-off-by: Luis Chamberlain <mcgrof@kernel.org> > --- > Documentation/filesystems/proc.rst | 16 ++++++++++++++++ > 1 file changed, 16 insertions(+) > > diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst > index 9fd5249f1a5f..9defe9af683a 100644 > --- a/Documentation/filesystems/proc.rst > +++ b/Documentation/filesystems/proc.rst > @@ -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). Thanks for fixing this. > + > 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. > + 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. > The /proc/PID/maps file contains the currently mapped memory regions and > their access permissions. > > -- > 2.35.1 > ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2022-07-23 14:17 UTC | newest] Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2022-07-22 16:29 [PATCH 0/2] procfs: document proc timestamps Luis Chamberlain 2022-07-22 16:29 ` [PATCH 1/2] Documentation/filesystems/proc.rst: remove ancient boiler plate Luis Chamberlain 2022-07-22 16:29 ` [PATCH 2/2] Documentation/filesystems/proc.rst: document procfs inode timestamps Luis Chamberlain 2022-07-22 19:56 ` Randy Dunlap 2022-07-23 14:17 ` Muchun Song
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).