From 064f965c1244fb7c89ef1d66a7c3e87d522bccad Mon Sep 17 00:00:00 2001
From: наб <nabijaczleweli@nabijaczleweli.xyz>
Date: Sun, 17 Mar 2024 12:01:43 +0100
Subject: proc_pid_io.5: Stats include children
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This file is like getrusage(2) RUSAGE_SELF + RUSAGE_CHILDREN,
the current wording implies it's like just RUSAGE_SELF.

Compare:
  #include <fcntl.h>
  #include <signal.h>
  #include <string.h>
  #include <sys/wait.h>
  #include <unistd.h>

  void copy() {
    char buf[1024];
    int fd = open("/proc/self/io", 0);
    write(1, buf, read(fd, buf, sizeof(buf)));
    close(fd);
  }

  int main() {
    copy();
    copy();
    if (!fork()) {
    zero:;
      int fd = open("/dev/zero", 0);
      char buf[64 * 1024] = {};
      write(1, buf, 10000);
      for (int i = 0; i < 1000; ++i)
        read(fd, buf, sizeof(buf));
      _exit(0);
    }
    sleep(1);
    copy();
    wait(NULL);
    copy();
    signal(SIGCHLD, SIG_IGN);
    if (!fork())
      goto zero;
    sleep(1);
    copy();
    wait(NULL);
    copy();
  }
yielding
  rchar: 3980
  wchar: 0
  syscr: 9
  syscw: 0
  read_bytes: 2968
  write_bytes: 0
  cancelled_write_bytes: 0

  rchar: 4076
  wchar: 96
  syscr: 10
  syscw: 1
  read_bytes: 2968
  write_bytes: 96
  cancelled_write_bytes: 0

  rchar: 4175
  wchar: 195
  syscr: 11
  syscw: 2
  read_bytes: 2968
  write_bytes: 195
  cancelled_write_bytes: 0

  rchar: 65540276
  wchar: 10296
  syscr: 1012
  syscw: 4
  read_bytes: 2968
  write_bytes: 10296
  cancelled_write_bytes: 0

  rchar: 65540387
  wchar: 10407
  syscr: 1013
  syscw: 5
  read_bytes: 2968
  write_bytes: 10407
  cancelled_write_bytes: 0

  rchar: 65540498
  wchar: 10518
  syscr: 1014
  syscw: 6
  read_bytes: 2968
  write_bytes: 10518
  cancelled_write_bytes: 0

Just s/process/& and its waited-for children/ but re-broken per review.

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man5/proc_pid_io.5 | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/man5/proc_pid_io.5 b/man5/proc_pid_io.5
index d6eaebf5d..dc75a91de 100644
--- a/man5/proc_pid_io.5
+++ b/man5/proc_pid_io.5
@@ -11,7 +11,9 @@
 .TP
 .IR /proc/ pid /io " (since Linux 2.6.20)"
 .\" commit 7c3ab7381e79dfc7db14a67c6f4f3285664e1ec2
-This file contains I/O statistics for the process, for example:
+This file contains I/O statistics
+for the process and its waited-for children,
+for example:
 .IP
 .in +4n
 .EX
@@ -30,7 +32,9 @@ The fields are as follows:
 .RS
 .TP
 .IR rchar ": characters read"
-The number of bytes which this task has caused to be read from storage.
+The number of bytes
+which this task and its waited-for children
+have caused to be read from storage.
 This is simply the sum of bytes which this process passed to
 .BR read (2)
 and similar system calls.
@@ -40,8 +44,9 @@ physical disk I/O was required (the read might have been satisfied from
 pagecache).
 .TP
 .IR wchar ": characters written"
-The number of bytes which this task has caused, or shall cause to be written
-to disk.
+The number of bytes
+which this task and its waited-for children
+have caused, or shall cause to be written to disk.
 Similar caveats apply here as with
 .IR rchar .
 .TP
@@ -60,20 +65,24 @@ and
 .BR pwrite (2).
 .TP
 .IR read_bytes ": bytes read"
-Attempt to count the number of bytes which this process really did cause to
-be fetched from the storage layer.
+Attempt to count the number of bytes
+which this process and its waited-for children
+really did cause to be fetched from the storage layer.
 This is accurate for block-backed filesystems.
 .TP
 .IR write_bytes ": bytes written"
-Attempt to count the number of bytes which this process caused to be sent to
-the storage layer.
+Attempt to count the number of bytes
+which this process and its waited-for children
+caused to be sent to the storage layer.
 .TP
 .IR cancelled_write_bytes :
 The big inaccuracy here is truncate.
 If a process writes 1 MB to a file and then deletes the file,
 it will in fact perform no writeout.
 But it will have been accounted as having caused 1 MB of write.
-In other words: this field represents the number of bytes which this process
+In other words:
+this field represents the number of bytes
+which this process and its waited-for children
 caused to not happen, by truncating pagecache.
 A task can cause "negative" I/O too.
 If this task truncates some dirty pagecache,
-- 
cgit v1.2.3