1LSEEK(P)                   POSIX Programmer's Manual                  LSEEK(P)
2
3
4

NAME

6       lseek - move the read/write file offset
7

SYNOPSIS

9       #include <unistd.h>
10
11       off_t lseek(int fildes, off_t offset, int whence);
12
13

DESCRIPTION

15       The  lseek()  function  shall  set  the  file  offset for the open file
16       description associated with the file descriptor fildes, as follows:
17
18        * If whence is SEEK_SET, the file offset shall be set to offset bytes.
19
20        * If whence is SEEK_CUR, the file offset shall be set to  its  current
21          location plus offset.
22
23        * If  whence  is SEEK_END, the file offset shall be set to the size of
24          the file plus offset.
25
26       The symbolic constants SEEK_SET, SEEK_CUR, and SEEK_END are defined  in
27       <unistd.h>.
28
29       The  behavior  of  lseek() on devices which are incapable of seeking is
30       implementation-defined. The value of the file  offset  associated  with
31       such a device is undefined.
32
33       The  lseek()  function shall allow the file offset to be set beyond the
34       end of the existing data in the file. If data is later written at  this
35       point,  subsequent reads of data in the gap shall return bytes with the
36       value 0 until data is actually written into the gap.
37
38       The lseek() function shall not, by itself, extend the size of a file.
39
40       If fildes refers to a shared memory object, the result of  the  lseek()
41       function is unspecified.
42
43       If  fildes  refers  to a typed memory object, the result of the lseek()
44       function is unspecified.
45

RETURN VALUE

47       Upon successful completion, the resulting offset, as measured in  bytes
48       from  the  beginning  of  the  file,  shall  be  returned.   Otherwise,
49       (off_t)-1 shall be returned, errno shall be set to indicate the  error,
50       and the file offset shall remain unchanged.
51

ERRORS

53       The lseek() function shall fail if:
54
55       EBADF  The fildes argument is not an open file descriptor.
56
57       EINVAL The whence argument is not a proper value, or the resulting file
58              offset would be negative for a regular file, block special file,
59              or directory.
60
61       EOVERFLOW
62              The  resulting file offset would be a value which cannot be rep‐
63              resented correctly in an object of type off_t.
64
65       ESPIPE The fildes argument is associated with a pipe, FIFO, or socket.
66
67
68       The following sections are informative.
69

EXAMPLES

71       None.
72

APPLICATION USAGE

74       None.
75

RATIONALE

77       The ISO C standard includes  the  functions  fgetpos()  and  fsetpos(),
78       which work on very large files by use of a special positioning type.
79
80       Although  lseek()  may  position  the file offset beyond the end of the
81       file, this function does not itself extend the size of the file.  While
82       the  only function in IEEE Std 1003.1-2001 that may directly extend the
83       size of the file is write(), truncate(), and ftruncate(), several func‐
84       tions  originally  derived  from  the ISO C standard, such as fwrite(),
85       fprintf(), and so on, may do so (by causing calls on write()).
86
87       An invalid file offset that would cause [EINVAL] to be returned may  be
88       both  implementation-defined  and device-dependent (for example, memory
89       may have few invalid values). A negative file offset may be  valid  for
90       some devices in some implementations.
91
92       The  POSIX.1-1990  standard  did not specifically prohibit lseek() from
93       returning a negative offset. Therefore, an application was required  to
94       clear  errno prior to the call and check errno upon return to determine
95       whether a return value of ( off_t)-1 is a negative offset or an indica‐
96       tion  of  an  error  condition. The standard developers did not wish to
97       require this action on the part of a conforming application, and  chose
98       to require that errno be set to [EINVAL] when the resulting file offset
99       would be negative for a regular file, block special file, or directory.
100

FUTURE DIRECTIONS

102       None.
103

SEE ALSO

105       open()  ,  the  Base  Definitions   volume   of   IEEE Std 1003.1-2001,
106       <sys/types.h>, <unistd.h>
107

109       Portions  of  this text are reprinted and reproduced in electronic form
110       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
111       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
112       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
113       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
114       event of any discrepancy between this version and the original IEEE and
115       The  Open Group Standard, the original IEEE and The Open Group Standard
116       is the referee document. The original Standard can be  obtained  online
117       at http://www.opengroup.org/unix/online.html .
118
119
120
121IEEE/The Open Group                  2003                             LSEEK(P)
Impressum