Debian Codegraph @

upstream/debian-unstable/man2/readahead.2

raw
1 .\" Copyright 2004, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH readahead 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 readahead \- initiate file readahead into page cache
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
15 .B #define _FILE_OFFSET_BITS 64
16 .B #include <fcntl.h>
17 .P
18 .BI "ssize_t readahead(int " fd ", off_t " offset ", size_t " count );
19 .fi
20 .SH DESCRIPTION
21 .BR readahead ()
22 initiates readahead on a file so that subsequent reads from that file will
23 be satisfied from the cache, and not block on disk I/O
24 (assuming the readahead was initiated early enough and that other activity
25 on the system did not in the meantime flush pages from the cache).
26 .P
27 The
28 .I fd
29 argument is a file descriptor identifying the file which is
30 to be read.
31 The
32 .I offset
33 argument specifies the starting point from which data is to be read
34 and
35 .I count
36 specifies the number of bytes to be read.
37 I/O is performed in whole pages, so that
38 .I offset
39 is effectively rounded down to a page boundary
40 and bytes are read up to the next page boundary greater than or
41 equal to
42 .IR "(offset+count)" .
43 .BR readahead ()
44 does not read beyond the end of the file.
45 The file offset of the open file description referred to by the file descriptor
46 .I fd
47 is left unchanged.
48 .SH RETURN VALUE
49 On success,
50 .BR readahead ()
51 returns 0;
52 on failure, \-1 is returned, and
53 .I errno
54 is set to indicate the error.
55 .SH ERRORS
56 .TP
57 .B EBADF
58 .I fd
59 is not a valid file descriptor or is not open for reading.
60 .TP
61 .B EINVAL
62 .I fd
63 does not refer to a file type to which
64 .BR readahead ()
65 can be applied.
66 .SH VERSIONS
67 On some 32-bit architectures,
68 the calling signature for this system call differs,
69 for the reasons described in
70 .BR syscall (2).
71 .SH STANDARDS
72 Linux.
73 .SH HISTORY
74 Linux 2.4.13,
75 glibc 2.3.
76 .SH NOTES
77 .B _FILE_OFFSET_BITS
78 should be defined to be 64 in code that uses a pointer to
79 .BR readahead ,
80 if the code is intended to be portable
81 to traditional 32-bit x86 and ARM platforms where
82 .BR off_t 's
83 width defaults to 32 bits.
84 .SH BUGS
85 .BR readahead ()
86 attempts to schedule the reads in the background and return immediately.
87 However, it may block while it reads the filesystem metadata needed
88 to locate the requested blocks.
89 This occurs frequently with ext[234] on large files
90 using indirect blocks instead of extents,
91 giving the appearance that the call blocks until the requested data has
92 been read.
93 .SH SEE ALSO
94 .BR lseek (2),
95 .BR madvise (2),
96 .BR mmap (2),
97 .BR posix_fadvise (2),
98 .BR read (2)