| blob | 01bd34c5bf25e403010d04e85baad95a95a09bd4 |
1 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
2 .\" All rights reserved.
3 .\"
4 .\" This code is derived from software contributed to Berkeley by
5 .\" Chris Torek and the American National Standards Committee X3,
6 .\" on Information Processing Systems.
7 .\"
8 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. All advertising materials mentioning features or use of this software
18 .\" must display the following acknowledgement:
19 .\" This product includes software developed by the University of
20 .\" California, Berkeley and its contributors.
21 .\" 4. Neither the name of the University nor the names of its contributors
22 .\" may be used to endorse or promote products derived from this software
23 .\" without specific prior written permission.
24 .\"
25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .\" SUCH DAMAGE.
36 .\" %%%LICENSE_END
37 .\"
38 .\" @(#)fseek.3 6.11 (Berkeley) 6/29/91
39 .\"
40 .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu
41 .\"
42 .TH FSEEK 3 2021-03-22 "GNU" "Linux Programmer's Manual"
43 .SH NAME
44 fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream
45 .SH SYNOPSIS
46 .nf
47 .B #include <stdio.h>
48 .PP
49 .BI "int fseek(FILE *" stream ", long " offset ", int " whence );
50 .BI "long ftell(FILE *" stream );
51 .PP
52 .BI "void rewind(FILE *" stream );
53 .PP
54 .BI "int fgetpos(FILE *restrict " stream ", fpos_t *restrict " pos );
55 .BI "int fsetpos(FILE *" stream ", const fpos_t *" pos );
56 .fi
57 .SH DESCRIPTION
58 The
59 .BR fseek ()
60 function sets the file position indicator for the stream pointed to by
61 .IR stream .
62 The new position, measured in bytes, is obtained by adding
63 .I offset
64 bytes to the position specified by
65 .IR whence .
66 If
67 .I whence
68 is set to
69 .BR SEEK_SET ,
70 .BR SEEK_CUR ,
71 or
72 .BR SEEK_END ,
73 the offset is relative to the start of the file, the current position
74 indicator, or end-of-file, respectively.
75 A successful call to the
76 .BR fseek ()
77 function clears the end-of-file indicator for the stream and undoes
78 any effects of the
79 .BR ungetc (3)
80 function on the same stream.
81 .PP
82 The
83 .BR ftell ()
84 function obtains the current value of the file position indicator for the
85 stream pointed to by
86 .IR stream .
87 .PP
88 The
89 .BR rewind ()
90 function sets the file position indicator for the stream pointed to by
91 .I stream
92 to the beginning of the file.
93 It is equivalent to:
94 .PP
95 .RS
96 (void) fseek(stream, 0L, SEEK_SET)
97 .RE
98 .PP
99 except that the error indicator for the stream is also cleared (see
100 .BR clearerr (3)).
101 .PP
102 The
103 .BR fgetpos ()
104 and
105 .BR fsetpos ()
106 functions are alternate interfaces equivalent to
107 .BR ftell ()
108 and
109 .BR fseek ()
110 (with
111 .I whence
112 set to
113 .BR SEEK_SET ),
114 setting and storing the current value of the file offset into or from the
115 object referenced by
116 .IR pos .
117 On some non-UNIX systems, an
118 .I fpos_t
119 object may be a complex object and these routines may be the only way to
120 portably reposition a text stream.
121 .SH RETURN VALUE
122 The
123 .BR rewind ()
124 function returns no value.
125 Upon successful completion,
126 .BR fgetpos (),
127 .BR fseek (),
128 .BR fsetpos ()
129 return 0,
130 and
131 .BR ftell ()
132 returns the current offset.
133 Otherwise, \-1 is returned and
134 .I errno
135 is set to indicate the error.
136 .SH ERRORS
137 .TP
138 .B EINVAL
139 The
140 .I whence
141 argument to
142 .BR fseek ()
143 was not
144 .BR SEEK_SET ,
145 .BR SEEK_END ,
146 or
147 .BR SEEK_CUR .
148 Or: the resulting file offset would be negative.
149 .TP
150 .B ESPIPE
151 The file descriptor underlying
152 .I stream
153 is not seekable (e.g., it refers to a pipe, FIFO, or socket).
154 .PP
155 The functions
156 .BR fgetpos (),
157 .BR fseek (),
158 .BR fsetpos (),
159 and
160 .BR ftell ()
161 may also fail and set
162 .I errno
163 for any of the errors specified for the routines
164 .BR fflush (3),
165 .BR fstat (2),
166 .BR lseek (2),
167 and
168 .BR malloc (3).
169 .SH ATTRIBUTES
170 For an explanation of the terms used in this section, see
171 .BR attributes (7).
172 .ad l
173 .nh
174 .TS
175 allbox;
176 lbx lb lb
177 l l l.
178 Interface Attribute Value
179 T{
180 .BR fseek (),
181 .BR ftell (),
182 .BR rewind (),
183 .BR fgetpos (),
184 .BR fsetpos ()
185 T} Thread safety MT-Safe
186 .TE
187 .hy
188 .ad
189 .sp 1
190 .SH CONFORMING TO
191 POSIX.1-2001, POSIX.1-2008, C89, C99.
192 .SH SEE ALSO
193 .BR lseek (2),
194 .BR fseeko (3)