dlopen.3: tfix

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

diff --git a/man2/pread.2 b/man2/pread.2
index ecb0d9505af617cd2bb2cf51c0fe290655ac3472..edd8bb3e9b1b5f04675d6b1f131f4488e07e0e2e 100644 (file)
--- a/man2/pread.2
+++ b/man2/pread.2
@@ -1,5 +1,6 @@
 .\" Copyright (C) 1999 Joseph Samuel Myers.
 .\"
+.\" %%%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.
@@ -19,26 +20,27 @@
 .\"
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
 .\"
-.TH PREAD 2 2010-09-26 "Linux" "Linux Programmer's Manual"
+.TH PREAD 2 2017-09-15 "Linux" "Linux Programmer's Manual"
 .SH NAME
 pread, pwrite \- read from or write to a file descriptor at a given offset
 .SH SYNOPSIS
 .B #include <unistd.h>
-.sp
+.PP
 .BI "ssize_t pread(int " fd ", void *" buf ", size_t " count \
 ", off_t " offset );
-.sp
+.PP
 .BI "ssize_t pwrite(int " fd ", const void *" buf ", size_t " count \
 ", off_t " offset );
-.sp
+.PP
 .in -4n
 Feature Test Macro Requirements for glibc (see
 .BR feature_test_macros (7)):
 .in
+.PP
 .PD 0
 .ad l
-.sp
 .BR pread (),
 .BR pwrite ():
 .RS 4
@@ -74,16 +76,24 @@ The file offset is not changed.
 The file referenced by
 .I fd
 must be capable of seeking.
-.SH "RETURN VALUE"
-On success, the number of bytes read or written is returned (zero
-indicates that nothing was written, in the case of
-.BR pwrite (),
-or
-end of file, in the case of
-.BR pread ()),
-or \-1 on error, in which case
+.SH RETURN VALUE
+On success,
+.BR pread ()
+returns the number of bytes read
+(a return of zero indicates end of file)
+and
+.BR pwrite ()
+returns the number of bytes written.
+.PP
+Note that it is not an error for a successful call to transfer fewer bytes
+than requested (see
+.BR read (2)
+and
+.BR write (2)).
+.PP
+On error, \-1 is returned and
 .I errno
-is set to indicate the error.
+is set to indicate the cause of the error.
 .SH ERRORS
 .BR pread ()
 can fail and set
@@ -110,10 +120,52 @@ in 2.1.69.
 C library support (including emulation using
 .BR lseek (2)
 on older kernels without the system calls) was added in glibc 2.1.
-.SH "CONFORMING TO"
-POSIX.1-2001.
-.SH "SEE ALSO"
+.SH CONFORMING TO
+POSIX.1-2001, POSIX.1-2008.
+.SH NOTES
+The
+.BR pread ()
+and
+.BR pwrite ()
+system calls are especially useful in multithreaded applications.
+They allow multiple threads to perform I/O on the same file descriptor
+without being affected by changes to the file offset by other threads.
+.\"
+.SS C library/kernel differences
+On Linux, the underlying system calls were renamed
+in kernel 2.6:
+.BR pread ()
+became
+.BR pread64 (),
+and
+.BR pwrite ()
+became
+.BR pwrite64 ().
+The system call numbers remained the same.
+The glibc
+.BR pread ()
+and
+.BR pwrite ()
+wrapper functions transparently deal with the change.
+.PP
+On some 32-bit architectures,
+the calling signature for these system calls differ,
+for the reasons described in
+.BR syscall (2).
+.SH BUGS
+POSIX requires that opening a file with the
+.BR O_APPEND
+flag should have no effect on the location at which
+.BR pwrite ()
+writes data.
+However, on Linux, if a file is opened with
+.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=43178
+.BR O_APPEND ,
+.BR pwrite ()
+appends data to the end of the file, regardless of the value of
+.IR offset .
+.SH SEE ALSO
 .BR lseek (2),
 .BR read (2),
-.BR write (2),
-.BR feature_test_macros (7)
+.BR readv (2),
+.BR write (2)