📄 fseek.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-2004 IEEE and The Open Group, All Rights Reserved --><title>fseek</title></head><body bgcolor="white"><script type="text/javascript" language="JavaScript" src="../jscript/codes.js"></script><basefont size="3"> <a name="fseek"></a> <a name="tag_03_191"></a><!-- fseek --> <!--header start--><center><font size="2">The Open Group Base Specifications Issue 6<br>IEEE Std 1003.1, 2004 Edition<br>Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.</font></center><!--header end--><hr size="2" noshade><h4><a name="tag_03_191_01"></a>NAME</h4><blockquote>fseek, fseeko - reposition a file-position indicator in a stream</blockquote><h4><a name="tag_03_191_02"></a>SYNOPSIS</h4><blockquote class="synopsis"><p><code><tt>#include <<a href="../basedefs/stdio.h.html">stdio.h</a>><br><br> int fseek(FILE *</tt><i>stream</i><tt>, long</tt> <i>offset</i><tt>, int</tt> <i>whence</i><tt>);<br></tt></code></p><div class="box"><code><tt><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> int fseeko(FILE *</tt><i>stream</i><tt>, off_t</tt> <i>offset</i><tt>, int</tt> <i>whence</i><tt>);<img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div><tt><br></tt></blockquote><h4><a name="tag_03_191_03"></a>DESCRIPTION</h4><blockquote><div class="box"><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]"border="0"> The functionality described on this reference page is aligned with the ISO C standard. Any conflict between therequirements described here and the ISO C standard is unintentional. This volume of IEEE Std 1003.1-2001 defers tothe ISO C standard. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></div><p>The <i>fseek</i>() function shall set the file-position indicator for the stream pointed to by <i>stream</i>. If a read or writeerror occurs, the error indicator for the stream shall be set and <i>fseek</i>() fails.</p><p>The new position, measured in bytes from the beginning of the file, shall be obtained by adding <i>offset</i> to the positionspecified by <i>whence</i>. The specified point is the beginning of the file for SEEK_SET, the current value of the file-positionindicator for SEEK_CUR, or end-of-file for SEEK_END.</p><p>If the stream is to be used with wide-character input/output functions, the application shall ensure that <i>offset</i> iseither 0 or a value returned by an earlier call to <a href="../functions/ftell.html"><i>ftell</i>()</a> on the same stream and<i>whence</i> is SEEK_SET.</p><p>A successful call to <i>fseek</i>() shall clear the end-of-file indicator for the stream and undo any effects of <a href="../functions/ungetc.html"><i>ungetc</i>()</a> and <a href="../functions/ungetwc.html"><i>ungetwc</i>()</a> on the same stream.After an <i>fseek</i>() call, the next operation on an update stream may be either input or output.</p><p><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> Ifthe most recent operation, other than <a href="../functions/ftell.html"><i>ftell</i>()</a>, on a given stream is <a href="../functions/fflush.html"><i>fflush</i>()</a>, the file offset in the underlying open file description shall be adjusted toreflect the location specified by <i>fseek</i>().</p><p>The <i>fseek</i>() function shall allow the file-position indicator to be set beyond the end of existing data in the file. Ifdata is later written at this point, subsequent reads of data in the gap shall return bytes with the value 0 until data is actuallywritten into the gap.</p><p>The behavior of <i>fseek</i>() on devices which are incapable of seeking is implementation-defined. The value of the file offsetassociated with such a device is undefined.</p><p>If the stream is writable and buffered data had not been written to the underlying file, <i>fseek</i>() shall cause theunwritten data to be written to the file and shall mark the <i>st_ctime</i> and <i>st_mtime</i> fields of the file for update.</p><p>In a locale with state-dependent encoding, whether <i>fseek</i>() restores the stream's shift state isimplementation-defined.</p><p>The <i>fseeko</i>() function shall be equivalent to the <i>fseek</i>() function except that the <i>offset</i> argument is oftype <b>off_t</b>. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p></blockquote><h4><a name="tag_03_191_04"></a>RETURN VALUE</h4><blockquote><p>The <i>fseek</i>() <sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> and <i>fseeko</i>() <img src="../images/opt-end.gif" alt="[Option End]" border="0"> functionsshall return 0 if they succeed.</p><p><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">Otherwise, they shall return -1 and set <i>errno</i> to indicate the error. <img src="../images/opt-end.gif" alt="[Option End]"border="0"></p></blockquote><h4><a name="tag_03_191_05"></a>ERRORS</h4><blockquote><p>The <i>fseek</i>() <sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> and <i>fseeko</i>() <img src="../images/opt-end.gif" alt="[Option End]" border="0"> functions shall fail if, <sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> either the <i>stream</i> is unbuffered or the <i>stream</i>'s buffer needed to be flushed, andthe call to <i>fseek</i>() or <i>fseeko</i>() causes an underlying <a href="../functions/lseek.html"><i>lseek</i>()</a> or <a href="../functions/write.html"><i>write</i>()</a> to be invoked, and: <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p><dl compact><dt>[EAGAIN]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">The O_NONBLOCK flag is set for the file descriptor and the thread would be delayed in the write operation. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd><dt>[EBADF]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">The file descriptor underlying the stream file is not open for writing or the stream's buffer needed to be flushed and the file isnot open. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd><dt>[EFBIG]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> Anattempt was made to write a file that exceeds the maximum file size. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd><dt>[EFBIG]</dt><dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">An attempt was made to write a file that exceeds the process' file size limit. <img src="../images/opt-end.gif" alt="[Option End]"border="0"></dd><dt>[EFBIG]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">The file is a regular file and an attempt was made to write at or beyond the offset maximum associated with the correspondingstream. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd><dt>[EINTR]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">The write operation was terminated due to the receipt of a signal, and no data was transferred. <img src="../images/opt-end.gif"alt="[Option End]" border="0"></dd><dt>[EINVAL]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">The <i>whence</i> argument is invalid. The resulting file-position indicator would be set to a negative value. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd><dt>[EIO]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> Aphysical I/O error has occurred, or the process is a member of a background process group attempting to perform a <a href="../functions/write.html"><i>write</i>()</a> to its controlling terminal, TOSTOP is set, the process is neither ignoring norblocking SIGTTOU, and the process group of the process is orphaned. This error may also be returned under implementation-definedconditions. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd><dt>[ENOSPC]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">There was no free space remaining on the device containing the file. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd><dt>[ENXIO]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> Arequest was made of a nonexistent device, or the request was outside the capabilities of the device. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd><dt>[EOVERFLOW]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">For <i>fseek</i>(), the resulting file offset would be a value which cannot be represented correctly in an object of type<b>long</b>. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd><dt>[EOVERFLOW]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">For <i>fseeko</i>(), the resulting file offset would be a value which cannot be represented correctly in an object of type<b>off_t</b>. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd><dt>[EPIPE]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> Anattempt was made to write to a pipe or FIFO that is not open for reading by any process; a SIGPIPE signal shall also be sent to thethread. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></dd><dt>[ESPIPE]</dt><dd><sup>[<a href="javascript:open_code('CX')">CX</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">The file descriptor underlying <i>stream</i> is associated with a pipe or FIFO. <img src="../images/opt-end.gif" alt="[Option End]"border="0"></dd></dl></blockquote><hr><div class="box"><em>The following sections are informative.</em></div><h4><a name="tag_03_191_06"></a>EXAMPLES</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_191_07"></a>APPLICATION USAGE</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_191_08"></a>RATIONALE</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_191_09"></a>FUTURE DIRECTIONS</h4><blockquote><p>None.</p></blockquote><h4><a name="tag_03_191_10"></a>SEE ALSO</h4><blockquote><p><a href="fopen.html"><i>fopen</i>()</a>, <a href="fsetpos.html"><i>fsetpos</i>()</a>, <a href="ftell.html"><i>ftell</i>()</a>, <a href="getrlimit.html"><i>getrlimit</i>()</a>, <a href="lseek.html"><i>lseek</i>()</a>, <a href="rewind.html"><i>rewind</i>()</a>, <a href="ulimit.html"><i>ulimit</i>()</a>, <a href="ungetc.html"><i>ungetc</i>()</a>, <ahref="write.html"><i>write</i>()</a>, the Base Definitions volume of IEEE Std 1003.1-2001, <a href="../basedefs/stdio.h.html"><i><stdio.h></i></a></p></blockquote><h4><a name="tag_03_191_11"></a>CHANGE HISTORY</h4><blockquote><p>First released in Issue 1. Derived from Issue 1 of the SVID.</p></blockquote><h4><a name="tag_03_191_12"></a>Issue 5</h4><blockquote><p>Normative text previously in the APPLICATION USAGE section is moved to the DESCRIPTION.</p><p>Large File Summit extensions are added.</p></blockquote><h4><a name="tag_03_191_13"></a>Issue 6</h4><blockquote><p>Extensions beyond the ISO C standard are marked.</p><p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p><ul><li><p>The <i>fseeko</i>() function is added.</p></li><li><p>The [EFBIG], [EOVERFLOW], and [ENXIO] mandatory error conditions are added.</p></li></ul><p>The following change is incorporated for alignment with the FIPS requirements:</p><ul><li><p>The [EINTR] error is no longer an indication that the implementation does not report partial transfers.</p></li></ul><p>The DESCRIPTION is updated to avoid use of the term "must" for application requirements.</p><p>The DESCRIPTION is updated to explicitly state that <i>fseek</i>() sets the file-position indicator, and then on error the errorindicator is set and <i>fseek</i>() fails. This is for alignment with the ISO/IEC 9899:1999 standard.</p><p>IEEE Std 1003.1-2001/Cor 2-2004, item XSH/TC2/D6/42 is applied, updating the [EAGAIN] error in the ERRORS sectionfrom "the process would be delayed" to "the thread would be delayed".</p></blockquote><div class="box"><em>End of informative text.</em></div><hr size="2" noshade><center><font size="2"><!--footer start-->UNIX ® is a registered Trademark of The Open Group.<br>POSIX ® is a registered Trademark of The IEEE.<br>[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>]</font></center><!--footer end--><hr size="2" noshade></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -