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 sysfs. Signed-off-by: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx> --- This patch is for the man-pages project, not the kernel source tree man2/readfile.2 | 159 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 man2/readfile.2 diff --git a/man2/readfile.2 b/man2/readfile.2 new file mode 100644 index 000000000000..449e722c3442 --- /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 +.\" +.\" %%%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) -- 2.27.0
