Debian Codegraph @

upstream/debian-trixie/man2/pread.2

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