]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da MK |
2 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
3 | .\" All rights reserved. | |
4 | .\" | |
5 | .\" This code is derived from software contributed to Berkeley by | |
6 | .\" Chris Torek and the American National Standards Committee X3, | |
7 | .\" on Information Processing Systems. | |
8 | .\" | |
47009d5e | 9 | .\" SPDX-License-Identifier: BSD-4-Clause-UC |
fea681da MK |
10 | .\" |
11 | .\" @(#)fseek.3 6.11 (Berkeley) 6/29/91 | |
12 | .\" | |
13 | .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu | |
14 | .\" | |
4c1c5274 | 15 | .TH fseek 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
16 | .SH NAME |
17 | fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream | |
cfba38f4 AC |
18 | .SH LIBRARY |
19 | Standard C library | |
20 | .RI ( libc ", " \-lc ) | |
fea681da | 21 | .SH SYNOPSIS |
15d65653 | 22 | .nf |
fea681da | 23 | .B #include <stdio.h> |
68e4db0a | 24 | .PP |
fea681da | 25 | .BI "int fseek(FILE *" stream ", long " offset ", int " whence ); |
fea681da | 26 | .BI "long ftell(FILE *" stream ); |
dbfe9c70 | 27 | .PP |
fea681da | 28 | .BI "void rewind(FILE *" stream ); |
dbfe9c70 | 29 | .PP |
2b19457a | 30 | .BI "int fgetpos(FILE *restrict " stream ", fpos_t *restrict " pos ); |
d19a532b | 31 | .BI "int fsetpos(FILE *" stream ", const fpos_t *" pos ); |
15d65653 | 32 | .fi |
fea681da MK |
33 | .SH DESCRIPTION |
34 | The | |
e511ffb6 | 35 | .BR fseek () |
fea681da MK |
36 | function sets the file position indicator for the stream pointed to by |
37 | .IR stream . | |
38 | The new position, measured in bytes, is obtained by adding | |
39 | .I offset | |
40 | bytes to the position specified by | |
41 | .IR whence . | |
42 | If | |
43 | .I whence | |
44 | is set to | |
45 | .BR SEEK_SET , | |
46 | .BR SEEK_CUR , | |
47 | or | |
48 | .BR SEEK_END , | |
49 | the offset is relative to the start of the file, the current position | |
c13182ef MK |
50 | indicator, or end-of-file, respectively. |
51 | A successful call to the | |
e511ffb6 | 52 | .BR fseek () |
fea681da MK |
53 | function clears the end-of-file indicator for the stream and undoes |
54 | any effects of the | |
55 | .BR ungetc (3) | |
56 | function on the same stream. | |
57 | .PP | |
58 | The | |
e511ffb6 | 59 | .BR ftell () |
fea681da MK |
60 | function obtains the current value of the file position indicator for the |
61 | stream pointed to by | |
62 | .IR stream . | |
63 | .PP | |
64 | The | |
e511ffb6 | 65 | .BR rewind () |
fea681da MK |
66 | function sets the file position indicator for the stream pointed to by |
67 | .I stream | |
c13182ef MK |
68 | to the beginning of the file. |
69 | It is equivalent to: | |
fea681da MK |
70 | .PP |
71 | .RS | |
0c535394 | 72 | (void) fseek(stream, 0L, SEEK_SET) |
fea681da MK |
73 | .RE |
74 | .PP | |
75 | except that the error indicator for the stream is also cleared (see | |
76 | .BR clearerr (3)). | |
77 | .PP | |
78 | The | |
e511ffb6 | 79 | .BR fgetpos () |
fea681da | 80 | and |
e511ffb6 | 81 | .BR fsetpos () |
fea681da | 82 | functions are alternate interfaces equivalent to |
e511ffb6 | 83 | .BR ftell () |
fea681da | 84 | and |
e511ffb6 | 85 | .BR fseek () |
949aff4c MK |
86 | (with |
87 | .I whence | |
88 | set to | |
fea681da MK |
89 | .BR SEEK_SET ), |
90 | setting and storing the current value of the file offset into or from the | |
91 | object referenced by | |
92 | .IR pos . | |
824464a9 | 93 | On some non-UNIX systems, an |
f19a0f03 | 94 | .I fpos_t |
fea681da MK |
95 | object may be a complex object and these routines may be the only way to |
96 | portably reposition a text stream. | |
d8ce99e3 | 97 | .PP |
98 | If the stream refers to a regular file | |
99 | and the resulting stream offset is beyond the size of the file, | |
100 | subsequent writes will extend the file with a hole, up to the offset, | |
101 | before committing any data. | |
102 | See | |
103 | .BR lseek (2) | |
104 | for details on file seeking semantics. | |
47297adb | 105 | .SH RETURN VALUE |
fea681da | 106 | The |
e511ffb6 | 107 | .BR rewind () |
c13182ef MK |
108 | function returns no value. |
109 | Upon successful completion, | |
e511ffb6 MK |
110 | .BR fgetpos (), |
111 | .BR fseek (), | |
112 | .BR fsetpos () | |
fea681da MK |
113 | return 0, |
114 | and | |
e511ffb6 | 115 | .BR ftell () |
c13182ef MK |
116 | returns the current offset. |
117 | Otherwise, \-1 is returned and | |
118 | .I errno | |
845f2c47 | 119 | is set to indicate the error. |
fea681da MK |
120 | .SH ERRORS |
121 | .TP | |
fea681da MK |
122 | .B EINVAL |
123 | The | |
124 | .I whence | |
c13182ef | 125 | argument to |
e511ffb6 | 126 | .BR fseek () |
fea681da MK |
127 | was not |
128 | .BR SEEK_SET , | |
129 | .BR SEEK_END , | |
130 | or | |
131 | .BR SEEK_CUR . | |
f3ef4558 | 132 | Or: the resulting file offset would be negative. |
f2e2bdc0 MK |
133 | .TP |
134 | .B ESPIPE | |
f019faae | 135 | The file descriptor underlying |
f2e2bdc0 | 136 | .I stream |
f019faae | 137 | is not seekable (e.g., it refers to a pipe, FIFO, or socket). |
fea681da | 138 | .PP |
845f2c47 | 139 | The functions |
e511ffb6 MK |
140 | .BR fgetpos (), |
141 | .BR fseek (), | |
142 | .BR fsetpos (), | |
c13182ef | 143 | and |
e511ffb6 | 144 | .BR ftell () |
fea681da MK |
145 | may also fail and set |
146 | .I errno | |
147 | for any of the errors specified for the routines | |
148 | .BR fflush (3), | |
149 | .BR fstat (2), | |
150 | .BR lseek (2), | |
c13182ef | 151 | and |
fea681da | 152 | .BR malloc (3). |
011bc011 MS |
153 | .SH ATTRIBUTES |
154 | For an explanation of the terms used in this section, see | |
155 | .BR attributes (7). | |
156 | .TS | |
157 | allbox; | |
c466875e | 158 | lbx lb lb |
011bc011 MS |
159 | l l l. |
160 | Interface Attribute Value | |
161 | T{ | |
9e54434e BR |
162 | .na |
163 | .nh | |
011bc011 MS |
164 | .BR fseek (), |
165 | .BR ftell (), | |
166 | .BR rewind (), | |
011bc011 MS |
167 | .BR fgetpos (), |
168 | .BR fsetpos () | |
169 | T} Thread safety MT-Safe | |
170 | .TE | |
847e0d88 | 171 | .sp 1 |
3113c7f3 | 172 | .SH STANDARDS |
4131356c AC |
173 | C11, POSIX.1-2008. |
174 | .SH HISTORY | |
175 | POSIX.1-2001, C89. | |
47297adb | 176 | .SH SEE ALSO |
fea681da MK |
177 | .BR lseek (2), |
178 | .BR fseeko (3) |