dlopen.3: tfix

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

diff --git a/man2/pread.2 b/man2/pread.2
index 9c7d8437c29e616218cee58c12a4d6ea81ec8aa7..edd8bb3e9b1b5f04675d6b1f131f4488e07e0e2e 100644 (file)
--- a/man2/pread.2
+++ b/man2/pread.2
@@ -1,6 +1,6 @@
 .\" Copyright (C) 1999 Joseph Samuel Myers.
 .\"
-.\" %%%LICENSE_START(verbatim)
+.\" %%%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.
@@ -22,25 +22,25 @@
 .\" the source, must acknowledge the copyright and authors of this work.
 .\" %%%LICENSE_END
 .\"
-.TH PREAD 2 2012-04-30 "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
@@ -77,15 +77,23 @@ 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
+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
@@ -113,8 +121,17 @@ 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.
+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 ()
@@ -130,14 +147,19 @@ The glibc
 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 affect on the location at which
+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
+.\" 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