| .\" This manpage is Copyright (C) 2004, Michael Kerrisk |
| .\" |
| .\" %%%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 |
| .\" |
| .\" 2004-05-40 Created by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" 2004-10-05 aeb, minor correction |
| .\" |
| .TH READAHEAD 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| readahead \- initiate file readahead into page cache |
| .SH SYNOPSIS |
| .nf |
| .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
| .B #include <fcntl.h> |
| .PP |
| .BI "ssize_t readahead(int " fd ", off64_t " offset ", size_t " count ); |
| .fi |
| .SH DESCRIPTION |
| .BR readahead () |
| initiates readahead on a file so that subsequent reads from that file will |
| be satisfied from the cache, and not block on disk I/O |
| (assuming the readahead was initiated early enough and that other activity |
| on the system did not in the meantime flush pages from the cache). |
| .PP |
| The |
| .I fd |
| argument is a file descriptor identifying the file which is |
| to be read. |
| The |
| .I offset |
| argument specifies the starting point from which data is to be read |
| and |
| .I count |
| specifies the number of bytes to be read. |
| I/O is performed in whole pages, so that |
| .I offset |
| is effectively rounded down to a page boundary |
| and bytes are read up to the next page boundary greater than or |
| equal to |
| .IR "(offset+count)" . |
| .BR readahead () |
| does not read beyond the end of the file. |
| The file offset of the open file description referred to by the file descriptor |
| .I fd |
| is left unchanged. |
| .SH RETURN VALUE |
| On success, |
| .BR readahead () |
| returns 0; on failure, \-1 is returned, with |
| .I errno |
| set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EBADF |
| .I fd |
| is not a valid file descriptor or is not open for reading. |
| .TP |
| .B EINVAL |
| .I fd |
| does not refer to a file type to which |
| .BR readahead () |
| can be applied. |
| .SH VERSIONS |
| The |
| .BR readahead () |
| system call appeared in Linux 2.4.13; |
| glibc support has been provided since version 2.3. |
| .SH CONFORMING TO |
| The |
| .BR readahead () |
| system call is Linux-specific, and its use should be avoided |
| in portable applications. |
| .SH NOTES |
| On some 32-bit architectures, |
| the calling signature for this system call differs, |
| for the reasons described in |
| .BR syscall (2). |
| .SH BUGS |
| .BR readahead () |
| attempts to schedule the reads in the background and return immediately. |
| However, it may block while it reads the filesystem metadata needed |
| to locate the requested blocks. |
| This occurs frequently with ext[234] on large files |
| using indirect blocks instead of extents, |
| giving the appearance that the call blocks until the requested data has |
| been read. |
| .SH SEE ALSO |
| .BR lseek (2), |
| .BR madvise (2), |
| .BR mmap (2), |
| .BR posix_fadvise (2), |
| .BR read (2) |