pread(2) - f39

1pread(2)                      System Calls Manual                     pread(2)
2
3
4

NAME

6       pread, pwrite - read from or write to a file descriptor at a given off‐
7       set
8

LIBRARY

10       Standard C library (libc, -lc)
11

SYNOPSIS

13       #include <unistd.h>
14
15       ssize_t pread(int fd, void buf[.count], size_t count,
16                     off_t offset);
17       ssize_t pwrite(int fd, const void buf[.count], size_t count,
18                     off_t offset);
19
20   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
21
22       pread(), pwrite():
23           _XOPEN_SOURCE >= 500
24               || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
25

DESCRIPTION

27       pread() reads up to count bytes from file descriptor fd at offset  off‐
28       set  (from the start of the file) into the buffer starting at buf.  The
29       file offset is not changed.
30
31       pwrite() writes up to count bytes from the buffer starting  at  buf  to
32       the  file  descriptor  fd  at  offset  offset.   The file offset is not
33       changed.
34
35       The file referenced by fd must be capable of seeking.
36

RETURN VALUE

38       On success, pread() returns the number of bytes read (a return of  zero
39       indicates  end  of file) and pwrite() returns the number of bytes writ‐
40       ten.
41
42       Note that it is not an error for a successful call  to  transfer  fewer
43       bytes than requested (see read(2) and write(2)).
44
45       On error, -1 is returned and errno is set to indicate the error.
46

ERRORS

48       pread()  can  fail  and set errno to any error specified for read(2) or
49       lseek(2).  pwrite() can fail and set errno to any error  specified  for
50       write(2) or lseek(2).
51

STANDARDS

53       POSIX.1-2008.
54

HISTORY

56       POSIX.1-2001.
57
58       Added  in  Linux 2.1.60; the entries in the i386 system call table were
59       added in Linux 2.1.69.  C library support  (including  emulation  using
60       lseek(2)  on older kernels without the system calls) was added in glibc
61       2.1.
62
63   C library/kernel differences
64       On Linux, the underlying  system  calls  were  renamed  in  Linux  2.6:
65       pread()  became  pread64(), and pwrite() became pwrite64().  The system
66       call numbers remained the same.  The glibc pread() and pwrite() wrapper
67       functions transparently deal with the change.
68
69       On  some  32-bit  architectures, the calling signature for these system
70       calls differ, for the reasons described in syscall(2).
71

NOTES

73       The pread() and pwrite() system calls are especially useful  in  multi‐
74       threaded  applications.   They allow multiple threads to perform I/O on
75       the same file descriptor without being affected by changes to the  file
76       offset by other threads.
77

BUGS

79       POSIX  requires  that opening a file with the O_APPEND flag should have
80       no effect on the location at which pwrite() writes data.   However,  on
81       Linux,  if a file is opened with O_APPEND, pwrite() appends data to the
82       end of the file, regardless of the value of offset.
83