1READ(3P)                   POSIX Programmer's Manual                  READ(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       pread, read — read from a file
14

SYNOPSIS

16       #include <unistd.h>
17
18       ssize_t pread(int fildes, void *buf, size_t nbyte, off_t offset);
19       ssize_t read(int fildes, void *buf, size_t nbyte);
20

DESCRIPTION

22       The read() function shall attempt to read nbyte  bytes  from  the  file
23       associated  with  the  open  file  descriptor,  fildes, into the buffer
24       pointed to by buf.  The behavior of multiple concurrent  reads  on  the
25       same pipe, FIFO, or terminal device is unspecified.
26
27       Before  any  action described below is taken, and if nbyte is zero, the
28       read() function may detect and return errors as described below. In the
29       absence  of  errors, or if error detection is not performed, the read()
30       function shall return zero and have no other results.
31
32       On files that support seeking (for example, a regular file), the read()
33       shall  start at a position in the file given by the file offset associ‐
34       ated with fildes.  The file offset shall be incremented by  the  number
35       of bytes actually read.
36
37       Files  that  do  not support seeking—for example, terminals—always read
38       from the current position. The value of a file offset  associated  with
39       such a file is undefined.
40
41       No  data  transfer  shall  occur  past  the current end-of-file. If the
42       starting position is at or after the end-of-file, 0 shall be  returned.
43       If  the  file refers to a device special file, the result of subsequent
44       read() requests is implementation-defined.
45
46       If the value of nbyte is greater than {SSIZE_MAX}, the result is imple‐
47       mentation-defined.
48
49       When attempting to read from an empty pipe or FIFO:
50
51        *  If  no process has the pipe open for writing, read() shall return 0
52           to indicate end-of-file.
53
54        *  If some process has the pipe open for  writing  and  O_NONBLOCK  is
55           set, read() shall return −1 and set errno to [EAGAIN].
56
57        *  If  some  process  has  the pipe open for writing and O_NONBLOCK is
58           clear, read() shall block the calling thread  until  some  data  is
59           written  or  the  pipe is closed by all processes that had the pipe
60           open for writing.
61
62       When attempting to read a file (other than a pipe or  FIFO)  that  sup‐
63       ports non-blocking reads and has no data currently available:
64
65        *  If  O_NONBLOCK  is  set,  read()  shall  return −1 and set errno to
66           [EAGAIN].
67
68        *  If O_NONBLOCK is clear, read() shall block the calling thread until
69           some data becomes available.
70
71        *  The  use of the O_NONBLOCK flag has no effect if there is some data
72           available.
73
74       The read() function reads data previously written to  a  file.  If  any
75       portion  of  a regular file prior to the end-of-file has not been writ‐
76       ten, read() shall return bytes  with  value  0.  For  example,  lseek()
77       allows the file offset to be set beyond the end of existing data in the
78       file. If data is later written at this point, subsequent reads  in  the
79       gap  between  the previous end of data and the newly written data shall
80       return bytes with value 0 until data is written into the gap.
81
82       Upon successful completion, where nbyte is greater than 0, read() shall
83       mark  for  update the last data access timestamp of the file, and shall
84       return the number of bytes read.  This number shall  never  be  greater
85       than nbyte.  The value returned may be less than nbyte if the number of
86       bytes left in the file is less than nbyte, if the  read()  request  was
87       interrupted  by  a  signal, or if the file is a pipe or FIFO or special
88       file and has fewer than nbyte bytes immediately available for  reading.
89       For example, a read() from a file associated with a terminal may return
90       one typed line of data.
91
92       If a read() is interrupted by a signal before it  reads  any  data,  it
93       shall return −1 with errno set to [EINTR].
94
95       If  a  read() is interrupted by a signal after it has successfully read
96       some data, it shall return the number of bytes read.
97
98       For regular files, no data transfer shall occur past the offset maximum
99       established in the open file description associated with fildes.
100
101       If fildes refers to a socket, read() shall be equivalent to recv() with
102       no flags set.
103
104       If the O_DSYNC and O_RSYNC bits have been set, read I/O  operations  on
105       the  file descriptor shall complete as defined by synchronized I/O data
106       integrity completion. If the O_SYNC and O_RSYNC  bits  have  been  set,
107       read I/O operations on the file descriptor shall complete as defined by
108       synchronized I/O file integrity completion.
109
110       If fildes refers to a shared memory object, the result  of  the  read()
111       function is unspecified.
112
113       If  fildes  refers  to  a typed memory object, the result of the read()
114       function is unspecified.
115
116       A read() from a STREAMS file can read data in  three  different  modes:
117       byte-stream  mode,  message-nondiscard  mode, and message-discard mode.
118       The default shall be byte-stream mode.  This can be changed  using  the
119       I_SRDOPT  ioctl() request, and can be tested with I_GRDOPT ioctl().  In
120       byte-stream mode, read() shall retrieve data from the STREAM  until  as
121       many bytes as were requested are transferred, or until there is no more
122       data to be retrieved.  Byte-stream mode ignores message boundaries.
123
124       In STREAMS message-nondiscard mode, read() shall retrieve data until as
125       many bytes as were requested are transferred, or until a message bound‐
126       ary is reached. If read() does not retrieve all the data in a  message,
127       the remaining data shall be left on the STREAM, and can be retrieved by
128       the next read() call. Message-discard mode also retrieves data until as
129       many  bytes as were requested are transferred, or a message boundary is
130       reached.  However, unread data remaining in a message after the  read()
131       returns shall be discarded, and shall not be available for a subsequent
132       read(), getmsg(), or getpmsg() call.
133
134       How read() handles zero-byte STREAMS messages is determined by the cur‐
135       rent  read  mode setting. In byte-stream mode, read() shall accept data
136       until it has read nbyte bytes, or until there is no more data to  read,
137       or  until a zero-byte message block is encountered. The read() function
138       shall then return the number of bytes read,  and  place  the  zero-byte
139       message  back  on  the  STREAM  to  be  retrieved  by  the next read(),
140       getmsg(), or getpmsg().  In message-nondiscard mode or  message-discard
141       mode,  a  zero-byte  message  shall  return  0 and the message shall be
142       removed from the STREAM. When a zero-byte message is read as the  first
143       message on a STREAM, the message shall be removed from the STREAM and 0
144       shall be returned, regardless of the read mode.
145
146       A read() from a STREAMS file shall return the data in  the  message  at
147       the  front  of  the  STREAM head read queue, regardless of the priority
148       band of the message.
149
150       By default, STREAMs are in control-normal mode, in which a read()  from
151       a  STREAMS  file can only process messages that contain a data part but
152       do not contain a control part. The read() shall fail if a message  con‐
153       taining  a control part is encountered at the STREAM head. This default
154       action can be changed by placing the STREAM in either control-data mode
155       or  control-discard mode with the I_SRDOPT ioctl() command. In control-
156       data mode, read() shall convert any control part to data and pass it to
157       the  application before passing any data part originally present in the
158       same message.  In control-discard mode, read()  shall  discard  message
159       control parts but return to the process any data part in the message.
160
161       In  addition,  read()  shall  fail  if the STREAM head had processed an
162       asynchronous error before the call. In this case, the  value  of  errno
163       shall not reflect the result of read(), but reflect the prior error. If
164       a hangup occurs on the STREAM being  read,  read()  shall  continue  to
165       operate normally until the STREAM head read queue is empty. Thereafter,
166       it shall return 0.
167
168       The pread() function shall be equivalent  to  read(),  except  that  it
169       shall  read from a given position in the file without changing the file
170       pointer. The first three arguments to pread() are the  same  as  read()
171       with  the addition of a fourth argument offset for the desired position
172       inside the file. An attempt to perform a pread()  on  a  file  that  is
173       incapable of seeking shall result in an error.
174

RETURN VALUE

176       Upon successful completion, these functions shall return a non-negative
177       integer indicating the number of bytes actually  read.  Otherwise,  the
178       functions shall return −1 and set errno to indicate the error.
179

ERRORS

181       These functions shall fail if:
182
183       EAGAIN The file is neither a pipe, nor a FIFO, nor a socket, the O_NON‐
184              BLOCK flag is set for the file descriptor, and the thread  would
185              be delayed in the read operation.
186
187       EBADF  The  fildes  argument  is  not  a valid file descriptor open for
188              reading.
189
190       EBADMSG
191              The file is a STREAM file that is set to control-normal mode and
192              the message waiting to be read includes a control part.
193
194       EINTR  The  read  operation was terminated due to the receipt of a sig‐
195              nal, and no data was transferred.
196
197       EINVAL The  STREAM  or  multiplexer  referenced  by  fildes  is  linked
198              (directly or indirectly) downstream from a multiplexer.
199
200       EIO    The process is a member of a background process group attempting
201              to read from its controlling terminal, and  either  the  calling
202              thread is blocking SIGTTIN or the process is ignoring SIGTTIN or
203              the process group of the process is  orphaned.  This  error  may
204              also be generated for implementation-defined reasons.
205
206       EISDIR The fildes argument refers to a directory and the implementation
207              does not allow the directory to be read using read() or pread().
208              The readdir() function should be used instead.
209
210       EOVERFLOW
211              The  file is a regular file, nbyte is greater than 0, the start‐
212              ing position is before the end-of-file, and the  starting  posi‐
213              tion  is greater than or equal to the offset maximum established
214              in the open file description associated with fildes.
215
216       The pread() function shall fail if:
217
218       EINVAL The file is a regular file or block special file, and the offset
219              argument is negative. The file pointer shall remain unchanged.
220
221       ESPIPE The file is a pipe, FIFO, or socket.
222
223       The read() function shall fail if:
224
225       EAGAIN The  file  is a pipe or FIFO, the O_NONBLOCK flag is set for the
226              file descriptor, and the thread would be  delayed  in  the  read
227              operation.
228
229       EAGAIN or EWOULDBLOCK
230              The  file  is  a socket, the O_NONBLOCK flag is set for the file
231              descriptor, and the thread would be delayed in the  read  opera‐
232              tion.
233
234       ECONNRESET
235              A read was attempted on a socket and the connection was forcibly
236              closed by its peer.
237
238       ENOTCONN
239              A read was attempted on a socket that is not connected.
240
241       ETIMEDOUT
242              A read was attempted on a  socket  and  a  transmission  timeout
243              occurred.
244
245       These functions may fail if:
246
247       EIO    A physical I/O error has occurred.
248
249       ENOBUFS
250              Insufficient  resources  were available in the system to perform
251              the operation.
252
253       ENOMEM Insufficient memory was available to fulfill the request.
254
255       ENXIO  A request was made of a nonexistent device, or the  request  was
256              outside the capabilities of the device.
257
258       The following sections are informative.
259

EXAMPLES

261   Reading Data into a Buffer
262       The following example reads data from the file associated with the file
263       descriptor fd into the buffer pointed to by buf.
264
265           #include <sys/types.h>
266           #include <unistd.h>
267           ...
268           char buf[20];
269           size_t nbytes;
270           ssize_t bytes_read;
271           int fd;
272           ...
273           nbytes = sizeof(buf);
274           bytes_read = read(fd, buf, nbytes);
275           ...
276

APPLICATION USAGE

278       None.
279

RATIONALE

281       This volume of POSIX.1‐2008 does not specify the value of the file off‐
282       set  after an error is returned; there are too many cases. For program‐
283       ming errors, such as [EBADF], the concept is meaningless since no  file
284       is  involved.  For  errors  that  are  detected  immediately,  such  as
285       [EAGAIN], clearly the pointer should not change. After an interrupt  or
286       hardware  error,  however, an updated value would be very useful and is
287       the behavior of many implementations.
288
289       Note that a read() of zero bytes does not modify the last  data  access
290       timestamp.  A  read()  that  requests more than zero bytes, but returns
291       zero, is required to modify the last data access timestamp.
292
293       Implementations are allowed, but not required, to perform error  check‐
294       ing for read() requests of zero bytes.
295
296   Input and Output
297       The  use  of  I/O with large byte counts has always presented problems.
298       Ideas such as lread() and lwrite() (using  and  returning  longs)  were
299       considered  at  one time. The current solution is to use abstract types
300       on the ISO C standard function to read()  and  write().   The  abstract
301       types  can be declared so that existing functions work, but can also be
302       declared so that larger types can be represented in future  implementa‐
303       tions. It is presumed that whatever constraints limit the maximum range
304       of size_t also limit portable I/O requests to the same range. This vol‐
305       ume of POSIX.1‐2008 also limits the range further by requiring that the
306       byte count be limited so that a signed return value remains meaningful.
307       Since  the return type is also a (signed) abstract type, the byte count
308       can be defined by the implementation to be larger than an int can hold.
309
310       The standard developers considered adding atomicity requirements  to  a
311       pipe  or FIFO, but recognized that due to the nature of pipes and FIFOs
312       there could be no guarantee of atomicity of reads of {PIPE_BUF} or  any
313       other size that would be an aid to applications portability.
314
315       This volume of POSIX.1‐2008 requires that no action be taken for read()
316       or write() when nbyte is zero. This is not intended to take  precedence
317       over  detection  of  errors  (such  as  invalid buffer pointers or file
318       descriptors). This is consistent  with  the  rest  of  this  volume  of
319       POSIX.1‐2008,  but the phrasing here could be misread to require detec‐
320       tion of the zero case before any other errors.  A value of zero  is  to
321       be considered a correct value, for which the semantics are a no-op.
322
323       I/O  is  intended  to  be atomic to ordinary files and pipes and FIFOs.
324       Atomic means that all the bytes from a single  operation  that  started
325       out together end up together, without interleaving from other I/O oper‐
326       ations. It is a known attribute of terminals that this is not  honored,
327       and  terminals  are  explicitly  (and implicitly permanently) excepted,
328       making the behavior unspecified. The behavior for other device types is
329       also left unspecified, but the wording is intended to imply that future
330       standards might choose to specify atomicity (or not).
331
332       There were recommendations to  add  format  parameters  to  read()  and
333       write() in order to handle networked transfers among heterogeneous file
334       system and base hardware types. Such a facility  may  be  required  for
335       support  by  the  OSI  presentation  of layer services. However, it was
336       determined that this should correspond with similar C-language  facili‐
337       ties,  and that is beyond the scope of this volume of POSIX.1‐2008. The
338       concept was suggested to the developers of the ISO C standard for their
339       consideration as a possible area for future work.
340
341       In  4.3 BSD, a read() or write() that is interrupted by a signal before
342       transferring any data does not by default return an [EINTR] error,  but
343       is  restarted. In 4.2 BSD, 4.3 BSD, and the Eighth Edition, there is an
344       additional function, select(), whose purpose is to pause  until  speci‐
345       fied  activity (data to read, space to write, and so on) is detected on
346       specified file descriptors. It is common in  applications  written  for
347       those systems for select() to be used before read() in situations (such
348       as keyboard input) where  interruption  of  I/O  due  to  a  signal  is
349       desired.
350
351       The  issue of which files or file types are interruptible is considered
352       an implementation design issue. This is  often  affected  primarily  by
353       hardware and reliability issues.
354
355       There  are  no references to actions taken following an ``unrecoverable
356       error''.  It  is  considered  beyond  the  scope  of  this  volume   of
357       POSIX.1‐2008 to describe what happens in the case of hardware errors.
358
359       Earlier  versions of this standard allowed two very different behaviors
360       with regard to the handling of interrupts. In  order  to  minimize  the
361       resulting  confusion,  it  was decided that POSIX.1‐2008 should support
362       only one of these behaviors. Historical practice on  AT&T-derived  sys‐
363       tems  was to have read() and write() return −1 and set errno to [EINTR]
364       when interrupted after some, but not all, of  the  data  requested  had
365       been transferred. However, the US Department of Commerce FIPS 151‐1 and
366       FIPS 151‐2 require the historical BSD behavior,  in  which  read()  and
367       write()  return  the  number  of  bytes actually transferred before the
368       interrupt.  If −1 is returned when any data is transferred, it is  dif‐
369       ficult to recover from the error on a seekable device and impossible on
370       a non-seekable device. Most new implementations support this  behavior.
371       The  behavior required by POSIX.1‐2008 is to return the number of bytes
372       transferred.
373
374       POSIX.1‐2008 does not  specify  when  an  implementation  that  buffers
375       read()s  actually  moves  the data into the user-supplied buffer, so an
376       implementation may choose to do this at  the  latest  possible  moment.
377       Therefore, an interrupt arriving earlier may not cause read() to return
378       a partial byte count, but rather to return −1 and set errno to [EINTR].
379
380       Consideration was also given to combining the two previous options, and
381       setting  errno  to  [EINTR] while returning a short count. However, not
382       only is there no existing practice that implements  this,  it  is  also
383       contradictory  to the idea that when errno is set, the function respon‐
384       sible shall return −1.
385
386       This volume of POSIX.1‐2008 intentionally does not specify any  pread()
387       errors related to pipes, FIFOs, and sockets other than [ESPIPE].
388

FUTURE DIRECTIONS

390       None.
391

SEE ALSO

393       fcntl(), ioctl(), lseek(), open(), pipe(), readv()
394
395       The Base Definitions volume of POSIX.1‐2008, Chapter 11, General Termi‐
396       nal Interface, <stropts.h>, <sys_uio.h>, <unistd.h>
397
399       Portions of this text are reprinted and reproduced in  electronic  form
400       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
401       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
402       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
403       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
404       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
405       event of any discrepancy between this version and the original IEEE and
406       The  Open Group Standard, the original IEEE and The Open Group Standard
407       is the referee document. The original Standard can be  obtained  online
408       at http://www.unix.org/online.html .
409
410       Any  typographical  or  formatting  errors that appear in this page are
411       most likely to have been introduced during the conversion of the source
412       files  to  man page format. To report such errors, see https://www.ker
413       nel.org/doc/man-pages/reporting_bugs.html .
414
415
416
417IEEE/The Open Group                  2013                             READ(3P)
Impressum