| 1 |
.\" Copyright 1999, Joseph Samuel Myers <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH pread 2 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
pread, pwrite \- read from or write to a file descriptor at a given offset |
| 9 |
.SH LIBRARY |
| 10 |
Standard C library |
| 11 |
.RI ( libc ,\~ \-lc ) |
| 12 |
.SH SYNOPSIS |
| 13 |
.nf |
| 14 |
.B #include <unistd.h> |
| 15 |
.P |
| 16 |
.BR "ssize_t pread(" "size_t count;" |
| 17 |
.BI " int " fd ", void " buf [ count "], size_t " count , |
| 18 |
.BI " off_t " offset ); |
| 19 |
.BR "ssize_t pwrite(" "size_t count;" |
| 20 |
.BI " int " fd ", const void " buf [ count "], size_t " count , |
| 21 |
.BI " off_t " offset ); |
| 22 |
.fi |
| 23 |
.P |
| 24 |
.RS -4 |
| 25 |
Feature Test Macro Requirements for glibc (see |
| 26 |
.BR feature_test_macros (7)): |
| 27 |
.RE |
| 28 |
.P |
| 29 |
.BR pread (), |
| 30 |
.BR pwrite (): |
| 31 |
.nf |
| 32 |
_XOPEN_SOURCE >= 500 |
| 33 |
|| /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L |
| 34 |
.fi |
| 35 |
.SH DESCRIPTION |
| 36 |
.BR pread () |
| 37 |
reads up to |
| 38 |
.I count |
| 39 |
bytes from file descriptor |
| 40 |
.I fd |
| 41 |
at offset |
| 42 |
.I offset |
| 43 |
(from the start of the file) into the buffer starting at |
| 44 |
.IR buf . |
| 45 |
The file offset is not changed. |
| 46 |
.P |
| 47 |
.BR pwrite () |
| 48 |
writes up to |
| 49 |
.I count |
| 50 |
bytes from the buffer starting at |
| 51 |
.I buf |
| 52 |
to the file descriptor |
| 53 |
.I fd |
| 54 |
at offset |
| 55 |
.IR offset . |
| 56 |
The file offset is not changed. |
| 57 |
.P |
| 58 |
The file referenced by |
| 59 |
.I fd |
| 60 |
must be capable of seeking. |
| 61 |
.SH RETURN VALUE |
| 62 |
On success, |
| 63 |
.BR pread () |
| 64 |
returns the number of bytes read |
| 65 |
(a return of zero indicates end of file) |
| 66 |
and |
| 67 |
.BR pwrite () |
| 68 |
returns the number of bytes written. |
| 69 |
.P |
| 70 |
Note that it is not an error for a successful call to transfer fewer bytes |
| 71 |
than requested (see |
| 72 |
.BR read (2) |
| 73 |
and |
| 74 |
.BR write (2)). |
| 75 |
.P |
| 76 |
On error, \-1 is returned and |
| 77 |
.I errno |
| 78 |
is set to indicate the error. |
| 79 |
.SH ERRORS |
| 80 |
.BR pread () |
| 81 |
can fail and set |
| 82 |
.I errno |
| 83 |
to any error specified for |
| 84 |
.BR read (2) |
| 85 |
or |
| 86 |
.BR lseek (2). |
| 87 |
.BR pwrite () |
| 88 |
can fail and set |
| 89 |
.I errno |
| 90 |
to any error specified for |
| 91 |
.BR write (2) |
| 92 |
or |
| 93 |
.BR lseek (2). |
| 94 |
.SH STANDARDS |
| 95 |
POSIX.1-2024. |
| 96 |
.SH HISTORY |
| 97 |
POSIX.1-2001. |
| 98 |
.P |
| 99 |
Added in Linux 2.1.60; |
| 100 |
the entries in the i386 system call table were added in Linux 2.1.69. |
| 101 |
C library support (including emulation using |
| 102 |
.BR lseek (2) |
| 103 |
on older kernels without the system calls) was added in glibc 2.1. |
| 104 |
.SS C library/kernel differences |
| 105 |
On Linux, the underlying system calls were renamed |
| 106 |
in Linux 2.6: |
| 107 |
.BR pread () |
| 108 |
became |
| 109 |
.BR pread64 (), |
| 110 |
and |
| 111 |
.BR pwrite () |
| 112 |
became |
| 113 |
.BR pwrite64 (). |
| 114 |
The system call numbers remained the same. |
| 115 |
The glibc |
| 116 |
.BR pread () |
| 117 |
and |
| 118 |
.BR pwrite () |
| 119 |
wrapper functions transparently deal with the change. |
| 120 |
.P |
| 121 |
On some 32-bit architectures, |
| 122 |
the calling signature for these system calls differ, |
| 123 |
for the reasons described in |
| 124 |
.BR syscall (2). |
| 125 |
.SH NOTES |
| 126 |
The |
| 127 |
.BR pread () |
| 128 |
and |
| 129 |
.BR pwrite () |
| 130 |
system calls are especially useful in multithreaded applications. |
| 131 |
They allow multiple threads to perform I/O on the same file descriptor |
| 132 |
without being affected by changes to the file offset by other threads. |
| 133 |
.SH BUGS |
| 134 |
POSIX requires that opening a file with the |
| 135 |
.B O_APPEND |
| 136 |
flag should have no effect on the location at which |
| 137 |
.BR pwrite () |
| 138 |
writes data. |
| 139 |
However, on Linux, if a file is opened with |
| 140 |
.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=43178 |
| 141 |
.BR O_APPEND , |
| 142 |
.BR pwrite () |
| 143 |
appends data to the end of the file, regardless of the value of |
| 144 |
.IR offset . |
| 145 |
.SH SEE ALSO |
| 146 |
.BR lseek (2), |
| 147 |
.BR read (2), |
| 148 |
.BR readv (2), |
| 149 |
.BR write (2) |