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 \- 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 .fi
  19 .SH DESCRIPTION
  20 .B Read
  21 attempts to read
  22 .I nbytes
  23 of data from the object referenced by the descriptor
  24 .I d
  25 into the buffer pointed to by
  26 .IR buf .
  27 .PP
  28 On objects capable of seeking, the
  29 .B read
  30 starts at a position
  31 given by the pointer associated with
  32 .IR d
  33 (see
  34 .BR lseek (2)).
  35 Upon return from
  36 .BR read ,
  37 the pointer is incremented by the number of bytes actually read.
  38 .PP
  39 Objects that are not capable of seeking always read from the current
  40 position.  The value of the pointer associated with such an
  41 object is undefined.
  42 .PP
  43 Upon successful completion,
  44 .B read
  45 return the number of bytes actually read and placed in the buffer.
  46 The system guarantees to read the number of bytes requested if
  47 the descriptor references a normal file that has that many bytes left
  48 before the end-of-file, but in no other case.
  49 .PP
  50 If the returned value is 0, then
  51 end-of-file has been reached.
  52 .SH "RETURN VALUE
  53 If successful, the
  54 number of bytes actually read is returned.
  55 Otherwise, a \-1 is returned and the global variable
  56 .B errno
  57 is set to indicate the error.
  58 .SH "ERRORS
  59 .B Read
  60 will fail if one or more of the following are true:
  61 .TP 15
  62 [EBADF]
  63 \fID\fP is not a valid descriptor open for reading.
  64 .TP 15
  65 [EFAULT]
  66 \fIBuf\fP points outside the allocated address space.
  67 .TP 15
  68 [EIO]
  69 An I/O error occurred while reading from the file system.
  70 .TP 15
  71 [EINTR]
  72 A read from a slow device was interrupted before
  73 any data arrived by the delivery of a signal.
  74 .TP 15
  75 [EAGAIN]
  76 The file was marked for non-blocking I/O,
  77 and no data were ready to be read.
  78 .SH "SEE ALSO"
  79 .BR dup (2),
  80 .BR fcntl (2),
  81 .BR open (2),
  82 .BR pipe (2),
  83 .BR write (2).