projects / unix-history / blame
| Commit | Line | Data |
|---|---|---|
| ec7838a8 KM |
1 | .\" Copyright (c) 1980 Regents of the University of California. |
| 2 | .\" All rights reserved. The Berkeley software License Agreement | |
| 3 | .\" specifies the terms and conditions for redistribution. | |
| 4 | .\" | |
| d1c0365c | 5 | .\" @(#)lseek.2 6.3 (Berkeley) %G% |
| ec7838a8 | 6 | .\" |
| ed86ee10 | 7 | .TH LSEEK 2 "" |
| ec7838a8 KM |
8 | .UC 4 |
| 9 | .SH NAME | |
| 84648ee2 | 10 | lseek \- move read/write pointer |
| ec7838a8 KM |
11 | .SH SYNOPSIS |
| 12 | .nf | |
| 84648ee2 | 13 | .ft B |
| ed86ee10 KM |
14 | #include <sys/file.h> |
| 15 | .PP | |
| 16 | .nf | |
| 17 | .ft B | |
| 18 | .ta 1.25i 1.6i 1.8i | |
| 84648ee2 KM |
19 | #define L_SET 0 /* set the seek pointer */ |
| 20 | #define L_INCR 1 /* increment the seek pointer */ | |
| 21 | #define L_XTND 2 /* extend the file size */ | |
| ec7838a8 | 22 | .PP |
| 84648ee2 KM |
23 | .ft B |
| 24 | pos = lseek(d, offset, whence) | |
| ed86ee10 KM |
25 | off_t pos; |
| 26 | int d; | |
| 27 | off_t offset; | |
| 28 | int whence; | |
| ec7838a8 | 29 | .fi |
| 84648ee2 | 30 | .ft R |
| ec7838a8 | 31 | .SH DESCRIPTION |
| 84648ee2 KM |
32 | The descriptor |
| 33 | .I d | |
| 34 | refers to a file or device open for reading and/or writing. | |
| 35 | .I Lseek | |
| 36 | sets the file pointer of | |
| 37 | .I d | |
| 38 | as follows: | |
| ec7838a8 KM |
39 | .IP |
| 40 | If | |
| 41 | .I whence | |
| 84648ee2 | 42 | is L_SET, the pointer is set to |
| ec7838a8 KM |
43 | .I offset |
| 44 | bytes. | |
| 45 | .IP | |
| 46 | If | |
| 47 | .I whence | |
| 84648ee2 | 48 | is L_INCR, the pointer is set to its current location plus |
| ec7838a8 KM |
49 | .IR offset . |
| 50 | .IP | |
| 51 | If | |
| 52 | .I whence | |
| 84648ee2 | 53 | is L_XTND, the pointer is set to the size of the |
| ec7838a8 KM |
54 | file plus |
| 55 | .IR offset . | |
| 56 | .PP | |
| 84648ee2 KM |
57 | Upon successful completion, the resulting pointer location |
| 58 | as measured in bytes from beginning of the file is returned. | |
| 59 | Some devices are incapable of seeking. The value of the pointer | |
| 60 | associated with such a device is undefined. | |
| 61 | .SH NOTES | |
| ec7838a8 | 62 | Seeking far beyond the end of a file, then writing, |
| 84648ee2 | 63 | creates a gap or \*(lqhole\*(rq, which occupies no |
| ec7838a8 | 64 | physical space and reads as zeros. |
| 84648ee2 | 65 | .SH "RETURN VALUE |
| 594f4c31 KM |
66 | Upon successful completion, |
| 67 | the current file pointer value is returned. | |
| 68 | Otherwise, | |
| 84648ee2 KM |
69 | a value of \-1 is returned and \fIerrno\fP is set to indicate |
| 70 | the error. | |
| 71 | .SH "ERRORS | |
| 72 | .I Lseek | |
| 73 | will fail and the file pointer will remain unchanged if: | |
| 74 | .TP 15 | |
| 75 | [EBADF] | |
| 76 | .I Fildes | |
| 77 | is not an open file descriptor. | |
| 78 | .TP 15 | |
| 79 | [ESPIPE] | |
| 80 | .I Fildes | |
| 81 | is associated with a pipe or a socket. | |
| 82 | .TP 15 | |
| 83 | [EINVAL] | |
| 84 | .I Whence | |
| 85 | is not a proper value. | |
| ec7838a8 | 86 | .SH "SEE ALSO" |
| 84648ee2 | 87 | dup(2), open(2) |
| ec7838a8 | 88 | .SH BUGS |
| 84648ee2 KM |
89 | This document's use of |
| 90 | .I whence | |
| 91 | is incorrect English, but maintained for historical reasons. |