man2/readfile.2

.\" This manpage is Copyright (C) 2020 Greg Kroah-Hartman;
.\"  and Copyright (C) 2020 The Linux Foundation
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" 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.
.\" %%%LICENSE_END
.\"
.TH READFILE 2 2020-07-04 "Linux" "Linux Programmer's Manual"
.SH NAME
readfile \- read a file into a buffer
.SH SYNOPSIS
.nf
.B #include <unistd.h>
.PP
.BI "ssize_t readfile(int " dirfd ", const char *" pathname ", void *" buf \
", size_t " count ", int " flags );
.fi
.SH DESCRIPTION
.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
or
.BR sysfs .
.PP
If the size of file is smaller than the value provided in
.I count
then the whole file will be copied into
.IR buf .
.PP
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 .
.PP
The argument
.I flags
may contain one of the following
.IR "access modes" :
.BR O_NOFOLLOW ", or " O_NOATIME .
.PP
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 .
.PP
If
.I pathname
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
.I pathname
is interpreted relative to the current working
directory of the calling process (like
.BR openat ()).
.PP
If
.I pathname
is absolute, then
.I dirfd
is ignored.
.SH RETURN VALUE
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.
.PP
On error, \-1 is returned, and
.I errno
is set appropriately.
.SH ERRORS
.TP
.B EFAULT
.I buf
is outside your accessible address space.
.TP
.B EINTR
The call was interrupted by a signal before any data was read; see
.BR signal (7).
.TP
.B EINVAL
.I flags
was set to a value that is not allowed.
.TP
.B EIO
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
.B SIGTTIN
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
.B EIO
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.
.SH CONFORMING TO
None, this is a Linux-specific system call at this point in time.
.SH NOTES
The type
.I size_t
is an unsigned integer data type specified by POSIX.1.
.PP
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.)
.SH BUGS
None yet!
.SH SEE ALSO
.BR close (2),
.BR open (2),
.BR openat (2),
.BR read (2),
.BR fread (3)