rename.2: tfix

[thirdparty/man-pages.git] / man2 / readahead.2

diff --git a/man2/readahead.2 b/man2/readahead.2
index bf129042fda0d697e704ca3e70cadf9f0a9ca5ff..c551d877148f551601c2b8a9b795230e3dc47674 100644 (file)
--- a/man2/readahead.2
+++ b/man2/readahead.2
@@ -1,7 +1,6 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\"
 .\" 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.
@@ -14,28 +13,35 @@
 .\" 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 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 2007-07-26 "Linux" "Linux Programmer's Manual"
+.TH READAHEAD 2 2019-03-06 "Linux" "Linux Programmer's Manual"
 .SH NAME
-readahead \- perform file readahead into page cache
+readahead \- initiate file readahead into page cache
 .SH SYNOPSIS
 .nf
-.B #define _GNU_SOURCE
+.BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
 .B #include <fcntl.h>
-.sp
+.PP
 .BI "ssize_t readahead(int " fd ", off64_t " offset ", size_t " count );
 .fi
 .SH DESCRIPTION
 .BR readahead ()
-populates the page cache with data from a file so that subsequent
-reads from that file will not block on disk I/O.
+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
@@ -54,12 +60,10 @@ equal to
 .IR "(offset+count)" .
 .BR readahead ()
 does not read beyond the end of the file.
-.BR readahead ()
-blocks until the specified data has been read.
-The current file offset of the open file referred to by
+The file offset of the open file description referred to by the file descriptor
 .I fd
 is left unchanged.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
 On success,
 .BR readahead ()
 returns 0; on failure, \-1 is returned, with
@@ -81,12 +85,26 @@ The
 .BR readahead ()
 system call appeared in Linux 2.4.13;
 glibc support has been provided since version 2.3.
-.SH "CONFORMING TO"
+.SH CONFORMING TO
 The
 .BR readahead ()
 system call is Linux-specific, and its use should be avoided
 in portable applications.
-.SH "SEE ALSO"
+.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),