blob: 5a18923787f5434b0ed8f034fef54b48ebcce367 [file] [log] [blame]
From 8d58e2dad8eb7d6fc1cf689adcf0a88e033ea109 Mon Sep 17 00:00:00 2001
From: Greg Kroah-Hartman <>
Date: Fri, 12 Jun 2020 12:11:39 +0200
Subject: [PATCH 4/4] readfile.2: new page describing readfile(2)
readfile(2) is a new syscall to remove the need to do the
open/read/close dance for small virtual files in places like procfs or
Signed-off-by: Greg Kroah-Hartman <>
man2/readfile.2 | 159 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 159 insertions(+)
create mode 100644 man2/readfile.2
--- /dev/null
+++ b/man2/readfile.2
@@ -0,0 +1,159 @@
+.\" This manpage is Copyright (C) 2020 Greg Kroah-Hartman;
+.\" and Copyright (C) 2020 The Linux Foundation
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date. The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein. The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.TH READFILE 2 2020-07-04 "Linux" "Linux Programmer's Manual"
+readfile \- read a file into a buffer
+.B #include <unistd.h>
+.BI "ssize_t readfile(int " dirfd ", const char *" pathname ", void *" buf \
+", size_t " count ", int " flags );
+.BR readfile ()
+attempts to open the file specified by
+.IR pathname
+and to read up to
+.I count
+bytes from the file into the buffer starting at
+.IR buf .
+It is to be a shortcut of doing the sequence of
+.BR open ()
+and then
+.BR read ()
+and then
+.BR close ()
+for small files that are read frequently, such as those in
+.B procfs
+.BR sysfs .
+If the size of file is smaller than the value provided in
+.I count
+then the whole file will be copied into
+.IR buf .
+If the file is larger than the value provided in
+.I count
+then only
+.I count
+number of bytes will be copied into
+.IR buf .
+The argument
+.I flags
+may contain one of the following
+.IR "access modes" :
+If the pathname given in
+.I pathname
+is relative, then it is interpreted relative to the directory
+referred to by the file descriptor
+.IR dirfd .
+.I pathname
+is relative and
+.I dirfd
+is the special value
+.I pathname
+is interpreted relative to the current working
+directory of the calling process (like
+.BR openat ()).
+.I pathname
+is absolute, then
+.I dirfd
+is ignored.
+On success, the number of bytes read is returned.
+It is not an error if this number is smaller than the number of bytes
+requested; this can happen if the file is smaller than the number of
+bytes requested.
+On error, \-1 is returned, and
+.I errno
+is set appropriately.
+.I buf
+is outside your accessible address space.
+The call was interrupted by a signal before any data was read; see
+.BR signal (7).
+.I flags
+was set to a value that is not allowed.
+I/O error.
+This will happen for example when the process is in a
+background process group, tries to read from its controlling terminal,
+and either it is ignoring or blocking
+or its process group
+is orphaned.
+It may also occur when there is a low-level I/O error
+while reading from a disk or tape.
+A further possible cause of
+on networked filesystems is when an advisory lock had been taken
+out on the file descriptor and this lock has been lost.
+See the
+.I "Lost locks"
+section of
+.BR fcntl (2)
+for further details.
+None, this is a Linux-specific system call at this point in time.
+The type
+.I size_t
+is an unsigned integer data type specified by POSIX.1.
+On Linux,
+.BR read ()
+(and similar system calls) will transfer at most
+0x7ffff000 (2,147,479,552) bytes,
+returning the number of bytes actually transferred.
+.\" commit e28cc71572da38a5a12c1cfe4d7032017adccf69
+(This is true on both 32-bit and 64-bit systems.)
+None yet!
+.BR close (2),
+.BR open (2),
+.BR openat (2),
+.BR read (2),
+.BR fread (3)