man2/pread.2

   1 .\" Copyright (C) 1999 Joseph Samuel Myers.
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .TH PREAD 2 2008-12-03 "Linux" "Linux Programmer's Manual"
  24 .SH NAME
  25 pread, pwrite \- read from or write to a file descriptor at a given offset
  26 .SH SYNOPSIS
  27 .B #include <unistd.h>
  28 .sp
  29 .BI "ssize_t pread(int " fd ", void *" buf ", size_t " count \
  30 ", off_t " offset );
  31 .sp
  32 .BI "ssize_t pwrite(int " fd ", const void *" buf ", size_t " count \
  33 ", off_t " offset );
  34 .sp
  35 .in -4n
  36 Feature Test Macro Requirements for glibc (see
  37 .BR feature_test_macros (7)):
  38 .in
  39 .PD 0
  40 .ad l
  41 .sp
  42 .BR pread (),
  43 .BR pwrite ():
  44 .RS 4
  45 .TP 4
  46 Since glibc 2.12:
  47 _XOPEN_SOURCE\ >=\ 500 || _POSIX_C_SOURCE\ >=\ 200809L
  48 .TP
  49 Before glibc 2.12:
  50 _XOPEN_SOURCE\ >=\ 500
  51 .RE
  52 .ad
  53 .PD
  54 .SH DESCRIPTION
  55 .BR pread ()
  56 reads up to
  57 .I count
  58 bytes from file descriptor
  59 .I fd
  60 at offset
  61 .I offset
  62 (from the start of the file) into the buffer starting at
  63 .IR buf .
  64 The file offset is not changed.
  65 .PP
  66 .BR pwrite ()
  67 writes up to
  68 .I count
  69 bytes from the buffer starting at
  70 .I buf
  71 to the file descriptor
  72 .I fd
  73 at offset
  74 .IR offset .
  75 The file offset is not changed.
  76 .PP
  77 The file referenced by
  78 .I fd
  79 must be capable of seeking.
  80 .SH "RETURN VALUE"
  81 On success, the number of bytes read or written is returned (zero
  82 indicates that nothing was written, in the case of
  83 .BR pwrite (),
  84 or
  85 end of file, in the case of
  86 .BR pread ()),
  87 or \-1 on error, in which case
  88 .I errno
  89 is set to indicate the error.
  90 .SH ERRORS
  91 .BR pread ()
  92 can fail and set
  93 .I errno
  94 to any error specified for
  95 .BR read (2)
  96 or
  97 .BR lseek (2).
  98 .BR pwrite ()
  99 can fail and set
 100 .I errno
 101 to any error specified for
 102 .BR write (2)
 103 or
 104 .BR lseek (2).
 105 .SH VERSIONS
 106 The
 107 .BR pread ()
 108 and
 109 .BR pwrite ()
 110 system calls were added to Linux in
 111 version 2.1.60; the entries in the i386 system call table were added
 112 in 2.1.69.
 113 C library support (including emulation using
 114 .BR lseek (2)
 115 on older kernels without the system calls) was added in glibc 2.1.
 116 .SH "CONFORMING TO"
 117 POSIX.1-2001.
 118 .SH "SEE ALSO"
 119 .BR lseek (2),
 120 .BR read (2),
 121 .BR write (2),
 122 .BR feature_test_macros (7)