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

write.3p (22217B)


  1. '\" et
  2. .TH WRITE "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. pwrite,
  12. write
  13. \(em write on a file
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <unistd.h>
  18. .P
  19. ssize_t pwrite(int \fIfildes\fP, const void *\fIbuf\fP, size_t \fInbyte\fP,
  20. off_t \fIoffset\fP);
  21. ssize_t write(int \fIfildes\fP, const void *\fIbuf\fP, size_t \fInbyte\fP);
  22. .fi
  23. .SH DESCRIPTION
  24. The
  25. \fIwrite\fR()
  26. function shall attempt to write
  27. .IR nbyte
  28. bytes from the buffer pointed to by
  29. .IR buf
  30. to the file associated with the open file descriptor,
  31. .IR fildes .
  32. .P
  33. Before any action described below is taken, and if
  34. .IR nbyte
  35. is zero and the file is a regular file, the
  36. \fIwrite\fR()
  37. function may detect and return errors as described below. In the
  38. absence of errors, or if error detection is not performed, the
  39. \fIwrite\fR()
  40. function shall return zero and have no other results. If
  41. .IR nbyte
  42. is zero and the file is not a regular file, the results are
  43. unspecified.
  44. .P
  45. On a regular file or other file capable of seeking, the actual writing
  46. of data shall proceed from the position in the file indicated by the
  47. file offset associated with
  48. .IR fildes .
  49. Before successful return from
  50. \fIwrite\fR(),
  51. the file offset shall be incremented by the number of bytes actually
  52. written. On a regular file, if the position of the last byte written
  53. is greater than or equal to the length of the file,
  54. the length of the file shall be set to this position plus one.
  55. .P
  56. On a file not capable of seeking, writing shall always take place
  57. starting at the current position. The value of a file offset associated
  58. with such a device is undefined.
  59. .P
  60. If the O_APPEND flag of the file status flags is set,
  61. the file offset shall be set to the end of the file prior to each write
  62. and no intervening file modification operation shall occur between
  63. changing the file offset and the write operation.
  64. .P
  65. If a
  66. \fIwrite\fR()
  67. requests that more bytes be written than there is room for (for
  68. example,
  69. the file size limit of the process or
  70. the physical end of a medium), only as many bytes as there is room for
  71. shall be written. For example, suppose there is space for 20 bytes more
  72. in a file before reaching a limit. A write of 512 bytes will return
  73. 20. The next write of a non-zero number of bytes would give a failure
  74. return (except as noted below).
  75. .P
  76. If the request would cause the file size to exceed the soft file size
  77. limit for the process and there is no room for any bytes to be written,
  78. the request shall fail and the implementation shall generate the
  79. SIGXFSZ signal for the thread.
  80. .P
  81. If
  82. \fIwrite\fR()
  83. is interrupted by a signal before it writes any data, it shall
  84. return \-1 with
  85. .IR errno
  86. set to
  87. .BR [EINTR] .
  88. .P
  89. If
  90. \fIwrite\fR()
  91. is interrupted by a signal after it successfully writes some data, it
  92. shall return the number of bytes written.
  93. .P
  94. If the value of
  95. .IR nbyte
  96. is greater than
  97. {SSIZE_MAX},
  98. the result is implementation-defined.
  99. .P
  100. After a
  101. \fIwrite\fR()
  102. to a regular file has successfully returned:
  103. .IP " *" 4
  104. Any successful
  105. \fIread\fR()
  106. from each byte position in the file that was modified by that write
  107. shall return the data specified by the
  108. \fIwrite\fR()
  109. for that position until such byte positions are again modified.
  110. .IP " *" 4
  111. Any subsequent successful
  112. \fIwrite\fR()
  113. to the same byte position in the file shall overwrite that file data.
  114. .br
  115. .P
  116. Write requests to a pipe or FIFO shall be handled in the same way
  117. as a regular file with the following exceptions:
  118. .IP " *" 4
  119. There is no file offset associated with a pipe, hence each write
  120. request shall append to the end of the pipe.
  121. .IP " *" 4
  122. Write requests of
  123. {PIPE_BUF}
  124. bytes or less shall not be interleaved with data from other processes
  125. doing writes on the same pipe. Writes of greater than
  126. {PIPE_BUF}
  127. bytes may have data interleaved, on arbitrary boundaries, with writes
  128. by other processes, whether or not the O_NONBLOCK flag of the file
  129. status flags is set.
  130. .IP " *" 4
  131. If the O_NONBLOCK flag is clear, a write request may cause the thread
  132. to block, but on normal completion it shall return
  133. .IR nbyte .
  134. .IP " *" 4
  135. If the O_NONBLOCK flag is set,
  136. \fIwrite\fR()
  137. requests shall be handled differently, in the following ways:
  138. .RS 4
  139. .IP -- 4
  140. The
  141. \fIwrite\fR()
  142. function shall not block the thread.
  143. .IP -- 4
  144. A write request for
  145. {PIPE_BUF}
  146. or fewer bytes shall have the following effect: if there is sufficient
  147. space available in the pipe,
  148. \fIwrite\fR()
  149. shall transfer all the data and return the number of bytes requested.
  150. Otherwise,
  151. \fIwrite\fR()
  152. shall transfer no data and return \-1 with
  153. .IR errno
  154. set to
  155. .BR [EAGAIN] .
  156. .IP -- 4
  157. A write request for more than
  158. {PIPE_BUF}
  159. bytes shall cause one of the following:
  160. .RS 4
  161. .IP -- 4
  162. When at least one byte can be written, transfer what it can and return
  163. the number of bytes written. When all data previously written to the
  164. pipe is read, it shall transfer at least
  165. {PIPE_BUF}
  166. bytes.
  167. .IP -- 4
  168. When no data can be written, transfer no data, and return \-1 with
  169. .IR errno
  170. set to
  171. .BR [EAGAIN] .
  172. .RE
  173. .RE
  174. .P
  175. When attempting to write to a file descriptor (other than a pipe or
  176. FIFO) that supports non-blocking writes and cannot accept the data
  177. immediately:
  178. .IP " *" 4
  179. If the O_NONBLOCK flag is clear,
  180. \fIwrite\fR()
  181. shall block the calling thread until the data can be accepted.
  182. .IP " *" 4
  183. If the O_NONBLOCK flag is set,
  184. \fIwrite\fR()
  185. shall not block the thread. If some data can be written without
  186. blocking the thread,
  187. \fIwrite\fR()
  188. shall write what it can and return the number of bytes written.
  189. Otherwise, it shall return \-1 and set
  190. .IR errno
  191. to
  192. .BR [EAGAIN] .
  193. .P
  194. Upon successful completion, where
  195. .IR nbyte
  196. is greater than 0,
  197. \fIwrite\fR()
  198. shall mark for update the last data modification and last file
  199. status change timestamps of the file, and if the file is a regular file,
  200. the S_ISUID and S_ISGID bits of the file mode may be cleared.
  201. .P
  202. For regular files, no data transfer shall occur past the offset maximum
  203. established in the open file description associated with
  204. .IR fildes .
  205. .P
  206. If
  207. .IR fildes
  208. refers to a socket,
  209. \fIwrite\fR()
  210. shall be equivalent to
  211. \fIsend\fR()
  212. with no flags set.
  213. .P
  214. If the O_DSYNC bit has been set,
  215. write I/O operations on the file descriptor shall complete as defined
  216. by synchronized I/O data integrity completion.
  217. .P
  218. If the O_SYNC bit has been set, write I/O operations on the file
  219. descriptor shall complete as defined by synchronized I/O file
  220. integrity completion.
  221. .P
  222. If
  223. .IR fildes
  224. refers to a shared memory object, the result of the
  225. \fIwrite\fR()
  226. function is unspecified.
  227. .P
  228. If
  229. .IR fildes
  230. refers to a typed memory object, the result of the
  231. \fIwrite\fR()
  232. function is unspecified.
  233. .P
  234. If
  235. .IR fildes
  236. refers to a STREAM, the operation of
  237. \fIwrite\fR()
  238. shall be determined by the values of the minimum and maximum
  239. .IR nbyte
  240. range (packet size) accepted by the STREAM. These values are determined
  241. by the topmost STREAM module. If
  242. .IR nbyte
  243. falls within the packet size range,
  244. .IR nbyte
  245. bytes shall be written. If
  246. .IR nbyte
  247. does not fall within the range and the minimum packet size value is 0,
  248. \fIwrite\fR()
  249. shall break the buffer into maximum packet size segments prior to
  250. sending the data downstream (the last segment may contain less than the
  251. maximum packet size). If
  252. .IR nbyte
  253. does not fall within the range and the minimum value is non-zero,
  254. \fIwrite\fR()
  255. shall fail with
  256. .IR errno
  257. set to
  258. .BR [ERANGE] .
  259. Writing a zero-length buffer (\c
  260. .IR nbyte
  261. is 0) to a STREAMS device sends 0 bytes with 0 returned. However,
  262. writing a zero-length buffer to a STREAMS-based pipe or FIFO sends no
  263. message and 0 is returned. The process may issue I_SWROPT
  264. \fIioctl\fR()
  265. to enable zero-length messages to be sent across the pipe or FIFO.
  266. .P
  267. When writing to a STREAM, data messages are created with a priority
  268. band of 0. When writing to a STREAM that is not a pipe or FIFO:
  269. .IP " *" 4
  270. If O_NONBLOCK is clear, and the STREAM cannot accept data (the STREAM
  271. write queue is full due to internal flow control conditions),
  272. \fIwrite\fR()
  273. shall block until data can be accepted.
  274. .IP " *" 4
  275. If O_NONBLOCK is set and the STREAM cannot accept data,
  276. \fIwrite\fR()
  277. shall return \-1 and set
  278. .IR errno
  279. to
  280. .BR [EAGAIN] .
  281. .IP " *" 4
  282. If O_NONBLOCK is set and part of the buffer has been written while a
  283. condition in which the STREAM cannot accept additional data occurs,
  284. \fIwrite\fR()
  285. shall terminate and return the number of bytes written.
  286. .P
  287. In addition,
  288. \fIwrite\fR()
  289. shall fail if the STREAM head has processed an asynchronous error
  290. before the call. In this case, the value of
  291. .IR errno
  292. does not reflect the result of
  293. \fIwrite\fR(),
  294. but reflects the prior error.
  295. .P
  296. The
  297. \fIpwrite\fR()
  298. function shall be equivalent to
  299. \fIwrite\fR(),
  300. except that it writes into a given position and does not change the
  301. file offset (regardless of whether O_APPEND is set). The first three
  302. arguments to
  303. \fIpwrite\fR()
  304. are the same as
  305. \fIwrite\fR()
  306. with the addition of a fourth argument
  307. .IR offset
  308. for the desired position inside the file. An attempt to perform a
  309. \fIpwrite\fR()
  310. on a file that is incapable of seeking shall result in an error.
  311. .SH "RETURN VALUE"
  312. Upon successful completion, these functions shall return the number of
  313. bytes actually written to the file associated with
  314. .IR fildes .
  315. This number shall never be greater than
  316. .IR nbyte .
  317. Otherwise, \-1 shall be returned and
  318. .IR errno
  319. set to indicate the error.
  320. .SH ERRORS
  321. These functions shall fail if:
  322. .TP
  323. .BR EAGAIN
  324. The file is neither a pipe, nor a FIFO, nor a socket, the O_NONBLOCK flag
  325. is set for the file descriptor, and the thread would be delayed in the
  326. \fIwrite\fR()
  327. operation.
  328. .TP
  329. .BR EBADF
  330. The
  331. .IR fildes
  332. argument is not a valid file descriptor open for writing.
  333. .TP
  334. .BR EFBIG
  335. An attempt was made to write a file that exceeds the
  336. implementation-defined maximum file size
  337. or the file size limit of the process,
  338. and there was no room for any bytes to be written.
  339. .TP
  340. .BR EFBIG
  341. The file is a regular file,
  342. .IR nbyte
  343. is greater than 0, and the starting position is greater than or equal
  344. to the offset maximum established in the open file description
  345. associated with
  346. .IR fildes .
  347. .TP
  348. .BR EINTR
  349. The write operation was terminated due to the receipt of a signal, and
  350. no data was transferred.
  351. .TP
  352. .BR EIO
  353. The process is a member of a background process group attempting to
  354. write to its controlling terminal, TOSTOP is set, the calling thread
  355. is not blocking SIGTTOU, the process is not ignoring SIGTTOU,
  356. and the process group of the process is orphaned. This error may also
  357. be returned under implementation-defined conditions.
  358. .TP
  359. .BR ENOSPC
  360. There was no free space remaining on the device containing the file.
  361. .TP
  362. .BR ERANGE
  363. The transfer request size was outside the range supported by the
  364. STREAMS file associated with
  365. .IR fildes .
  366. .P
  367. The
  368. \fIpwrite\fR()
  369. function shall fail if:
  370. .TP
  371. .BR EINVAL
  372. The file is a regular file or block special file, and the
  373. .IR offset
  374. argument is negative. The file offset shall remain unchanged.
  375. .TP
  376. .BR ESPIPE
  377. The file is incapable of seeking.
  378. .P
  379. The
  380. \fIwrite\fR()
  381. function shall fail if:
  382. .TP
  383. .BR EAGAIN
  384. The file is a pipe or FIFO, the O_NONBLOCK flag is set for the file
  385. descriptor, and the thread would be delayed in the write operation.
  386. .TP
  387. .BR EAGAIN " or " EWOULDBLOCK
  388. .br
  389. The file is a socket, the O_NONBLOCK flag is set for the file
  390. descriptor, and the thread would be delayed in the write operation.
  391. .TP
  392. .BR ECONNRESET
  393. A write was attempted on a socket that is not connected.
  394. .TP
  395. .BR EPIPE
  396. An attempt is made to write to a pipe or FIFO that is not open for
  397. reading by any process, or that only has one end open. A SIGPIPE signal
  398. shall also be sent to the thread.
  399. .TP
  400. .BR EPIPE
  401. A write was attempted on a socket that is shut down for writing, or is
  402. no longer connected. In the latter case, if the socket is of type
  403. SOCK_STREAM, a SIGPIPE signal shall also be sent to the thread.
  404. .P
  405. These functions may fail if:
  406. .TP
  407. .BR EINVAL
  408. The STREAM or multiplexer referenced by
  409. .IR fildes
  410. is linked (directly or indirectly) downstream from a multiplexer.
  411. .TP
  412. .BR EIO
  413. A physical I/O error has occurred.
  414. .TP
  415. .BR ENOBUFS
  416. Insufficient resources were available in the system to perform the
  417. operation.
  418. .TP
  419. .BR ENXIO
  420. A request was made of a nonexistent device, or the request was outside
  421. the capabilities of the device.
  422. .TP
  423. .BR ENXIO
  424. A hangup occurred on the STREAM being written to.
  425. .P
  426. A write to a STREAMS file may fail if an error message has been
  427. received at the STREAM head. In this case,
  428. .IR errno
  429. is set to the value included in the error message.
  430. .br
  431. .P
  432. The
  433. \fIwrite\fR()
  434. function may fail if:
  435. .TP
  436. .BR EACCES
  437. A write was attempted on a socket and the calling
  438. process does not have appropriate privileges.
  439. .TP
  440. .BR ENETDOWN
  441. A write was attempted on a socket and the local network interface used
  442. to reach the destination is down.
  443. .TP
  444. .BR ENETUNREACH
  445. .br
  446. A write was attempted on a socket and no route to the network is
  447. present.
  448. .LP
  449. .IR "The following sections are informative."
  450. .SH EXAMPLES
  451. .SS "Writing from a Buffer"
  452. .P
  453. The following example writes data from the buffer pointed to by
  454. .IR buf
  455. to the file associated with the file descriptor
  456. .IR fd .
  457. .sp
  458. .RS 4
  459. .nf
  460. #include <sys/types.h>
  461. #include <string.h>
  462. \&...
  463. char buf[20];
  464. size_t nbytes;
  465. ssize_t bytes_written;
  466. int fd;
  467. \&...
  468. strcpy(buf, "This is a test\en");
  469. nbytes = strlen(buf);
  470. .P
  471. bytes_written = write(fd, buf, nbytes);
  472. \&...
  473. .fi
  474. .P
  475. .RE
  476. .SH "APPLICATION USAGE"
  477. None.
  478. .SH RATIONALE
  479. See also the RATIONALE section in
  480. \fIread\fR().
  481. .P
  482. An attempt to write to a pipe or FIFO has several major
  483. characteristics:
  484. .IP " *" 4
  485. \fIAtomic/non-atomic\fP: A write is atomic if the whole amount written
  486. in one operation is not interleaved with data from any other process.
  487. This is useful when there are multiple writers sending data to a single
  488. reader. Applications need to know how large a write request can be
  489. expected to be performed atomically. This maximum is called
  490. {PIPE_BUF}.
  491. This volume of POSIX.1\(hy2017 does not say whether write requests for more than
  492. {PIPE_BUF}
  493. bytes are atomic, but requires that writes of
  494. {PIPE_BUF}
  495. or fewer bytes shall be atomic.
  496. .IP " *" 4
  497. \fIBlocking/immediate\fP: Blocking is only possible with O_NONBLOCK
  498. clear. If there is enough space for all the data requested to be
  499. written immediately, the implementation should do so. Otherwise, the
  500. calling thread may block; that is, pause until enough space is
  501. available for writing. The effective size of a pipe or FIFO (the
  502. maximum amount that can be written in one operation without blocking)
  503. may vary dynamically, depending on the implementation, so it is not
  504. possible to specify a fixed value for it.
  505. .IP " *" 4
  506. \fIComplete/partial/deferred\fP: A write request:
  507. .RS 4
  508. .sp
  509. .RS 4
  510. .nf
  511. int fildes;
  512. size_t nbyte;
  513. ssize_t ret;
  514. char *buf;
  515. .P
  516. ret = write(fildes, buf, nbyte);
  517. .fi
  518. .P
  519. .RE
  520. .P
  521. may return:
  522. .IP Complete 10
  523. \fIret\fP=\fInbyte\fP
  524. .IP Partial 10
  525. \fIret\fP<\fInbyte\fP
  526. .RS 10
  527. .P
  528. This shall never happen if
  529. .IR nbyte \(<=\c
  530. {PIPE_BUF}.
  531. If it does happen (with
  532. .IR nbyte >\c
  533. {PIPE_BUF}),
  534. \&this volume of POSIX.1\(hy2017 does not guarantee atomicity, even if
  535. .IR ret \(<=\c
  536. {PIPE_BUF},
  537. because atomicity is guaranteed according to the amount
  538. .IR requested ,
  539. not the amount
  540. .IR written .
  541. .RE
  542. .IP Deferred: 10
  543. \fIret\fP=\-1, \fIerrno\fP=[EAGAIN]
  544. .RS 10
  545. .P
  546. This error indicates that a later request may succeed. It does not
  547. indicate that it
  548. .IR shall
  549. succeed, even if
  550. .IR nbyte \(<=\c
  551. {PIPE_BUF},
  552. because if no process reads from the pipe or FIFO, the write never
  553. succeeds. An application could usefully count the number of times
  554. .BR [EAGAIN]
  555. is caused by a particular value of
  556. .IR nbyte >\c
  557. {PIPE_BUF}
  558. and perhaps do later writes with a smaller value, on the assumption
  559. that the effective size of the pipe may have decreased.
  560. .RE
  561. .P
  562. Partial and deferred writes are only possible with O_NONBLOCK set.
  563. .RE
  564. .P
  565. The relations of these properties are shown in the following tables:
  566. .TS
  567. center box tab(!);
  568. cB s s s
  569. cB | cB cB c
  570. l1 | lw(1.25i)1 lw(1.25i)1 lw(1.25i).
  571. Write to a Pipe or FIFO with O_NONBLOCK \fIclear\fP
  572. _
  573. Immediately Writable:!None!Some!\fInbyte\fP
  574. _
  575. \fInbyte\fP\(<={PIPE_BUF}!Atomic blocking!Atomic blocking!Atomic immediate
  576. !\fInbyte\fP!\fInbyte\fP!\fInbyte\fP
  577. _
  578. \fInbyte\fP>{PIPE_BUF}!Blocking \fInbyte\fP!Blocking \fInbyte\fP!Blocking \fInbyte\fP
  579. .TE
  580. .P
  581. If the O_NONBLOCK flag is clear, a write request shall block if the
  582. amount writable immediately is less than that requested. If the flag is
  583. set (by
  584. \fIfcntl\fR()),
  585. a write request shall never block.
  586. .TS
  587. center box tab(!);
  588. cB s s s
  589. cB | cB cB c
  590. l1 | lw(1.25i)1 lw(1.25i)1 lw(1.25i).
  591. Write to a Pipe or FIFO with O_NONBLOCK \fIset\fP
  592. _
  593. Immediately Writable:!None!Some!\fInbyte\fP
  594. _
  595. \fInbyte\fP\(<={PIPE_BUF}!\-1, [EAGAIN]!\-1, [EAGAIN]!Atomic \fInbyte\fP
  596. _
  597. \fInbyte\fP>{PIPE_BUF}!\-1, [EAGAIN]!<\fInbyte\fP or \-1,!\(<=\fInbyte\fP or \-1,
  598. !![EAGAIN]![EAGAIN]
  599. .TE
  600. .P
  601. There is no exception regarding partial writes when O_NONBLOCK is set.
  602. With the exception of writing to an empty pipe, this volume of POSIX.1\(hy2017 does not specify
  603. exactly when a partial write is performed since that would require
  604. specifying internal details of the implementation. Every application
  605. should be prepared to handle partial writes when O_NONBLOCK is set and
  606. the requested amount is greater than
  607. {PIPE_BUF},
  608. just as every application should be prepared to handle partial writes
  609. on other kinds of file descriptors.
  610. .P
  611. The intent of forcing writing at least one byte if any can be written
  612. is to assure that each write makes progress if there is any room in the
  613. pipe. If the pipe is empty,
  614. {PIPE_BUF}
  615. bytes must be written; if not, at least some progress must have been
  616. made.
  617. .P
  618. Where this volume of POSIX.1\(hy2017 requires \-1 to be returned and
  619. .IR errno
  620. set to
  621. .BR [EAGAIN] ,
  622. most historical implementations return zero (with the O_NDELAY
  623. flag set, which is the historical predecessor of O_NONBLOCK, but is not
  624. itself in this volume of POSIX.1\(hy2017). The error indications in this volume of POSIX.1\(hy2017 were chosen so that an
  625. application can distinguish these cases from end-of-file. While
  626. \fIwrite\fR()
  627. cannot receive an indication of end-of-file,
  628. \fIread\fR()
  629. can, and the two functions have similar return values. Also, some
  630. existing systems (for example, Eighth Edition) permit a write of zero
  631. bytes to
  632. mean that the reader should get an end-of-file indication; for those
  633. systems, a return value of zero from
  634. \fIwrite\fR()
  635. indicates a successful write of an end-of-file indication.
  636. .P
  637. Implementations are allowed, but not required, to perform error
  638. checking for
  639. \fIwrite\fR()
  640. requests of zero bytes.
  641. .P
  642. The concept of a
  643. {PIPE_MAX}
  644. limit (indicating the maximum number of bytes that can be written to a
  645. pipe in a single operation) was considered, but rejected, because this
  646. concept would unnecessarily limit application writing.
  647. .P
  648. See also the discussion of O_NONBLOCK in
  649. \fIread\fR().
  650. .P
  651. Writes can be serialized with respect to other reads and writes. If a
  652. \fIread\fR()
  653. of file data can be proven (by any means) to occur after a
  654. \fIwrite\fR()
  655. of the data, it must reflect that
  656. \fIwrite\fR(),
  657. even if the calls are made by different processes. A similar
  658. requirement applies to multiple write operations to the same file
  659. position. This is needed to guarantee the propagation of data from
  660. \fIwrite\fR()
  661. calls to subsequent
  662. \fIread\fR()
  663. calls. This requirement is particularly significant for networked file
  664. systems, where some caching schemes violate these semantics.
  665. .P
  666. Note that this is specified in terms of
  667. \fIread\fR()
  668. and
  669. \fIwrite\fR().
  670. The XSI extensions
  671. \fIreadv\fR()
  672. and
  673. \fIwritev\fR()
  674. also obey these semantics. A new ``high-performance'' write
  675. analog that did not follow these serialization requirements would also
  676. be permitted by this wording. This volume of POSIX.1\(hy2017 is also silent about any effects of
  677. application-level caching (such as that done by
  678. .IR stdio ).
  679. .P
  680. This volume of POSIX.1\(hy2017 does not specify the value of the file offset after an error is
  681. returned; there are too many cases. For programming errors, such as
  682. .BR [EBADF] ,
  683. the concept is meaningless since no file is involved. For errors that
  684. are detected immediately, such as
  685. .BR [EAGAIN] ,
  686. clearly the pointer should not change. After an interrupt or hardware
  687. error, however, an updated value would be very useful and is the
  688. behavior of many implementations.
  689. .P
  690. This volume of POSIX.1\(hy2017 does not specify the behavior of concurrent writes to a
  691. regular file from multiple threads, except that each write
  692. is atomic (see
  693. .IR "Section 2.9.7" ", " "Thread Interactions with Regular File Operations").
  694. Applications should use some form of concurrency control.
  695. .P
  696. This volume of POSIX.1\(hy2017 intentionally does not specify any
  697. \fIpwrite\fR()
  698. errors related to pipes, FIFOs, and sockets other than
  699. .BR [ESPIPE] .
  700. .SH "FUTURE DIRECTIONS"
  701. None.
  702. .SH "SEE ALSO"
  703. .IR "\fIchmod\fR\^(\|)",
  704. .IR "\fIcreat\fR\^(\|)",
  705. .IR "\fIdup\fR\^(\|)",
  706. .IR "\fIfcntl\fR\^(\|)",
  707. .IR "\fIgetrlimit\fR\^(\|)",
  708. .IR "\fIlseek\fR\^(\|)",
  709. .IR "\fIopen\fR\^(\|)",
  710. .IR "\fIpipe\fR\^(\|)",
  711. .IR "\fIread\fR\^(\|)",
  712. .IR "\fIulimit\fR\^(\|)",
  713. .IR "\fIwritev\fR\^(\|)"
  714. .P
  715. The Base Definitions volume of POSIX.1\(hy2017,
  716. .IR "\fB<limits.h>\fP",
  717. .IR "\fB<stropts.h>\fP",
  718. .IR "\fB<sys_uio.h>\fP",
  719. .IR "\fB<unistd.h>\fP"
  720. .\"
  721. .SH COPYRIGHT
  722. Portions of this text are reprinted and reproduced in electronic form
  723. from IEEE Std 1003.1-2017, Standard for Information Technology
  724. -- Portable Operating System Interface (POSIX), The Open Group Base
  725. Specifications Issue 7, 2018 Edition,
  726. Copyright (C) 2018 by the Institute of
  727. Electrical and Electronics Engineers, Inc and The Open Group.
  728. In the event of any discrepancy between this version and the original IEEE and
  729. The Open Group Standard, the original IEEE and The Open Group Standard
  730. is the referee document. The original Standard can be obtained online at
  731. http://www.opengroup.org/unix/online.html .
  732. .PP
  733. Any typographical or formatting errors that appear
  734. in this page are most likely
  735. to have been introduced during the conversion of the source files to
  736. man page format. To report such errors, see
  737. https://www.kernel.org/doc/man-pages/reporting_bugs.html .