| <html lang="en"> |
| <head> |
| <title>File Position Primitive - The GNU C Library</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="The GNU C Library"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="Low_002dLevel-I_002fO.html#Low_002dLevel-I_002fO" title="Low-Level I/O"> |
| <link rel="prev" href="I_002fO-Primitives.html#I_002fO-Primitives" title="I/O Primitives"> |
| <link rel="next" href="Descriptors-and-Streams.html#Descriptors-and-Streams" title="Descriptors and Streams"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| This file documents the GNU C library. |
| |
| This is Edition 0.12, last updated 2007-10-27, |
| of `The GNU C Library Reference Manual', for version |
| 2.8 (Sourcery G++ Lite 2011.03-41). |
| |
| Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, |
| 2003, 2007, 2008, 2010 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software Needs Free Documentation'' |
| and ``GNU Lesser General Public License'', the Front-Cover texts being |
| ``A GNU Manual'', and with the Back-Cover Texts as in (a) below. A |
| copy of the license is included in the section entitled "GNU Free |
| Documentation License". |
| |
| (a) The FSF's Back-Cover Text is: ``You have the freedom to |
| copy and modify this GNU manual. Buying copies from the FSF |
| supports it in developing GNU and promoting software freedom.''--> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="File-Position-Primitive"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="Descriptors-and-Streams.html#Descriptors-and-Streams">Descriptors and Streams</a>, |
| Previous: <a rel="previous" accesskey="p" href="I_002fO-Primitives.html#I_002fO-Primitives">I/O Primitives</a>, |
| Up: <a rel="up" accesskey="u" href="Low_002dLevel-I_002fO.html#Low_002dLevel-I_002fO">Low-Level I/O</a> |
| <hr> |
| </div> |
| |
| <h3 class="section">13.3 Setting the File Position of a Descriptor</h3> |
| |
| <p>Just as you can set the file position of a stream with <code>fseek</code>, you |
| can set the file position of a descriptor with <code>lseek</code>. This |
| specifies the position in the file for the next <code>read</code> or |
| <code>write</code> operation. See <a href="File-Positioning.html#File-Positioning">File Positioning</a>, for more information |
| on the file position and what it means. |
| |
| <p>To read the current file position value from a descriptor, use |
| <code>lseek (</code><var>desc</var><code>, 0, SEEK_CUR)</code>. |
| |
| <p><a name="index-file-positioning-on-a-file-descriptor-1217"></a><a name="index-positioning-a-file-descriptor-1218"></a><a name="index-seeking-on-a-file-descriptor-1219"></a><!-- unistd.h --> |
| <!-- POSIX.1 --> |
| |
| <div class="defun"> |
| — Function: off_t <b>lseek</b> (<var>int filedes, off_t offset, int whence</var>)<var><a name="index-lseek-1220"></a></var><br> |
| <blockquote><p>The <code>lseek</code> function is used to change the file position of the |
| file with descriptor <var>filedes</var>. |
| |
| <p>The <var>whence</var> argument specifies how the <var>offset</var> should be |
| interpreted, in the same way as for the <code>fseek</code> function, and it must |
| be one of the symbolic constants <code>SEEK_SET</code>, <code>SEEK_CUR</code>, or |
| <code>SEEK_END</code>. |
| |
| <dl> |
| <dt><code>SEEK_SET</code><dd>Specifies that <var>whence</var> is a count of characters from the beginning |
| of the file. |
| |
| <br><dt><code>SEEK_CUR</code><dd>Specifies that <var>whence</var> is a count of characters from the current |
| file position. This count may be positive or negative. |
| |
| <br><dt><code>SEEK_END</code><dd>Specifies that <var>whence</var> is a count of characters from the end of |
| the file. A negative count specifies a position within the current |
| extent of the file; a positive count specifies a position past the |
| current end. If you set the position past the current end, and |
| actually write data, you will extend the file with zeros up to that |
| position. |
| </dl> |
| |
| <p>The return value from <code>lseek</code> is normally the resulting file |
| position, measured in bytes from the beginning of the file. |
| You can use this feature together with <code>SEEK_CUR</code> to read the |
| current file position. |
| |
| <p>If you want to append to the file, setting the file position to the |
| current end of file with <code>SEEK_END</code> is not sufficient. Another |
| process may write more data after you seek but before you write, |
| extending the file so the position you write onto clobbers their data. |
| Instead, use the <code>O_APPEND</code> operating mode; see <a href="Operating-Modes.html#Operating-Modes">Operating Modes</a>. |
| |
| <p>You can set the file position past the current end of the file. This |
| does not by itself make the file longer; <code>lseek</code> never changes the |
| file. But subsequent output at that position will extend the file. |
| Characters between the previous end of file and the new position are |
| filled with zeros. Extending the file in this way can create a |
| “hole”: the blocks of zeros are not actually allocated on disk, so the |
| file takes up less space than it appears to; it is then called a |
| “sparse file”. |
| <a name="index-sparse-files-1221"></a><a name="index-holes-in-files-1222"></a> |
| If the file position cannot be changed, or the operation is in some way |
| invalid, <code>lseek</code> returns a value of -1. The following |
| <code>errno</code> error conditions are defined for this function: |
| |
| <dl> |
| <dt><code>EBADF</code><dd>The <var>filedes</var> is not a valid file descriptor. |
| |
| <br><dt><code>EINVAL</code><dd>The <var>whence</var> argument value is not valid, or the resulting |
| file offset is not valid. A file offset is invalid. |
| |
| <br><dt><code>ESPIPE</code><dd>The <var>filedes</var> corresponds to an object that cannot be positioned, |
| such as a pipe, FIFO or terminal device. (POSIX.1 specifies this error |
| only for pipes and FIFOs, but in the GNU system, you always get |
| <code>ESPIPE</code> if the object is not seekable.) |
| </dl> |
| |
| <p>When the source file is compiled with <code>_FILE_OFFSET_BITS == 64</code> the |
| <code>lseek</code> function is in fact <code>lseek64</code> and the type |
| <code>off_t</code> has 64 bits which makes it possible to handle files up to |
| 2^63 bytes in length. |
| |
| <p>This function is a cancellation point in multi-threaded programs. This |
| is a problem if the thread allocates some resources (like memory, file |
| descriptors, semaphores or whatever) at the time <code>lseek</code> is |
| called. If the thread gets canceled these resources stay allocated |
| until the program ends. To avoid this calls to <code>lseek</code> should be |
| protected using cancellation handlers. |
| <!-- ref pthread_cleanup_push / pthread_cleanup_pop --> |
| |
| <p>The <code>lseek</code> function is the underlying primitive for the |
| <code>fseek</code>, <code>fseeko</code>, <code>ftell</code>, <code>ftello</code> and |
| <code>rewind</code> functions, which operate on streams instead of file |
| descriptors. |
| </p></blockquote></div> |
| |
| <!-- unistd.h --> |
| <!-- Unix98 --> |
| <div class="defun"> |
| — Function: off64_t <b>lseek64</b> (<var>int filedes, off64_t offset, int whence</var>)<var><a name="index-lseek64-1223"></a></var><br> |
| <blockquote><p>This function is similar to the <code>lseek</code> function. The difference |
| is that the <var>offset</var> parameter is of type <code>off64_t</code> instead of |
| <code>off_t</code> which makes it possible on 32 bit machines to address |
| files larger than 2^31 bytes and up to 2^63 bytes. The |
| file descriptor <code>filedes</code> must be opened using <code>open64</code> since |
| otherwise the large offsets possible with <code>off64_t</code> will lead to |
| errors with a descriptor in small file mode. |
| |
| <p>When the source file is compiled with <code>_FILE_OFFSET_BITS == 64</code> on a |
| 32 bits machine this function is actually available under the name |
| <code>lseek</code> and so transparently replaces the 32 bit interface. |
| </p></blockquote></div> |
| |
| <p>You can have multiple descriptors for the same file if you open the file |
| more than once, or if you duplicate a descriptor with <code>dup</code>. |
| Descriptors that come from separate calls to <code>open</code> have independent |
| file positions; using <code>lseek</code> on one descriptor has no effect on the |
| other. For example, |
| |
| <pre class="smallexample"> { |
| int d1, d2; |
| char buf[4]; |
| d1 = open ("foo", O_RDONLY); |
| d2 = open ("foo", O_RDONLY); |
| lseek (d1, 1024, SEEK_SET); |
| read (d2, buf, 4); |
| } |
| </pre> |
| <p class="noindent">will read the first four characters of the file <samp><span class="file">foo</span></samp>. (The |
| error-checking code necessary for a real program has been omitted here |
| for brevity.) |
| |
| <p>By contrast, descriptors made by duplication share a common file |
| position with the original descriptor that was duplicated. Anything |
| which alters the file position of one of the duplicates, including |
| reading or writing data, affects all of them alike. Thus, for example, |
| |
| <pre class="smallexample"> { |
| int d1, d2, d3; |
| char buf1[4], buf2[4]; |
| d1 = open ("foo", O_RDONLY); |
| d2 = dup (d1); |
| d3 = dup (d2); |
| lseek (d3, 1024, SEEK_SET); |
| read (d1, buf1, 4); |
| read (d2, buf2, 4); |
| } |
| </pre> |
| <p class="noindent">will read four characters starting with the 1024'th character of |
| <samp><span class="file">foo</span></samp>, and then four more characters starting with the 1028'th |
| character. |
| |
| <!-- sys/types.h --> |
| <!-- POSIX.1 --> |
| <div class="defun"> |
| — Data Type: <b>off_t</b><var><a name="index-off_005ft-1224"></a></var><br> |
| <blockquote><p>This is an arithmetic data type used to represent file sizes. |
| In the GNU system, this is equivalent to <code>fpos_t</code> or <code>long int</code>. |
| |
| <p>If the source is compiled with <code>_FILE_OFFSET_BITS == 64</code> this type |
| is transparently replaced by <code>off64_t</code>. |
| </p></blockquote></div> |
| |
| <!-- sys/types.h --> |
| <!-- Unix98 --> |
| <div class="defun"> |
| — Data Type: <b>off64_t</b><var><a name="index-off64_005ft-1225"></a></var><br> |
| <blockquote><p>This type is used similar to <code>off_t</code>. The difference is that even |
| on 32 bit machines, where the <code>off_t</code> type would have 32 bits, |
| <code>off64_t</code> has 64 bits and so is able to address files up to |
| 2^63 bytes in length. |
| |
| <p>When compiling with <code>_FILE_OFFSET_BITS == 64</code> this type is |
| available under the name <code>off_t</code>. |
| </p></blockquote></div> |
| |
| <p>These aliases for the ‘<samp><span class="samp">SEEK_...</span></samp>’ constants exist for the sake |
| of compatibility with older BSD systems. They are defined in two |
| different header files: <samp><span class="file">fcntl.h</span></samp> and <samp><span class="file">sys/file.h</span></samp>. |
| |
| <dl> |
| <dt><code>L_SET</code><dd>An alias for <code>SEEK_SET</code>. |
| |
| <br><dt><code>L_INCR</code><dd>An alias for <code>SEEK_CUR</code>. |
| |
| <br><dt><code>L_XTND</code><dd>An alias for <code>SEEK_END</code>. |
| </dl> |
| |
| </body></html> |
| |
