📄 pwrite.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><meta name="generator" content="HTML Tidy, see www.w3.org"><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 --><!-- Copyright (c) 2001-2003 The Open Group, All Rights Reserved --><title>write</title></head><body bgcolor="white"><script type="text/javascript" language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> <a name="write"></a> <a name="tag_03_866"></a><!-- write --> <!--header start--><center><font size="2">The Open Group Base Specifications Issue 6<br>IEEE Std 1003.1, 2003 Edition<br>Copyright © 2001-2003 The IEEE and The Open Group, All Rights reserved.</font></center><!--header end--><hr size="2" noshade><h4><a name="tag_03_866_01"></a>NAME</h4><blockquote>pwrite, write - write on a file</blockquote><h4><a name="tag_03_866_02"></a>SYNOPSIS</h4><blockquote class="synopsis"><p><code><tt>#include <<a href="../basedefs/unistd.h.html">unistd.h</a>><br><br></tt></code></p><div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> ssize_t pwrite(int</tt> <i>fildes</i><tt>, const void *</tt><i>buf</i><tt>, size_t</tt><i>nbyte</i><tt>,<br> off_t offset); <img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div><tt><br> ssize_t write(int</tt> <i>fildes</i><tt>, const void *</tt><i>buf</i><tt>, size_t</tt> <i>nbyte</i><tt>);<br></tt></blockquote><h4><a name="tag_03_866_03"></a>DESCRIPTION</h4><blockquote><p>The <i>write</i>() function shall attempt to write <i>nbyte</i> bytes from the buffer pointed to by <i>buf</i> to the fileassociated with the open file descriptor, <i>fildes</i>.</p><p>Before any action described below is taken, and if <i>nbyte</i> is zero and the file is a regular file, the <i>write</i>()function may detect and return errors as described below. In the absence of errors, or if error detection is not performed, the<i>write</i>() function shall return zero and have no other results. If <i>nbyte</i> is zero and the file is not a regular file,the results are unspecified.</p><p>On a regular file or other file capable of seeking, the actual writing of data shall proceed 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 shall beincremented by the number of bytes actually written. On a regular file, if this incremented file offset is greater than the lengthof the file, the length of the file shall be set to this file offset.</p><p>On a file not capable of seeking, writing shall always take place starting at the current position. The value of a file offsetassociated with such a device is undefined.</p><p>If the O_APPEND flag of the file status flags is set, the file offset shall be set to the end of the file prior to each writeand no intervening file modification operation shall occur between changing the file offset and the write operation.</p><p>If a <i>write</i>() requests that more bytes be written than there is room for (for example, <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> the process'file size limit or <img src="../images/opt-end.gif" alt="[Option End]" border="0"> the physical end of a medium), only as manybytes as there is room for shall be written. For example, suppose there is space for 20 bytes more in a file before reaching alimit. A write of 512 bytes will return 20. The next write of a non-zero number of bytes would give a failure return (except asnoted below).</p><p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">If the request would cause the file size to exceed the soft file size limit for the process and there is no room for any bytes tobe written, the request shall fail and the implementation shall generate the SIGXFSZ signal for the thread. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p><p>If <i>write</i>() is interrupted by a signal before it writes any data, it shall return -1 with <i>errno</i> set to [EINTR].</p><p>If <i>write</i>() is interrupted by a signal after it successfully writes some data, it shall return the number of byteswritten.</p><p>If the value of <i>nbyte</i> is greater than {SSIZE_MAX}, the result is implementation-defined.</p><p>After a <i>write</i>() to a regular file has successfully returned:</p><ul><li><p>Any successful <a href="../functions/read.html"><i>read</i>()</a> from each byte position in the file that was modified by thatwrite shall return the data specified by the <i>write</i>() for that position until such byte positions are again modified.</p></li><li><p>Any subsequent successful <i>write</i>() to the same byte position in the file shall overwrite that file data.</p></li></ul><p>Write requests to a pipe or FIFO shall be handled in the same way as a regular file with the following exceptions:</p><ul><li><p>There is no file offset associated with a pipe, hence each write request shall append to the end of the pipe.</p></li><li><p>Write requests of {PIPE_BUF} bytes or less shall not be interleaved with data from other processes doing writes on the samepipe. Writes of greater than {PIPE_BUF} bytes may have data interleaved, on arbitrary boundaries, with writes by other processes,whether or not the O_NONBLOCK flag of the file status flags is set.</p></li><li><p>If the O_NONBLOCK flag is clear, a write request may cause the thread to block, but on normal completion it shall return<i>nbyte</i>.</p></li><li><p>If the O_NONBLOCK flag is set, <i>write</i>() requests shall be handled differently, in the following ways:</p><ul><li><p>The <i>write</i>() function shall not block the thread.</p></li><li><p>A write request for {PIPE_BUF} or fewer bytes shall have the following effect: if there is sufficient space available in thepipe, <i>write</i>() shall transfer all the data and return the number of bytes requested. Otherwise, <i>write</i>() shall transferno data and return -1 with <i>errno</i> set to [EAGAIN].</p></li><li><p>A write request for more than {PIPE_BUF} bytes shall cause one of the following:</p><ul><li><p>When at least one byte can be written, transfer what it can and return the number of bytes written. When all data previouslywritten to the pipe is read, it shall transfer at least {PIPE_BUF} bytes.</p></li><li><p>When no data can be written, transfer no data, and return -1 with <i>errno</i> set to [EAGAIN].</p></li></ul></li></ul></li></ul><p>When attempting to write to a file descriptor (other than a pipe or FIFO) that supports non-blocking writes and cannot acceptthe data immediately:</p><ul><li><p>If the O_NONBLOCK flag is clear, <i>write</i>() shall block the calling thread until the data can be accepted.</p></li><li><p>If the O_NONBLOCK flag is set, <i>write</i>() shall not block the thread. If some data can be written without blocking thethread, <i>write</i>() shall write what it can and return the number of bytes written. Otherwise, it shall return -1 and set<i>errno</i> to [EAGAIN].</p></li></ul><p>Upon successful completion, where <i>nbyte</i> is greater than 0, <i>write</i>() shall mark for update the <i>st_ctime</i> and<i>st_mtime</i> fields of the file, and if the file is a regular file, the S_ISUID and S_ISGID bits of the file mode may becleared.</p><p>For regular files, no data transfer shall occur past the offset maximum established in the open file description associated with<i>fildes</i>.</p><p>If <i>fildes</i> refers to a socket, <i>write</i>() shall be equivalent to <a href="../functions/send.html"><i>send</i>()</a>with no flags set.</p><p><sup>[<a href="javascript:open_code('SIO')">SIO</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">If the O_DSYNC bit has been set, write I/O operations on the file descriptor shall complete as defined by synchronized I/O dataintegrity completion.</p><p>If the O_SYNC bit has been set, write I/O operations on the file descriptor shall complete as defined by synchronized I/O fileintegrity completion. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p><p><sup>[<a href="javascript:open_code('SHM')">SHM</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">If <i>fildes</i> refers to a shared memory object, the result of the <i>write</i>() function is unspecified. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p><p><sup>[<a href="javascript:open_code('TYM')">TYM</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">If <i>fildes</i> refers to a typed memory object, the result of the <i>write</i>() function is unspecified. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p><p><sup>[<a href="javascript:open_code('XSR')">XSR</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">If <i>fildes</i> refers to a STREAM, the operation of <i>write</i>() shall be determined by the values of the minimum and maximum<i>nbyte</i> range (packet size) accepted by the STREAM. These values are determined by the topmost STREAM module. If <i>nbyte</i>falls within the packet size range, <i>nbyte</i> bytes shall be written. If <i>nbyte</i> does not fall within the range and theminimum packet size value is 0, <i>write</i>() shall break the buffer into maximum packet size segments prior to sending the datadownstream (the last segment may contain less than the maximum packet size). If <i>nbyte</i> does not fall within the range and theminimum value is non-zero, <i>write</i>() shall 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 0 returned. However, writing a zero-length buffer to a STREAMS-based pipe or FIFOsends no message and 0 is returned. The process may issue I_SWROPT <a href="../functions/ioctl.html"><i>ioctl</i>()</a> to enablezero-length messages to be sent across the pipe or FIFO.</p><p>When writing to a STREAM, data messages are created with a priority band of 0. When writing to a STREAM that is not a pipe orFIFO:</p><ul><li><p>If O_NONBLOCK is clear, and the STREAM cannot accept data (the STREAM write queue is full due to internal flow controlconditions), <i>write</i>() shall block until data can be accepted.</p></li><li><p>If O_NONBLOCK is set and the STREAM cannot accept data, <i>write</i>() shall return -1 and set <i>errno</i> to [EAGAIN].</p></li><li><p>If O_NONBLOCK is set and part of the buffer has been written while a condition in which the STREAM cannot accept additional dataoccurs, <i>write</i>() shall terminate and return the number of bytes written.</p></li></ul><p>In addition, <i>write</i>() shall fail if the STREAM head has processed an asynchronous error before the call. In this case, thevalue of <i>errno</i> does not reflect the result of <i>write</i>(), but reflects the prior error. <img src="../images/opt-end.gif"alt="[Option End]" border="0"></p><p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">The <i>pwrite</i>() function shall be equivalent to <i>write</i>(), except that it writes into a given position without changingthe file pointer. The first three arguments to <i>pwrite</i>() are the same as <i>write</i>() with the addition of a fourthargument offset for the desired position inside the file. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p></blockquote><h4><a name="tag_03_866_04"></a>RETURN VALUE</h4><blockquote><p>Upon successful completion, <i>write</i>() <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> and <i>pwrite</i>() <img src="../images/opt-end.gif" alt="[Option End]" border="0"> shall return the number of bytes actually written to the file associated with <i>fildes</i>. This numbershall never be greater than <i>nbyte</i>. Otherwise, -1 shall be returned and <i>errno</i> set to indicate the error.</p></blockquote><h4><a name="tag_03_866_05"></a>ERRORS</h4><blockquote><p>The <i>write</i>() and <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> <i>pwrite</i>() <img src="../images/opt-end.gif" alt="[Option End]" border="0"> functions shall failif:</p><dl compact><dt>[EAGAIN]</dt><dd>The O_NONBLOCK flag is set for the file descriptor and the thread would be delayed in the <i>write</i>() operation.</dd><dt>[EBADF]</dt><dd>The <i>fildes</i> argument is not a valid file descriptor open for writing.</dd><dt>[EFBIG]</dt><dd>An attempt was made to write a file that exceeds the implementation-defined maximum file size <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> or theprocess' file size limit, <img src="../images/opt-end.gif" alt="[Option End]" border="0"> and there was no room for any bytesto be written.</dd><dt>[EFBIG]</dt><dd>The file is a regular file, <i>nbyte</i> is greater than 0, and the starting position is greater than or equal to the offsetmaximum established in the open file description associated with <i>fildes</i>.</dd><dt>[EINTR]</dt>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -