man/man2/read.2

   1 .\" Copyright (c) 1980 Regents of the University of California.
   2 .\" All rights reserved.  The Berkeley software License Agreement
   3 .\" specifies the terms and conditions for redistribution.
   4 .\"
   5 .\"     @(#)read.2      6.6 (Berkeley) 5/23/86
   6 .\"
   7 .TH READ 2 "May 23, 1986"
   8 .UC 4
   9 .SH NAME
  10 read, pread \- read input
  11 .SH SYNOPSIS
  12 .nf
  13 .ft B
  14 #include <sys/types.h>
  15 #include <unistd.h>
  16
  17 ssize_t read(int \fId\fP, void *\fIbuf\fP, size_t \fInbytes\fP)
  18 ssize_t pread(int \fId\fP, void *\fIbuf\fP, size_t \fInbytes\fP, off_t \fIoffset\fP)
  19 .fi
  20 .SH DESCRIPTION
  21 .B Read
  22 attempts to read
  23 .I nbytes
  24 of data from the object referenced by the descriptor
  25 .I d
  26 into the buffer pointed to by
  27 .IR buf .
  28 .PP
  29 On objects capable of seeking, the
  30 .B read
  31 starts at a position
  32 given by the pointer associated with
  33 .IR d
  34 (see
  35 .BR lseek (2)).
  36 Upon return from
  37 .BR read ,
  38 the pointer is incremented by the number of bytes actually read.
  39 .PP
  40 Objects that are not capable of seeking always read from the current
  41 position.  The value of the pointer associated with such an
  42 object is undefined.
  43 .PP
  44 Upon successful completion,
  45 .B read
  46 return the number of bytes actually read and placed in the buffer.
  47 The system guarantees to read the number of bytes requested if
  48 the descriptor references a normal file that has that many bytes left
  49 before the end-of-file, but in no other case.
  50 .PP
  51 If the returned value is 0, then
  52 end-of-file has been reached.
  53 .PP
  54 The
  55 .B pread
  56 system call performs the same functions, but reads from the specified
  57 position in the file without modifying the file pointer.
  58 .SH "RETURN VALUE
  59 If successful, the
  60 number of bytes actually read is returned.
  61 Otherwise, a \-1 is returned and the global variable
  62 .B errno
  63 is set to indicate the error.
  64 .SH "ERRORS
  65 .B Read
  66 and
  67 .B pread
  68 will fail if one or more of the following are true:
  69 .TP 15
  70 [EBADF]
  71 \fID\fP is not a valid descriptor open for reading.
  72 .TP 15
  73 [EFAULT]
  74 \fIBuf\fP points outside the allocated address space.
  75 .TP 15
  76 [EIO]
  77 An I/O error occurred while reading from the file system.
  78 .TP 15
  79 [EINTR]
  80 A read from a slow device was interrupted before
  81 any data arrived by the delivery of a signal.
  82 .TP 15
  83 [EAGAIN]
  84 The file was marked for non-blocking I/O,
  85 and no data were ready to be read.
  86 .PP
  87 The
  88 .B pread
  89 system call may also return any of the
  90 .B lseek
  91 errors.
  92 .SH "SEE ALSO"
  93 .BR dup (2),
  94 .BR fcntl (2),
  95 .BR open (2),
  96 .BR pipe (2),
  97 .BR lseek (2),
  98 .BR write (2).
  99 .SH NOTES
 100 .B pread
 101 is currently implemented as a library function instead of a system call.