man2/pread.2

   1 .\" Copyright (C) 1999 Joseph Samuel Myers.
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .TH PREAD 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 pread, pwrite \- read from or write to a file descriptor at a given offset
  28 .SH SYNOPSIS
  29 .nf
  30 .B #include <unistd.h>
  31 .PP
  32 .BI "ssize_t pread(int " fd ", void *" buf ", size_t " count \
  33 ", off_t " offset );
  34 .BI "ssize_t pwrite(int " fd ", const void *" buf ", size_t " count \
  35 ", off_t " offset );
  36 .fi
  37 .PP
  38 .RS -4
  39 Feature Test Macro Requirements for glibc (see
  40 .BR feature_test_macros (7)):
  41 .RE
  42 .PP
  43 .BR pread (),
  44 .BR pwrite ():
  45 .nf
  46     _XOPEN_SOURCE >= 500
  47         || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
  48 .fi
  49 .SH DESCRIPTION
  50 .BR pread ()
  51 reads up to
  52 .I count
  53 bytes from file descriptor
  54 .I fd
  55 at offset
  56 .I offset
  57 (from the start of the file) into the buffer starting at
  58 .IR buf .
  59 The file offset is not changed.
  60 .PP
  61 .BR pwrite ()
  62 writes up to
  63 .I count
  64 bytes from the buffer starting at
  65 .I buf
  66 to the file descriptor
  67 .I fd
  68 at offset
  69 .IR offset .
  70 The file offset is not changed.
  71 .PP
  72 The file referenced by
  73 .I fd
  74 must be capable of seeking.
  75 .SH RETURN VALUE
  76 On success,
  77 .BR pread ()
  78 returns the number of bytes read
  79 (a return of zero indicates end of file)
  80 and
  81 .BR pwrite ()
  82 returns the number of bytes written.
  83 .PP
  84 Note that it is not an error for a successful call to transfer fewer bytes
  85 than requested (see
  86 .BR read (2)
  87 and
  88 .BR write (2)).
  89 .PP
  90 On error, \-1 is returned and
  91 .I errno
  92 is set to indicate the error.
  93 .SH ERRORS
  94 .BR pread ()
  95 can fail and set
  96 .I errno
  97 to any error specified for
  98 .BR read (2)
  99 or
 100 .BR lseek (2).
 101 .BR pwrite ()
 102 can fail and set
 103 .I errno
 104 to any error specified for
 105 .BR write (2)
 106 or
 107 .BR lseek (2).
 108 .SH VERSIONS
 109 The
 110 .BR pread ()
 111 and
 112 .BR pwrite ()
 113 system calls were added to Linux in
 114 version 2.1.60; the entries in the i386 system call table were added
 115 in 2.1.69.
 116 C library support (including emulation using
 117 .BR lseek (2)
 118 on older kernels without the system calls) was added in glibc 2.1.
 119 .SH CONFORMING TO
 120 POSIX.1-2001, POSIX.1-2008.
 121 .SH NOTES
 122 The
 123 .BR pread ()
 124 and
 125 .BR pwrite ()
 126 system calls are especially useful in multithreaded applications.
 127 They allow multiple threads to perform I/O on the same file descriptor
 128 without being affected by changes to the file offset by other threads.
 129 .\"
 130 .SS C library/kernel differences
 131 On Linux, the underlying system calls were renamed
 132 in kernel 2.6:
 133 .BR pread ()
 134 became
 135 .BR pread64 (),
 136 and
 137 .BR pwrite ()
 138 became
 139 .BR pwrite64 ().
 140 The system call numbers remained the same.
 141 The glibc
 142 .BR pread ()
 143 and
 144 .BR pwrite ()
 145 wrapper functions transparently deal with the change.
 146 .PP
 147 On some 32-bit architectures,
 148 the calling signature for these system calls differ,
 149 for the reasons described in
 150 .BR syscall (2).
 151 .SH BUGS
 152 POSIX requires that opening a file with the
 153 .BR O_APPEND
 154 flag should have no effect on the location at which
 155 .BR pwrite ()
 156 writes data.
 157 However, on Linux, if a file is opened with
 158 .\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=43178
 159 .BR O_APPEND ,
 160 .BR pwrite ()
 161 appends data to the end of the file, regardless of the value of
 162 .IR offset .
 163 .SH SEE ALSO
 164 .BR lseek (2),
 165 .BR read (2),
 166 .BR readv (2),
 167 .BR write (2)