Debian Codegraph @

upstream/debian-unstable/man3/fseek.3

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