logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

read.3p (19830B)


  1. '\" et
  2. .TH READ "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. pread,
  12. read
  13. \(em read from a file
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <unistd.h>
  18. .P
  19. ssize_t pread(int \fIfildes\fP, void *\fIbuf\fP, size_t \fInbyte\fP, off_t \fIoffset\fR);
  20. ssize_t read(int \fIfildes\fP, void *\fIbuf\fP, size_t \fInbyte\fP);
  21. .fi
  22. .SH DESCRIPTION
  23. The
  24. \fIread\fR()
  25. function shall attempt to read
  26. .IR nbyte
  27. bytes from the file associated with the open file descriptor,
  28. .IR fildes ,
  29. into the buffer pointed to by
  30. .IR buf .
  31. The behavior of multiple concurrent reads on the same pipe, FIFO, or
  32. terminal device is unspecified.
  33. .P
  34. Before any action described below is taken, and if
  35. .IR nbyte
  36. is zero, the
  37. \fIread\fR()
  38. function may detect and return errors as described below. In the
  39. absence of errors, or if error detection is not performed, the
  40. \fIread\fR()
  41. function shall return zero and have no other results.
  42. .P
  43. On files that support seeking (for example, a regular file), the
  44. \fIread\fR()
  45. shall start at a position in the file given by the file offset
  46. associated with
  47. .IR fildes .
  48. The file offset shall be incremented by the number of bytes
  49. actually read.
  50. .P
  51. Files that do not support seeking\(emfor example, terminals\(emalways
  52. read from the current position. The value of a file offset associated
  53. with such a file is undefined.
  54. .P
  55. No data transfer shall occur past the current end-of-file. If the
  56. starting position is at or after the end-of-file, 0 shall be returned.
  57. If the file refers to a device special file, the result of subsequent
  58. \fIread\fR()
  59. requests is implementation-defined.
  60. .P
  61. If the value of
  62. .IR nbyte
  63. is greater than
  64. {SSIZE_MAX},
  65. the result is implementation-defined.
  66. .P
  67. When attempting to read from an empty pipe or FIFO:
  68. .IP " *" 4
  69. If no process has the pipe open for writing,
  70. \fIread\fR()
  71. shall return 0 to indicate end-of-file.
  72. .IP " *" 4
  73. If some process has the pipe open for writing and O_NONBLOCK is set,
  74. \fIread\fR()
  75. shall return \-1 and set
  76. .IR errno
  77. to
  78. .BR [EAGAIN] .
  79. .IP " *" 4
  80. If some process has the pipe open for writing and O_NONBLOCK is clear,
  81. \fIread\fR()
  82. shall block the calling thread until some data is written or the pipe
  83. is closed by all processes that had the pipe open for writing.
  84. .P
  85. When attempting to read a file (other than a pipe or FIFO) that
  86. supports non-blocking reads and has no data currently available:
  87. .IP " *" 4
  88. If O_NONBLOCK is set,
  89. \fIread\fR()
  90. shall return \-1 and set
  91. .IR errno
  92. to
  93. .BR [EAGAIN] .
  94. .IP " *" 4
  95. If O_NONBLOCK is clear,
  96. \fIread\fR()
  97. shall block the calling thread until some data becomes available.
  98. .IP " *" 4
  99. The use of the O_NONBLOCK flag has no effect if there is some data
  100. available.
  101. .P
  102. The
  103. \fIread\fR()
  104. function reads data previously written to a file. If any portion of a
  105. regular file prior to the end-of-file has not been written,
  106. \fIread\fR()
  107. shall return bytes with value 0. For example,
  108. \fIlseek\fR()
  109. allows the file offset to be set beyond the end of existing data in the
  110. file. If data is later written at this point, subsequent reads in the
  111. gap between the previous end of data and the newly written data shall
  112. return bytes with value 0 until data is written into the gap.
  113. .P
  114. Upon successful completion, where
  115. .IR nbyte
  116. is greater than 0,
  117. \fIread\fR()
  118. shall mark for update the last data access timestamp
  119. of the file, and shall return the number of bytes read.
  120. This number shall never be greater than
  121. .IR nbyte .
  122. The value returned may be less than
  123. .IR nbyte
  124. if the number of bytes left in the file is less than
  125. .IR nbyte ,
  126. if the
  127. \fIread\fR()
  128. request was interrupted by a signal, or if the file is a pipe or FIFO
  129. or special file and has fewer than
  130. .IR nbyte
  131. bytes immediately available for reading. For example, a
  132. \fIread\fR()
  133. from a file associated with a terminal may return one typed line of
  134. data.
  135. .P
  136. If a
  137. \fIread\fR()
  138. is interrupted by a signal before it reads any data, it shall return
  139. \-1 with
  140. .IR errno
  141. set to
  142. .BR [EINTR] .
  143. .P
  144. If a
  145. \fIread\fR()
  146. is interrupted by a signal after it has successfully read some data, it
  147. shall return the number of bytes read.
  148. .P
  149. For regular files, no data transfer shall occur past the offset maximum
  150. established in the open file description associated with
  151. .IR fildes .
  152. .P
  153. If
  154. .IR fildes
  155. refers to a socket,
  156. \fIread\fR()
  157. shall be equivalent to
  158. \fIrecv\fR()
  159. with no flags set.
  160. .P
  161. If the O_DSYNC and O_RSYNC bits have been set,
  162. read I/O operations on the file descriptor shall complete as defined by
  163. synchronized I/O data integrity completion. If the O_SYNC and O_RSYNC
  164. bits have been set, read I/O operations on the file descriptor shall
  165. complete as defined by synchronized I/O file integrity completion.
  166. .P
  167. If
  168. .IR fildes
  169. refers to a shared memory object, the result of the
  170. \fIread\fR()
  171. function is unspecified.
  172. .P
  173. If
  174. .IR fildes
  175. refers to a typed memory object, the result of the
  176. \fIread\fR()
  177. function is unspecified.
  178. .P
  179. A
  180. \fIread\fR()
  181. from a STREAMS file can read data in three different modes:
  182. \fIbyte-stream\fP mode, \fImessage-nondiscard\fP mode, and
  183. \fImessage-discard\fP mode. The default shall be byte-stream mode.
  184. This can be changed using the I_SRDOPT
  185. \fIioctl\fR()
  186. request, and can be tested with I_GRDOPT
  187. \fIioctl\fR().
  188. In byte-stream mode,
  189. \fIread\fR()
  190. shall retrieve data from the STREAM until as many bytes as were
  191. requested are
  192. transferred, or until there is no more data to be retrieved.
  193. Byte-stream mode ignores message boundaries.
  194. .P
  195. In STREAMS message-nondiscard mode,
  196. \fIread\fR()
  197. shall retrieve data until as many bytes as were requested are
  198. transferred, or until a message boundary is reached. If
  199. \fIread\fR()
  200. does not retrieve all the data in a message, the remaining data shall
  201. be left on the STREAM, and can be retrieved by the next
  202. \fIread\fR()
  203. call. Message-discard mode also retrieves data until as many bytes as
  204. were requested are transferred, or a message boundary is reached.
  205. However, unread data remaining in a message after the
  206. \fIread\fR()
  207. returns shall be discarded, and shall not be available for a subsequent
  208. \fIread\fR(),
  209. \fIgetmsg\fR(),
  210. or
  211. \fIgetpmsg\fR()
  212. call.
  213. .P
  214. How
  215. \fIread\fR()
  216. handles zero-byte STREAMS messages is determined by the current read
  217. mode setting. In byte-stream mode,
  218. \fIread\fR()
  219. shall accept data until it has read
  220. .IR nbyte
  221. bytes, or until there is no more data to read, or until a zero-byte
  222. message block is encountered. The
  223. \fIread\fR()
  224. function shall then return the number of bytes read, and place the
  225. zero-byte message back on the STREAM to be retrieved by the next
  226. \fIread\fR(),
  227. \fIgetmsg\fR(),
  228. or
  229. \fIgetpmsg\fR().
  230. In message-nondiscard mode or message-discard mode, a zero-byte message
  231. shall return 0 and the message shall be removed from the STREAM. When a
  232. zero-byte message is read as the first message on a STREAM, the message
  233. shall be removed from the STREAM and 0 shall be returned, regardless of
  234. the read mode.
  235. .P
  236. A
  237. \fIread\fR()
  238. from a STREAMS file shall return the data in the message at the front
  239. of the STREAM head read queue, regardless of the priority band of the
  240. message.
  241. .P
  242. By default, STREAMs are in control-normal mode, in which a
  243. \fIread\fR()
  244. from a STREAMS file can only process messages that contain a data part
  245. but do not contain a control part. The
  246. \fIread\fR()
  247. shall fail if a message containing a control part is encountered at the
  248. STREAM head. This default action can be changed by placing the STREAM
  249. in either control-data mode or control-discard mode with the I_SRDOPT
  250. \fIioctl\fR()
  251. command. In control-data mode,
  252. \fIread\fR()
  253. shall convert any control part to data and pass it to the application
  254. before passing any data part originally present in the same message.
  255. In control-discard mode,
  256. \fIread\fR()
  257. shall discard message control parts but return to the process any data
  258. part in the message.
  259. .P
  260. In addition,
  261. \fIread\fR()
  262. shall fail if the STREAM head had processed an asynchronous error
  263. before the call. In this case, the value of
  264. .IR errno
  265. shall not reflect the result of
  266. \fIread\fR(),
  267. but reflect the prior error. If a hangup occurs on the STREAM being
  268. read,
  269. \fIread\fR()
  270. shall continue to operate normally until the STREAM head read queue is
  271. empty. Thereafter, it shall return 0.
  272. .P
  273. The
  274. \fIpread\fR()
  275. function shall be equivalent to
  276. \fIread\fR(),
  277. except that it shall read from a given position in the file without
  278. changing the file offset. The first three arguments to
  279. \fIpread\fR()
  280. are the same as
  281. \fIread\fR()
  282. with the addition of a fourth argument
  283. .IR offset
  284. for the desired position inside the file. An attempt to perform a
  285. \fIpread\fR()
  286. on a file that is incapable of seeking shall result in an error.
  287. .SH "RETURN VALUE"
  288. Upon successful completion, these functions shall return a non-negative
  289. integer indicating the number of bytes actually read. Otherwise, the
  290. functions shall return \-1 and set
  291. .IR errno
  292. to indicate the error.
  293. .SH ERRORS
  294. These functions shall fail if:
  295. .TP
  296. .BR EAGAIN
  297. The file is neither a pipe, nor a FIFO, nor a socket, the O_NONBLOCK
  298. flag is set for the file descriptor, and the thread would be delayed
  299. in the read operation.
  300. .TP
  301. .BR EBADF
  302. The
  303. .IR fildes
  304. argument is not a valid file descriptor open for reading.
  305. .TP
  306. .BR EBADMSG
  307. The file is a STREAM file that is set to control-normal mode and the
  308. message waiting to be read includes a control part.
  309. .TP
  310. .BR EINTR
  311. The read operation was terminated due to the receipt of a signal, and
  312. no data was transferred.
  313. .TP
  314. .BR EINVAL
  315. The STREAM or multiplexer referenced by
  316. .IR fildes
  317. is linked (directly or indirectly) downstream from a multiplexer.
  318. .TP
  319. .BR EIO
  320. The process is a member of a background process group attempting to read
  321. from its controlling terminal, and either the calling thread is blocking
  322. SIGTTIN or the process is ignoring SIGTTIN or the process group of the
  323. process is orphaned. This error may also be generated for
  324. implementation-defined reasons.
  325. .TP
  326. .BR EISDIR
  327. The
  328. .IR fildes
  329. argument refers to a directory and the implementation
  330. does not allow the directory to be read using
  331. \fIread\fR()
  332. or
  333. \fIpread\fR().
  334. The
  335. \fIreaddir\fR()
  336. function should be used instead.
  337. .TP
  338. .BR EOVERFLOW
  339. The file is a regular file,
  340. .IR nbyte
  341. is greater than 0, the starting position is before the end-of-file, and
  342. the starting position is greater than or equal to the offset maximum
  343. established in the open file description associated with
  344. .IR fildes .
  345. .P
  346. The
  347. \fIpread\fR()
  348. function shall fail if:
  349. .TP
  350. .BR EINVAL
  351. The file is a regular file or block special file, and the
  352. .IR offset
  353. argument is negative. The file offset shall remain unchanged.
  354. .TP
  355. .BR ESPIPE
  356. The file is incapable of seeking.
  357. .br
  358. .P
  359. The
  360. \fIread\fR()
  361. function shall fail if:
  362. .TP
  363. .BR EAGAIN
  364. The file is a pipe or FIFO, the O_NONBLOCK flag is set for the file
  365. descriptor, and the thread would be delayed in the read operation.
  366. .TP
  367. .BR EAGAIN " or " EWOULDBLOCK
  368. .br
  369. The file is a socket, the O_NONBLOCK flag is set for the file
  370. descriptor, and the thread would be delayed in the read operation.
  371. .TP
  372. .BR ECONNRESET
  373. A read was attempted on a socket and the connection was forcibly closed
  374. by its peer.
  375. .TP
  376. .BR ENOTCONN
  377. A read was attempted on a socket that is not connected.
  378. .TP
  379. .BR ETIMEDOUT
  380. A read was attempted on a socket and a transmission timeout occurred.
  381. .P
  382. These functions may fail if:
  383. .TP
  384. .BR EIO
  385. A physical I/O error has occurred.
  386. .TP
  387. .BR ENOBUFS
  388. Insufficient resources were available in the system to perform the
  389. operation.
  390. .TP
  391. .BR ENOMEM
  392. Insufficient memory was available to fulfill the request.
  393. .TP
  394. .BR ENXIO
  395. A request was made of a nonexistent device, or the request was outside
  396. the capabilities of the device.
  397. .LP
  398. .IR "The following sections are informative."
  399. .SH EXAMPLES
  400. .SS "Reading Data into a Buffer"
  401. .P
  402. The following example reads data from the file associated with the file
  403. descriptor
  404. .IR fd
  405. into the buffer pointed to by
  406. .IR buf .
  407. .sp
  408. .RS 4
  409. .nf
  410. #include <sys/types.h>
  411. #include <unistd.h>
  412. \&...
  413. char buf[20];
  414. size_t nbytes;
  415. ssize_t bytes_read;
  416. int fd;
  417. \&...
  418. nbytes = sizeof(buf);
  419. bytes_read = read(fd, buf, nbytes);
  420. \&...
  421. .fi
  422. .P
  423. .RE
  424. .SH "APPLICATION USAGE"
  425. None.
  426. .SH RATIONALE
  427. This volume of POSIX.1\(hy2017 does not specify the value of the file offset after an
  428. error is returned; there are too many cases. For programming errors,
  429. such as
  430. .BR [EBADF] ,
  431. the concept is meaningless since no file is involved. For errors that
  432. are detected immediately, such as
  433. .BR [EAGAIN] ,
  434. clearly the offset should not change. After an interrupt or hardware
  435. error, however, an updated value would be very useful and is the
  436. behavior of many implementations.
  437. .P
  438. Note that a
  439. \fIread\fR()
  440. of zero bytes does not modify the last data access timestamp. A
  441. \fIread\fR()
  442. that requests more than zero bytes, but returns zero, is required
  443. to modify the last data access timestamp.
  444. .P
  445. Implementations are allowed, but not required, to perform error
  446. checking for
  447. \fIread\fR()
  448. requests of zero bytes.
  449. .SS "Input and Output"
  450. .P
  451. The use of I/O with large byte counts has always presented problems.
  452. Ideas such as
  453. \fIlread\fR()
  454. and
  455. \fIlwrite\fR()
  456. (using and returning
  457. .BR long s)
  458. were considered at one time. The current solution is to use abstract
  459. types on the ISO\ C standard function to
  460. \fIread\fR()
  461. and
  462. \fIwrite\fR().
  463. The abstract types can be declared so that existing functions work, but
  464. can also be declared so that larger types can be represented in future
  465. implementations. It is presumed that whatever constraints limit the
  466. maximum range of
  467. .BR size_t
  468. also limit portable I/O requests to the same range. This volume of POSIX.1\(hy2017 also limits
  469. the range further by requiring that the byte count be limited so that a
  470. signed return value remains meaningful. Since the return type is also a
  471. (signed) abstract type, the byte count can be defined by the
  472. implementation to be larger than an
  473. .BR int
  474. can hold.
  475. .P
  476. The standard developers considered adding atomicity requirements to a
  477. pipe or FIFO, but recognized that due to the nature of pipes and FIFOs
  478. there could be no guarantee of atomicity of reads of
  479. {PIPE_BUF}
  480. or any other size that would be an aid to applications portability.
  481. .P
  482. This volume of POSIX.1\(hy2017 requires that no action be taken for
  483. \fIread\fR()
  484. or
  485. \fIwrite\fR()
  486. when
  487. .IR nbyte
  488. is zero. This is not intended to take precedence over detection of
  489. errors (such as invalid buffer pointers or file descriptors). This is
  490. consistent with the rest of this volume of POSIX.1\(hy2017, but the phrasing here could be
  491. misread to require detection of the zero case before any other errors.
  492. A value of zero is to be considered a correct value, for which the
  493. semantics are a no-op.
  494. .P
  495. I/O is intended to be atomic to ordinary files and pipes and FIFOs.
  496. Atomic means that all the bytes from a single operation that
  497. started out together end up together, without interleaving from other
  498. I/O operations. It is a known attribute of terminals that this is not
  499. honored, and terminals are explicitly (and implicitly permanently)
  500. excepted, making the behavior unspecified. The behavior for other
  501. device types is also left unspecified, but the wording is intended to
  502. imply that future standards might choose to specify atomicity (or not).
  503. .P
  504. There were recommendations to add format parameters to
  505. \fIread\fR()
  506. and
  507. \fIwrite\fR()
  508. in order to handle networked transfers among heterogeneous file system
  509. and base hardware types. Such a facility may be required for support by
  510. the OSI presentation of layer services. However, it was determined that
  511. this should correspond with similar C-language facilities, and that is
  512. beyond the scope of this volume of POSIX.1\(hy2017. The concept was suggested to the developers
  513. of the ISO\ C standard for their consideration as a possible area for future
  514. work.
  515. .P
  516. In 4.3 BSD, a
  517. \fIread\fR()
  518. or
  519. \fIwrite\fR()
  520. that is interrupted by a signal before transferring any data does not
  521. by default return an
  522. .BR [EINTR]
  523. error, but is restarted. In 4.2 BSD,
  524. 4.3 BSD,
  525. and the Eighth Edition, there is an additional function,
  526. \fIselect\fR(),
  527. whose purpose is to pause until specified activity (data to read, space
  528. to write, and so on) is detected on specified file descriptors. It is
  529. common in applications written for those systems for
  530. \fIselect\fR()
  531. to be used before
  532. \fIread\fR()
  533. in situations (such as keyboard input) where interruption of I/O due to
  534. a signal is desired.
  535. .P
  536. The issue of which files or file types are interruptible is considered
  537. an implementation design issue. This is often affected primarily by
  538. hardware and reliability issues.
  539. .P
  540. There are no references to actions taken following an ``unrecoverable
  541. error''. It is considered beyond the scope of this volume of POSIX.1\(hy2017 to describe what
  542. happens in the case of hardware errors.
  543. .P
  544. Earlier versions of this standard allowed two very different behaviors
  545. with regard to the handling of interrupts. In order to minimize the
  546. resulting confusion, it was decided that POSIX.1\(hy2008 should support only one
  547. of these behaviors. Historical practice on AT&T-derived systems was to
  548. have
  549. \fIread\fR()
  550. and
  551. \fIwrite\fR()
  552. return \-1 and set
  553. .IR errno
  554. to
  555. .BR [EINTR]
  556. when interrupted after some, but not all, of the data requested had
  557. been transferred. However, the US Department of Commerce FIPS 151\(hy1 and
  558. FIPS 151\(hy2 require the historical BSD behavior, in which
  559. \fIread\fR()
  560. and
  561. \fIwrite\fR()
  562. return the number of bytes actually transferred before the interrupt.
  563. If \-1 is returned when any data is transferred, it is difficult to
  564. recover from the error on a seekable device and impossible on a
  565. non-seekable device. Most new implementations support this behavior.
  566. The behavior required by POSIX.1\(hy2008 is to return the number of bytes
  567. transferred.
  568. .P
  569. POSIX.1\(hy2008 does not specify when an implementation that buffers
  570. \fIread\fR()s
  571. actually moves the data into the user-supplied buffer, so an
  572. implementation may choose to do this at the latest possible moment.
  573. Therefore, an interrupt arriving earlier may not cause
  574. \fIread\fR()
  575. to return a partial byte count, but rather to return \-1 and set
  576. .IR errno
  577. to
  578. .BR [EINTR] .
  579. .P
  580. Consideration was also given to combining the two previous options, and
  581. setting
  582. .IR errno
  583. to
  584. .BR [EINTR]
  585. while returning a short count. However, not only is there no existing
  586. practice that implements this, it is also contradictory to the idea
  587. that when
  588. .IR errno
  589. is set, the function responsible shall return \-1.
  590. .P
  591. This volume of POSIX.1\(hy2017 intentionally does not specify any
  592. \fIpread\fR()
  593. errors related to pipes, FIFOs, and sockets other than
  594. .BR [ESPIPE] .
  595. .SH "FUTURE DIRECTIONS"
  596. None.
  597. .SH "SEE ALSO"
  598. .IR "\fIfcntl\fR\^(\|)",
  599. .IR "\fIioctl\fR\^(\|)",
  600. .IR "\fIlseek\fR\^(\|)",
  601. .IR "\fIopen\fR\^(\|)",
  602. .IR "\fIpipe\fR\^(\|)",
  603. .IR "\fIreadv\fR\^(\|)"
  604. .P
  605. The Base Definitions volume of POSIX.1\(hy2017,
  606. .IR "Chapter 11" ", " "General Terminal Interface",
  607. .IR "\fB<stropts.h>\fP",
  608. .IR "\fB<sys_uio.h>\fP",
  609. .IR "\fB<unistd.h>\fP"
  610. .\"
  611. .SH COPYRIGHT
  612. Portions of this text are reprinted and reproduced in electronic form
  613. from IEEE Std 1003.1-2017, Standard for Information Technology
  614. -- Portable Operating System Interface (POSIX), The Open Group Base
  615. Specifications Issue 7, 2018 Edition,
  616. Copyright (C) 2018 by the Institute of
  617. Electrical and Electronics Engineers, Inc and The Open Group.
  618. In the event of any discrepancy between this version and the original IEEE and
  619. The Open Group Standard, the original IEEE and The Open Group Standard
  620. is the referee document. The original Standard can be obtained online at
  621. http://www.opengroup.org/unix/online.html .
  622. .PP
  623. Any typographical or formatting errors that appear
  624. in this page are most likely
  625. to have been introduced during the conversion of the source files to
  626. man page format. To report such errors, see
  627. https://www.kernel.org/doc/man-pages/reporting_bugs.html .