[thirdparty/man-pages.git] / man5 / proc_pid_io.5

.\" Copyright (C) 1994, 1995, Daniel Quinlan <quinlan@yggdrasil.com>
.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Copyright (C) 2023, Alejandro Colomar <alx@kernel.org>
.\"
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\"
.TH proc_pid_io 5 (date) "Linux man-pages (unreleased)"
.SH NAME
/proc/pid/io \- I/O statistics
.SH DESCRIPTION
.TP
.IR /proc/ pid /io " (since Linux 2.6.20)"
.\" commit 7c3ab7381e79dfc7db14a67c6f4f3285664e1ec2
This file contains I/O statistics for the process, for example:
.IP
.in +4n
.EX
.RB "#" " cat /proc/3828/io"
rchar: 323934931
wchar: 323929600
syscr: 632687
syscw: 632675
read_bytes: 0
write_bytes: 323932160
cancelled_write_bytes: 0
.EE
.in
.IP
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.
This is simply the sum of bytes which this process passed to
.BR read (2)
and similar system calls.
It includes things such as terminal I/O and
is unaffected by whether or not actual
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.
Similar caveats apply here as with
.IR rchar .
.TP
.IR syscr ": read syscalls"
Attempt to count the number of read I/O operations\[em]that is,
system calls such as
.BR read (2)
and
.BR pread (2).
.TP
.IR syscw ": write syscalls"
Attempt to count the number of write I/O operations\[em]that is,
system calls such as
.BR write (2)
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.
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.
.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
caused to not happen, by truncating pagecache.
A task can cause "negative" I/O too.
If this task truncates some dirty pagecache,
some I/O which another task has been accounted for
(in its
.IR write_bytes )
will not be happening.
.RE
.IP
.IR Note :
In the current implementation, things are a bit racy on 32-bit systems:
if process A reads process B's
.IR /proc/ pid /io
while process B is updating one of these 64-bit counters,
process A could see an intermediate result.
.IP
Permission to access this file is governed by a ptrace access mode
.B PTRACE_MODE_READ_FSCREDS
check; see
.BR ptrace (2).
.SH SEE ALSO
.BR proc (5)
Commit	Line	Data
b47bcfdd AC	1	.\" Copyright (C) 1994, 1995, Daniel Quinlan <quinlan@yggdrasil.com>
	2	.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk <mtk.manpages@gmail.com>
	3	.\" Copyright (C) 2023, Alejandro Colomar <alx@kernel.org>
	4	.\"
	5	.\" SPDX-License-Identifier: GPL-3.0-or-later
	6	.\"
	7	.TH proc_pid_io 5 (date) "Linux man-pages (unreleased)"
	8	.SH NAME
	9	/proc/pid/io \- I/O statistics
	10	.SH DESCRIPTION
	11	.TP
	12	.IR /proc/ pid /io " (since Linux 2.6.20)"
	13	.\" commit 7c3ab7381e79dfc7db14a67c6f4f3285664e1ec2
	14	This file contains I/O statistics for the process, for example:
	15	.IP
	16	.in +4n
	17	.EX
	18	.RB "#" " cat /proc/3828/io"
	19	rchar: 323934931
	20	wchar: 323929600
	21	syscr: 632687
	22	syscw: 632675
	23	read_bytes: 0
	24	write_bytes: 323932160
	25	cancelled_write_bytes: 0
	26	.EE
	27	.in
	28	.IP
	29	The fields are as follows:
	30	.RS
	31	.TP
	32	.IR rchar ": characters read"
	33	The number of bytes which this task has caused to be read from storage.
	34	This is simply the sum of bytes which this process passed to
	35	.BR read (2)
	36	and similar system calls.
	37	It includes things such as terminal I/O and
	38	is unaffected by whether or not actual
	39	physical disk I/O was required (the read might have been satisfied from
	40	pagecache).
	41	.TP
	42	.IR wchar ": characters written"
	43	The number of bytes which this task has caused, or shall cause to be written
	44	to disk.
	45	Similar caveats apply here as with
	46	.IR rchar .
	47	.TP
	48	.IR syscr ": read syscalls"
	49	Attempt to count the number of read I/O operations\[em]that is,
	50	system calls such as
	51	.BR read (2)
	52	and
	53	.BR pread (2).
	54	.TP
	55	.IR syscw ": write syscalls"
	56	Attempt to count the number of write I/O operations\[em]that is,
	57	system calls such as
	58	.BR write (2)
	59	and
	60	.BR pwrite (2).
	61	.TP
	62	.IR read_bytes ": bytes read"
	63	Attempt to count the number of bytes which this process really did cause to
	64	be fetched from the storage layer.
65	This is accurate for block-backed filesystems.
66	.TP
67	.IR write_bytes ": bytes written"
68	Attempt to count the number of bytes which this process caused to be sent to
69	the storage layer.
70	.TP
71	.IR cancelled_write_bytes :
72	The big inaccuracy here is truncate.
73	If a process writes 1 MB to a file and then deletes the file,
74	it will in fact perform no writeout.
75	But it will have been accounted as having caused 1 MB of write.
76	In other words: this field represents the number of bytes which this process
77	caused to not happen, by truncating pagecache.
78	A task can cause "negative" I/O too.
79	If this task truncates some dirty pagecache,
80	some I/O which another task has been accounted for
81	(in its
82	.IR write_bytes )
83	will not be happening.
84	.RE
85	.IP
86	.IR Note :
87	In the current implementation, things are a bit racy on 32-bit systems:
88	if process A reads process B's
89	.IR /proc/ pid /io
90	while process B is updating one of these 64-bit counters,
91	process A could see an intermediate result.
92	.IP
93	Permission to access this file is governed by a ptrace access mode
94	.B PTRACE_MODE_READ_FSCREDS
95	check; see
96	.BR ptrace (2).
97	.SH SEE ALSO
98	.BR proc (5)