Debian Codegraph @

upstream/debian-unstable/man2/pread.2

raw
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)