READ(3)                    POSIX Programmer's Manual                   READ(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       pread, read -- read from a file

SSYYNNOOPPSSIISS
       #include <unistd.h>

       ssize_t pread(int _f_i_l_d_e_s, void *_b_u_f, size_t _n_b_y_t_e, off_t _o_f_f_s_e_t);
       ssize_t read(int _f_i_l_d_e_s, void *_b_u_f, size_t _n_b_y_t_e);

DDEESSCCRRIIPPTTIIOONN
       The _r_e_a_d() function shall attempt to read _n_b_y_t_e bytes from the file
       associated with the open file descriptor, _f_i_l_d_e_s, into the buffer
       pointed to by _b_u_f.  The behavior of multiple concurrent reads on the
       same pipe, FIFO, or terminal device is unspecified.

       Before any action described below is taken, and if _n_b_y_t_e is zero, the
       _r_e_a_d() function may detect and return errors as described below. In the
       absence of errors, or if error detection is not performed, the _r_e_a_d()
       function shall return zero and have no other results.

       On files that support seeking (for example, a regular file), the _r_e_a_d()
       shall start at a position in the file given by the file offset
       associated with _f_i_l_d_e_s.  The file offset shall be incremented by the
       number of bytes actually read.

       Files that do not support seeking--for example, terminals--always read
       from the current position. The value of a file offset associated with
       such a file is undefined.

       No data transfer shall occur past the current end-of-file. If the
       starting position is at or after the end-of-file, 0 shall be returned.
       If the file refers to a device special file, the result of subsequent
       _r_e_a_d() requests is implementation-defined.

       If the value of _n_b_y_t_e is greater than {SSIZE_MAX}, the result is
       implementation-defined.

       When attempting to read from an empty pipe or FIFO:

        *  If no process has the pipe open for writing, _r_e_a_d() shall return 0
           to indicate end-of-file.

        *  If some process has the pipe open for writing and O_NONBLOCK is
           set, _r_e_a_d() shall return -1 and set _e_r_r_n_o to [[EEAAGGAAIINN]].

        *  If some process has the pipe open for writing and O_NONBLOCK is
           clear, _r_e_a_d() shall block the calling thread until some data is
           written or the pipe is closed by all processes that had the pipe
           open for writing.

       When attempting to read a file (other than a pipe or FIFO) that
       supports non-blocking reads and has no data currently available:

        *  If O_NONBLOCK is set, _r_e_a_d() shall return -1 and set _e_r_r_n_o to
           [[EEAAGGAAIINN]].

        *  If O_NONBLOCK is clear, _r_e_a_d() shall block the calling thread until
           some data becomes available.

        *  The use of the O_NONBLOCK flag has no effect if there is some data
           available.

       The _r_e_a_d() function reads data previously written to a file. If any
       portion of a regular file prior to the end-of-file has not been
       written, _r_e_a_d() shall return bytes with value 0. For example, _l_s_e_e_k()
       allows the file offset to be set beyond the end of existing data in the
       file. If data is later written at this point, subsequent reads in the
       gap between the previous end of data and the newly written data shall
       return bytes with value 0 until data is written into the gap.

       Upon successful completion, where _n_b_y_t_e is greater than 0, _r_e_a_d() shall
       mark for update the last data access timestamp of the file, and shall
       return the number of bytes read.  This number shall never be greater
       than _n_b_y_t_e.  The value returned may be less than _n_b_y_t_e if the number of
       bytes left in the file is less than _n_b_y_t_e, if the _r_e_a_d() request was
       interrupted by a signal, or if the file is a pipe or FIFO or special
       file and has fewer than _n_b_y_t_e bytes immediately available for reading.
       For example, a _r_e_a_d() from a file associated with a terminal may return
       one typed line of data.

       If a _r_e_a_d() is interrupted by a signal before it reads any data, it
       shall return -1 with _e_r_r_n_o set to [[EEIINNTTRR]].

       If a _r_e_a_d() is interrupted by a signal after it has successfully read
       some data, it shall return the number of bytes read.

       For regular files, no data transfer shall occur past the offset maximum
       established in the open file description associated with _f_i_l_d_e_s.

       If _f_i_l_d_e_s refers to a socket, _r_e_a_d() shall be equivalent to _r_e_c_v() with
       no flags set.

       If the O_DSYNC and O_RSYNC bits have been set, read I/O operations on
       the file descriptor shall complete as defined by synchronized I/O data
       integrity completion. If the O_SYNC and O_RSYNC bits have been set,
       read I/O operations on the file descriptor shall complete as defined by
       synchronized I/O file integrity completion.

       If _f_i_l_d_e_s refers to a shared memory object, the result of the _r_e_a_d()
       function is unspecified.

       If _f_i_l_d_e_s refers to a typed memory object, the result of the _r_e_a_d()
       function is unspecified.

       A _r_e_a_d() from a STREAMS file can read data in three different modes:
       _b_y_t_e_-_s_t_r_e_a_m mode, _m_e_s_s_a_g_e_-_n_o_n_d_i_s_c_a_r_d mode, and _m_e_s_s_a_g_e_-_d_i_s_c_a_r_d mode.
       The default shall be byte-stream mode.  This can be changed using the
       I_SRDOPT _i_o_c_t_l() request, and can be tested with I_GRDOPT _i_o_c_t_l().  In
       byte-stream mode, _r_e_a_d() shall retrieve data from the STREAM until as
       many bytes as were requested are transferred, or until there is no more
       data to be retrieved.  Byte-stream mode ignores message boundaries.

       In STREAMS message-nondiscard mode, _r_e_a_d() shall retrieve data until as
       many bytes as were requested are transferred, or until a message
       boundary is reached. If _r_e_a_d() does not retrieve all the data in a
       message, the remaining data shall be left on the STREAM, and can be
       retrieved by the next _r_e_a_d() call. Message-discard mode also retrieves
       data until as many bytes as were requested are transferred, or a
       message boundary is reached.  However, unread data remaining in a
       message after the _r_e_a_d() returns shall be discarded, and shall not be
       available for a subsequent _r_e_a_d(), _g_e_t_m_s_g(), or _g_e_t_p_m_s_g() call.

       How _r_e_a_d() handles zero-byte STREAMS messages is determined by the
       current read mode setting. In byte-stream mode, _r_e_a_d() shall accept
       data until it has read _n_b_y_t_e bytes, or until there is no more data to
       read, or until a zero-byte message block is encountered. The _r_e_a_d()
       function shall then return the number of bytes read, and place the
       zero-byte message back on the STREAM to be retrieved by the next
       _r_e_a_d(), _g_e_t_m_s_g(), or _g_e_t_p_m_s_g().  In message-nondiscard mode or message-
       discard mode, a zero-byte message shall return 0 and the message shall
       be removed from the STREAM. When a zero-byte message is read as the
       first message on a STREAM, the message shall be removed from the STREAM
       and 0 shall be returned, regardless of the read mode.

       A _r_e_a_d() from a STREAMS file shall return the data in the message at
       the front of the STREAM head read queue, regardless of the priority
       band of the message.

       By default, STREAMs are in control-normal mode, in which a _r_e_a_d() from
       a STREAMS file can only process messages that contain a data part but
       do not contain a control part. The _r_e_a_d() shall fail if a message
       containing a control part is encountered at the STREAM head. This
       default action can be changed by placing the STREAM in either control-
       data mode or control-discard mode with the I_SRDOPT _i_o_c_t_l() command. In
       control-data mode, _r_e_a_d() shall convert any control part to data and
       pass it to the application before passing any data part originally
       present in the same message.  In control-discard mode, _r_e_a_d() shall
       discard message control parts but return to the process any data part
       in the message.

       In addition, _r_e_a_d() shall fail if the STREAM head had processed an
       asynchronous error before the call. In this case, the value of _e_r_r_n_o
       shall not reflect the result of _r_e_a_d(), but reflect the prior error. If
       a hangup occurs on the STREAM being read, _r_e_a_d() shall continue to
       operate normally until the STREAM head read queue is empty. Thereafter,
       it shall return 0.

       The _p_r_e_a_d() function shall be equivalent to _r_e_a_d(), except that it
       shall read from a given position in the file without changing the file
       offset. The first three arguments to _p_r_e_a_d() are the same as _r_e_a_d()
       with the addition of a fourth argument _o_f_f_s_e_t for the desired position
       inside the file. An attempt to perform a _p_r_e_a_d() on a file that is
       incapable of seeking shall result in an error.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, these functions shall return a non-negative
       integer indicating the number of bytes actually read. Otherwise, the
       functions shall return -1 and set _e_r_r_n_o to indicate the error.

EERRRROORRSS
       These functions shall fail if:

       EEAAGGAAIINN The file is neither a pipe, nor a FIFO, nor a socket, the
              O_NONBLOCK flag is set for the file descriptor, and the thread
              would be delayed in the read operation.

       EEBBAADDFF  The _f_i_l_d_e_s argument is not a valid file descriptor open for
              reading.

       EEBBAADDMMSSGG
              The file is a STREAM file that is set to control-normal mode and
              the message waiting to be read includes a control part.

       EEIINNTTRR  The read operation was terminated due to the receipt of a
              signal, and no data was transferred.

       EEIINNVVAALL The STREAM or multiplexer referenced by _f_i_l_d_e_s is linked
              (directly or indirectly) downstream from a multiplexer.

       EEIIOO    The process is a member of a background process group attempting
              to read from its controlling terminal, and either the calling
              thread is blocking SIGTTIN or the process is ignoring SIGTTIN or
              the process group of the process is orphaned. This error may
              also be generated for implementation-defined reasons.

       EEIISSDDIIRR The _f_i_l_d_e_s argument refers to a directory and the implementation
              does not allow the directory to be read using _r_e_a_d() or _p_r_e_a_d().
              The _r_e_a_d_d_i_r() function should be used instead.

       EEOOVVEERRFFLLOOWW
              The file is a regular file, _n_b_y_t_e is greater than 0, the
              starting position is before the end-of-file, and the starting
              position is greater than or equal to the offset maximum
              established in the open file description associated with _f_i_l_d_e_s.

       The _p_r_e_a_d() function shall fail if:

       EEIINNVVAALL The file is a regular file or block special file, and the _o_f_f_s_e_t
              argument is negative. The file offset shall remain unchanged.

       EESSPPIIPPEE The file is incapable of seeking.

       The _r_e_a_d() function shall fail if:

       EEAAGGAAIINN The file is a pipe or FIFO, the O_NONBLOCK flag is set for the
              file descriptor, and the thread would be delayed in the read
              operation.

       EEAAGGAAIINN or EEWWOOUULLDDBBLLOOCCKK
              The file is a socket, the O_NONBLOCK flag is set for the file
              descriptor, and the thread would be delayed in the read
              operation.

       EECCOONNNNRREESSEETT
              A read was attempted on a socket and the connection was forcibly
              closed by its peer.

       EENNOOTTCCOONNNN
              A read was attempted on a socket that is not connected.

       EETTIIMMEEDDOOUUTT
              A read was attempted on a socket and a transmission timeout
              occurred.

       These functions may fail if:

       EEIIOO    A physical I/O error has occurred.

       EENNOOBBUUFFSS
              Insufficient resources were available in the system to perform
              the operation.

       EENNOOMMEEMM Insufficient memory was available to fulfill the request.

       EENNXXIIOO  A request was made of a nonexistent device, or the request was
              outside the capabilities of the device.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
   RReeaaddiinngg DDaattaa iinnttoo aa BBuuffffeerr
       The following example reads data from the file associated with the file
       descriptor _f_d into the buffer pointed to by _b_u_f.


           #include <sys/types.h>
           #include <unistd.h>
           ...
           char buf[20];
           size_t nbytes;
           ssize_t bytes_read;
           int fd;
           ...
           nbytes = sizeof(buf);
           bytes_read = read(fd, buf, nbytes);
           ...

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

RRAATTIIOONNAALLEE
       This volume of POSIX.1-2017 does not specify the value of the file
       offset after an error is returned; there are too many cases. For
       programming errors, such as [[EEBBAADDFF]], the concept is meaningless since
       no file is involved. For errors that are detected immediately, such as
       [[EEAAGGAAIINN]], clearly the offset should not change. After an interrupt or
       hardware error, however, an updated value would be very useful and is
       the behavior of many implementations.

       Note that a _r_e_a_d() of zero bytes does not modify the last data access
       timestamp. A _r_e_a_d() that requests more than zero bytes, but returns
       zero, is required to modify the last data access timestamp.

       Implementations are allowed, but not required, to perform error
       checking for _r_e_a_d() requests of zero bytes.

   IInnppuutt aanndd OOuuttppuutt
       The use of I/O with large byte counts has always presented problems.
       Ideas such as _l_r_e_a_d() and _l_w_r_i_t_e() (using and returning lloonnggs) were
       considered at one time. The current solution is to use abstract types
       on the ISO C standard function to _r_e_a_d() and _w_r_i_t_e().  The abstract
       types can be declared so that existing functions work, but can also be
       declared so that larger types can be represented in future
       implementations. It is presumed that whatever constraints limit the
       maximum range of ssiizzee__tt also limit portable I/O requests to the same
       range. This volume of POSIX.1-2017 also limits the range further by
       requiring that the byte count be limited so that a signed return value
       remains meaningful. Since the return type is also a (signed) abstract
       type, the byte count can be defined by the implementation to be larger
       than an iinntt can hold.

       The standard developers considered adding atomicity requirements to a
       pipe or FIFO, but recognized that due to the nature of pipes and FIFOs
       there could be no guarantee of atomicity of reads of {PIPE_BUF} or any
       other size that would be an aid to applications portability.

       This volume of POSIX.1-2017 requires that no action be taken for _r_e_a_d()
       or _w_r_i_t_e() when _n_b_y_t_e is zero. This is not intended to take precedence
       over detection of errors (such as invalid buffer pointers or file
       descriptors). This is consistent with the rest of this volume of
       POSIX.1-2017, but the phrasing here could be misread to require
       detection of the zero case before any other errors.  A value of zero is
       to be considered a correct value, for which the semantics are a no-op.

       I/O is intended to be atomic to ordinary files and pipes and FIFOs.
       Atomic means that all the bytes from a single operation that started
       out together end up together, without interleaving from other I/O
       operations. It is a known attribute of terminals that this is not
       honored, and terminals are explicitly (and implicitly permanently)
       excepted, making the behavior unspecified. The behavior for other
       device types is also left unspecified, but the wording is intended to
       imply that future standards might choose to specify atomicity (or not).

       There were recommendations to add format parameters to _r_e_a_d() and
       _w_r_i_t_e() in order to handle networked transfers among heterogeneous file
       system and base hardware types. Such a facility may be required for
       support by the OSI presentation of layer services. However, it was
       determined that this should correspond with similar C-language
       facilities, and that is beyond the scope of this volume of
       POSIX.1-2017. The concept was suggested to the developers of the ISO C
       standard for their consideration as a possible area for future work.

       In 4.3 BSD, a _r_e_a_d() or _w_r_i_t_e() that is interrupted by a signal before
       transferring any data does not by default return an [[EEIINNTTRR]] error, but
       is restarted. In 4.2 BSD, 4.3 BSD, and the Eighth Edition, there is an
       additional function, _s_e_l_e_c_t(), whose purpose is to pause until
       specified activity (data to read, space to write, and so on) is
       detected on specified file descriptors. It is common in applications
       written for those systems for _s_e_l_e_c_t() to be used before _r_e_a_d() in
       situations (such as keyboard input) where interruption of I/O due to a
       signal is desired.

       The issue of which files or file types are interruptible is considered
       an implementation design issue. This is often affected primarily by
       hardware and reliability issues.

       There are no references to actions taken following an ``unrecoverable
       error''. It is considered beyond the scope of this volume of
       POSIX.1-2017 to describe what happens in the case of hardware errors.

       Earlier versions of this standard allowed two very different behaviors
       with regard to the handling of interrupts. In order to minimize the
       resulting confusion, it was decided that POSIX.1-2008 should support
       only one of these behaviors. Historical practice on AT&T-derived
       systems was to have _r_e_a_d() and _w_r_i_t_e() return -1 and set _e_r_r_n_o to
       [[EEIINNTTRR]] when interrupted after some, but not all, of the data requested
       had been transferred. However, the US Department of Commerce FIPS 151-1
       and FIPS 151-2 require the historical BSD behavior, in which _r_e_a_d() and
       _w_r_i_t_e() return the number of bytes actually transferred before the
       interrupt.  If -1 is returned when any data is transferred, it is
       difficult to recover from the error on a seekable device and impossible
       on a non-seekable device. Most new implementations support this
       behavior.  The behavior required by POSIX.1-2008 is to return the
       number of bytes transferred.

       POSIX.1-2008 does not specify when an implementation that buffers
       _r_e_a_d()s actually moves the data into the user-supplied buffer, so an
       implementation may choose to do this at the latest possible moment.
       Therefore, an interrupt arriving earlier may not cause _r_e_a_d() to return
       a partial byte count, but rather to return -1 and set _e_r_r_n_o to [[EEIINNTTRR]].

       Consideration was also given to combining the two previous options, and
       setting _e_r_r_n_o to [[EEIINNTTRR]] while returning a short count. However, not
       only is there no existing practice that implements this, it is also
       contradictory to the idea that when _e_r_r_n_o is set, the function
       responsible shall return -1.

       This volume of POSIX.1-2017 intentionally does not specify any _p_r_e_a_d()
       errors related to pipes, FIFOs, and sockets other than [[EESSPPIIPPEE]].

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _f_c_n_t_l(), _i_o_c_t_l(), _l_s_e_e_k(), _o_p_e_n(), _p_i_p_e(), _r_e_a_d_v()

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _1_1, _G_e_n_e_r_a_l
       _T_e_r_m_i_n_a_l _I_n_t_e_r_f_a_c_e, <<ssttrrooppttss..hh>>, <<ssyyss__uuiioo..hh>>, <<uunniissttdd..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1-2017, Standard for Information Technology --
       Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the
       Institute of Electrical and Electronics Engineers, Inc and The Open
       Group.  In the event of any discrepancy between this version and the
       original IEEE and The Open Group Standard, the original IEEE and The
       Open Group Standard is the referee document. The original Standard can
       be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2017                              READ(3)
