📄 write.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><html><head><!-- Copyright 1997 The Open Group, All Rights Reserved --><title>write</title></head><body bgcolor=white><center><font size=2>The Single UNIX ® Specification, Version 2<br>Copyright © 1997 The Open Group</font></center><hr size=2 noshade><h4><a name = "tag_000_010_821"> </a>NAME</h4><blockquote>write, writev, pwrite - write on a file</blockquote><h4><a name = "tag_000_010_822"> </a>SYNOPSIS</h4><blockquote><pre><code>#include <<a href="unistd.h.html">unistd.h</a>>ssize_t write(int <i>fildes</i>, const void *<i>buf</i>, size_t <i>nbyte</i>);ssize_t pwrite(int <i>fildes</i>, const void *<i>buf</i>, size_t <i>nbyte</i>, off_t offset);#include <<a href="sysuio.h.html">sys/uio.h</a>>ssize_t writev(int <i>fildes</i>, const struct iovec *<i>iov</i>, int <i>iovcnt</i>);</code></pre></blockquote><h4><a name = "tag_000_010_823"> </a>DESCRIPTION</h4><blockquote>The<i>write()</i>function attempts to write<i>nbyte</i>bytes from the buffer pointed to by<i>buf</i>to the file associated with theopen file descriptor,<i>fildes</i>.<p>If <i>nbyte</i> is 0,<i>write()</i>will return 0 and have no other results if the file is a regular file;otherwise, the results are unspecified.<p>On a regular file or other file capable of seeking,the actual writing of data proceeds from the position in the fileindicated by the file offset associated with<i>fildes</i>.Before successful return from<i>write()</i>,the file offset is incremented by the number of bytes actuallywritten.On a regular file,if this incremented file offset is greater than the length of the file,the length of the file will be set to this file offset.<p>On a file not capable of seeking, writing always takes place starting at thecurrent position. The value of a file offset associated with such a device isundefined.<p>If the O_APPEND flag of the file status flags is set,the file offset will be set to the end of the file prior to each writeand no intervening file modification operation will occurbetween changing the file offset and the write operation.<p>If a<i>write()</i>requests that more bytes be written than there is room for (for example,the<i>ulimit</i>orthe physical end of a medium), only as many bytes as there is room for will bewritten. For example, suppose there is space for 20 bytes more in a filebefore reaching a limit. A write of 512 bytes will return 20. The next writeof a non-zero number of bytes will give a failure return (except as notedbelow) and the implementation will generate a SIGXFSZ signal for the thread.<p>If<i>write()</i>is interrupted by a signal before it writes any data,it will return -1 with<i>errno</i>set to [EINTR].<p>If<i>write()</i>is interrupted by a signal after it successfully writes some data,it will returnthe number of bytes written.<p>If the value of<i>nbyte</i>is greater than {SSIZE_MAX}, the result is implementation-dependent.<p>After a<i>write()</i>to a regular file has successfully returned:<p><ul><p><li>Any successful<i><a href="read.html">read()</a></i>from each byte position in the file that was modified by that write willreturn the data specified by the<i>write()</i>for that position until such byte positions are again modified.<p><li>Any subsequent successful<i>write()</i>to the same byte position in the file will overwrite that file data.<p></ul><p>Write requests to a pipe or FIFO will be handled the sameas a regular file with the following exceptions:<ul><p><li>There is no file offset associated with a pipe, henceeach write request will append to the end of the pipe.<p><li>Write requests of {PIPE_BUF}bytes or less will not be interleaved with datafrom other processes doing writes on the same pipe.Writes of greater than {PIPE_BUF}bytes may have data interleaved, on arbitraryboundaries, with writes by other processes,whether or not the O_NONBLOCK flag of the file status flags is set.<p><li>If the O_NONBLOCK flag is clear, a write request may cause the threadto block, but on normal completion it will return<i>nbyte</i>.<p><li>If the O_NONBLOCK flag is set,<i>write()</i>requests will be handled differently, in the following ways:<ul><p><li>The<i>write()</i>function will not block the thread.<p><li>A write request for {PIPE_BUF} or fewer bytes will have the following effect:If there is sufficient space available in the pipe,<i>write()</i>will transfer all the data and return the number of bytes requested.Otherwise,<i>write()</i>will transfer no data and return -1 with<i>errno</i>set to [EAGAIN].<p><li>A write request for more than {PIPE_BUF} bytes will case one of thefollowing:<ol type = a><p><li>When at least one byte can be written,transfer what it can and return the number of bytes written.When all data previously written to the pipe is read,it will transfer at least {PIPE_BUF} bytes.<p><li>When no data can be written,transfer no data and return -1 with<i>errno</i>set to [EAGAIN].<p></ol><p></ul><p></ul><p>When attempting to write to a file descriptor (other thana pipe or FIFO) that supports non-blocking writes andcannot accept the data immediately:<ul><p><li>If the O_NONBLOCK flag is clear,<i>write()</i>will block the calling thread until the data can be accepted.<p><li>If the O_NONBLOCK flag is set,<i>write()</i>will not block the process.If some data can be written without blocking the process,<i>write()</i>will write what it can and return the number of bytes written.Otherwise, it will return -1 and<i>errno</i>will be set to [EAGAIN].<p></ul><p>Upon successful completion, where<i>nbyte</i>is greater than 0,<i>write()</i>will mark for update the <i>st_ctime</i>and <i>st_mtime</i> fields of the file, and if the file is a regularfile, the S_ISUID and S_ISGID bits of the file mode may be cleared.<p>If <i>fildes</i> refers to a STREAM, the operation of<i>write()</i>is determined by the values of the minimum and maximum <i>nbyte</i> range("packet size") accepted by the STREAM. These values are determined by thetopmost STREAM module. If <i>nbyte</i> falls withinthe packet size range, <i>nbyte</i> bytes will be written. If <i>nbyte</i> doesnot fall within the range and the minimum packet size value is 0,<i>write()</i>will break the buffer into maximum packet size segments prior to sending thedata downstream (the last segment may contain less than the maximum packetsize). If <i>nbyte</i> does not fall within the range and the minimum value isnon-zero,<i>write()</i>will fail with <i>errno</i> set to [ERANGE]. Writing a zero-length buffer(<i>nbyte</i> is 0) to a STREAMS device sends 0 bytes with 0returned. However, writing a zero-length buffer to a STREAMS-based pipe orFIFO sends no message and 0 is returned. The process may issue I_SWROPT<i><a href="ioctl.html">ioctl()</a></i>to enable zero-length messages to be sent across the pipe or FIFO.<p>When writing to a STREAM, data messages are created with a priority band of0. When writing to a STREAM that is not a pipe or FIFO:<ul><p><li>If O_NONBLOCK is clear, and the STREAM cannot accept data (the STREAM writequeue is full due to internal flow control conditions),<i>write()</i>will block until data can be accepted.<p><li>If O_NONBLOCK is set and the STREAM cannot accept data,<i>write()</i>will return -1 and set <i>errno</i> to [EAGAIN].<p><li>If O_NONBLOCK is set and part of the buffer has been written while a conditionin which the STREAM cannot accept additional data occurs,<i>write()</i>will terminate and return the number of bytes written.<p></ul><p>In addition,<i>write()</i>and<i>writev()</i>will fail if the STREAM head had processed an asynchronous error before thecall. In this case, the value of<i>errno</i>does not reflect the result of<i>write()</i>or<i>writev()</i>but reflects the prior error.<p>The<i>writev()</i>function is equivalent to<i>write()</i>,but gathers the output data from the<i>iovcnt</i>buffers specified by the members of the<i>iov</i> array:<i>iov</i>[0], <i>iov</i>[1], ...,<i>iov</i>[<i>iovcnt</i>-1].<i>iovcnt</i> is valid if greater than 0 and less than or equalto {IOV_MAX}, defined in<i><a href="limits.h.html"><limits.h></a></i>.<p>Each <b>iovec</b> entry specifies the base address and length of an area inmemory from which data should be written. The<i>writev()</i>function will always write a complete area before proceeding to the next.<p>If <i>fildes</i> refers to a regular file and all of the <b>iov_len</b> membersin the array pointed to by <i>iov</i> are 0,<i>writev()</i>will return 0 and have no other effect. For other file types, thebehaviour is unspecified.<p>If the sum of the <b>iov_len</b> values is greater than SSIZE_MAX, theoperation fails and no data is transferred.<p>If the Synchronized Input and Output option is supported:<dl compact><dt> <dd>If the O_DSYNC bit has been set,write I/O operations on the file descriptor complete as defined bysynchronised I/O data integrity completion.</dl><p>If the O_SYNC bit has been set, write I/O operations on the filedescriptor complete as defined by synchronised I/O file integritycompletion.<p>If the Shared Memory Objects option is supported:<dl compact><dt> <dd>If<i>fildes</i>refers to a shared memory object, the result of the<i>write()</i>function is unspecified.</dl><p>For regular files, no data transfer will occur past the offset maximumestablished in the open file description associated with<i>fildes</i>.<p>The<i><a href="pwrite.html">pwrite()</a></i>function performs the same action as<i>write()</i>,except that it writes into a given position without changing the filepointer.The first three arguments to<i><a href="pwrite.html">pwrite()</a></i>are the same as<i>write()</i>with the addition of a fourth argument offset for the desired positioninside the file.</blockquote><h4><a name = "tag_000_010_824"> </a>RETURN VALUE</h4><blockquote>Upon successful completion,<i>write()</i>and<i><a href="pwrite.html">pwrite()</a></i>will return the number of bytes actually writtento the file associated with<i>fildes</i>.This number will never be greater than<i>nbyte</i>.Otherwise, -1 is returned and<i>errno</i>is set to indicate the error.<p>Upon successful completion,<i>writev()</i>returns the number of bytes actually written. Otherwise, it returns a valueof -1, the file-pointer remains unchanged, and <i>errno</i> is set toindicate an error.</blockquote><h4><a name = "tag_000_010_825"> </a>ERRORS</h4><blockquote>The<i>write()</i>,<i>writev()</i>and<i><a href="pwrite.html">pwrite()</a></i>functions will fail if:<dl compact><dt>[EAGAIN]<dd>The O_NONBLOCK flag is set for the file descriptorand the thread would be delayed in the<i>write()</i>operation.<dt>[EBADF]<dd>The<i>fildes</i>argument is not a valid file descriptor open for writing.<dt>[EFBIG]<dd>An attempt was made to write a file that exceedsthe implementation-dependent maximum file size or the process' file size limit.<dt>[EFBIG]<dd>The file is a regular file,<i>nbyte</i>is greater than 0 and the startingposition is greater than or equal to the offset maximum established inthe open file description associated with<i>fildes</i>.<dt>[EINTR]<dd>The write operation was terminated due to the receipt of a signal, and no datawas transferred.<dt>[EIO]<dd>A physical I/O error has occurred.<dt>[EIO]<dd>The process is a memberof a background process group attempting to write to itscontrolling terminal, TOSTOP is set, the process is neither ignoring norblocking SIGTTOU and the process group of the process isorphaned.This error may also be returned under implementation-dependent conditions.<dt>[ENOSPC]<dd>There was no free space remaining on the device containingthe file.<dt>[EPIPE]<dd>An attempt is made to write to a pipe or FIFO that is not openfor reading by any process,or that only has one end open.A SIGPIPE signal will also be sent to the thread.<dt>[ERANGE]<dd>The transfer request size was outside the range supported by the STREAMS fileassociated with <i>fildes</i>.</dl><p>The<i>writev()</i>function will fail if:<dl compact><dt>[EINVAL]<dd>The sum of the <b>iov_len</b> values in the <i>iov</i> array wouldoverflow an <b>ssize_t</b>.</dl><p>The<i>write()</i>,<i>writev()</i>and<i><a href="pwrite.html">pwrite()</a></i>functions may fail if:<dl compact><dt>[EINVAL]<dd>The STREAM or multiplexer referenced by <i>fildes</i> is linked (directly orindirectly) downstream from a multiplexer.<dt>[ENXIO]<dd>A request was made of a non-existent device, or the request wasoutside the capabilities of the device.<dt>[ENXIO]<dd>A hangup occurred on the STREAM being written to.</dl><p>A write to a STREAMS file may fail if an error message has been received atthe STREAM head. In this case, <i>errno</i> is set to the value included inthe error message.<p>The<i>writev()</i>function may fail and set <i>errno</i> to:<dl compact><dt>[EINVAL]<dd>The <i>iovcnt</i> argument was less than or equal to 0, or greater than{IOV_MAX}.</dl><p>The<i><a href="pwrite.html">pwrite()</a></i>function fails and the file pointer remains unchanged if:<dl compact><dt>[EINVAL]<dd>The<i>offset</i>argument is invalid.The value is negative.<dt>[ESPIPE]<dd><i>fildes</i> is associated with a pipe or FIFO.</dl></blockquote><h4><a name = "tag_000_010_826"> </a>EXAMPLES</h4><blockquote>None.</blockquote><h4><a name = "tag_000_010_827"> </a>APPLICATION USAGE</h4><blockquote>None.</blockquote><h4><a name = "tag_000_010_828"> </a>FUTURE DIRECTIONS</h4><blockquote>None.</blockquote><h4><a name = "tag_000_010_829"> </a>SEE ALSO</h4><blockquote><i><a href="chmod.html">chmod()</a></i>,<i><a href="creat.html">creat()</a></i>,<i><a href="dup.html">dup()</a></i>,<i><a href="fcntl.html">fcntl()</a></i>,<i><a href="getrlimit.html">getrlimit()</a></i>,<i><a href="lseek.html">lseek()</a></i>,<i><a href="open.html">open()</a></i>,<i><a href="pipe.html">pipe()</a></i>,<i><a href="ulimit.html">ulimit()</a></i>,<i><a href="limits.h.html"><limits.h></a></i>,<i><a href="stropts.h.html"><stropts.h></a></i>,<i><a href="sysuio.h.html"><sys/uio.h></a></i>,<i><a href="unistd.h.html"><unistd.h></a></i>.</blockquote><h4>DERIVATION</h4><blockquote>Derived from Issue 1 of the SVID.</blockquote><hr size=2 noshade><center><font size=2>UNIX ® is a registered Trademark of The Open Group.<br>Copyright © 1997 The Open Group<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]</font></center><hr size=2 noshade></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -