xref: /freebsd/lib/libc/stdio/fseek.3 (revision f5147e312f43a9050468de539aeafa072caa1a60)
1.\" Copyright (c) 1990, 1991, 1993
2.\"	The Regents of the University of California.  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.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\" 3. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     @(#)fseek.3	8.1 (Berkeley) 6/4/93
33.\" $FreeBSD$
34.\"
35.Dd March 19, 2004
36.Dt FSEEK 3
37.Os
38.Sh NAME
39.Nm fgetpos ,
40.Nm fseek ,
41.Nm fseeko ,
42.Nm fsetpos ,
43.Nm ftell ,
44.Nm ftello ,
45.Nm rewind
46.Nd reposition a stream
47.Sh LIBRARY
48.Lb libc
49.Sh SYNOPSIS
50.In stdio.h
51.Ft int
52.Fn fseek "FILE *stream" "long offset" "int whence"
53.Ft long
54.Fn ftell "FILE *stream"
55.Ft void
56.Fn rewind "FILE *stream"
57.Ft int
58.Fn fgetpos "FILE * restrict stream" "fpos_t * restrict pos"
59.Ft int
60.Fn fsetpos "FILE *stream" "const fpos_t *pos"
61.In sys/types.h
62.Ft int
63.Fn fseeko "FILE *stream" "off_t offset" "int whence"
64.Ft off_t
65.Fn ftello "FILE *stream"
66.Sh DESCRIPTION
67The
68.Fn fseek
69function sets the file position indicator for the stream pointed
70to by
71.Fa stream .
72The new position, measured in bytes, is obtained by adding
73.Fa offset
74bytes to the position specified by
75.Fa whence .
76If
77.Fa whence
78is set to
79.Dv SEEK_SET ,
80.Dv SEEK_CUR ,
81or
82.Dv SEEK_END ,
83the offset is relative to the
84start of the file, the current position indicator, or end-of-file,
85respectively.
86A successful call to the
87.Fn fseek
88function clears the end-of-file indicator for the stream and undoes
89any effects of the
90.Xr ungetc 3
91and
92.Xr ungetwc 3
93functions on the same stream.
94.Pp
95The
96.Fn ftell
97function
98obtains the current value of the file position indicator for the
99stream pointed to by
100.Fa stream .
101.Pp
102The
103.Fn rewind
104function sets the file position indicator for the stream pointed
105to by
106.Fa stream
107to the beginning of the file.
108It is equivalent to:
109.Pp
110.Dl (void)fseek(stream, 0L, SEEK_SET)
111.Pp
112except that the error indicator for the stream is also cleared
113(see
114.Xr clearerr 3 ) .
115.Pp
116Since
117.Fn rewind
118does not return a value,
119an application wishing to detect errors should clear
120.Va errno ,
121then call
122.Fn rewind ,
123and if
124.Va errno
125is non-zero, assume an error has occurred.
126.Pp
127The
128.Fn fseeko
129function is identical to
130.Fn fseek ,
131except it takes an
132.Fa off_t
133argument
134instead of a
135.Fa long .
136Likewise, the
137.Fn ftello
138function is identical to
139.Fn ftell ,
140except it returns an
141.Fa off_t .
142.Pp
143The
144.Fn fgetpos
145and
146.Fn fsetpos
147functions
148are alternate interfaces for retrieving and setting the current position in
149the file, similar to
150.Fn ftell
151and
152.Fn fseek ,
153except that the current position is stored in an opaque object of
154type
155.Vt fpos_t
156pointed to by
157.Fa pos .
158These functions provide a portable way to seek to offsets larger than
159those that can be represented by a
160.Vt long int .
161They may also store additional state information in the
162.Vt fpos_t
163object to facilitate seeking within files containing multibyte
164characters with state-dependent encodings.
165Although
166.Vt fpos_t
167has traditionally been an integral type,
168applications cannot assume that it is;
169in particular, they must not perform arithmetic on objects
170of this type.
171.Pp
172If the stream is a wide character stream (see
173.Xr fwide 3 ) ,
174the position specified by the combination of
175.Fa offset
176and
177.Fa whence
178must contain the first byte of a multibyte sequence.
179.Sh RETURN VALUES
180The
181.Fn rewind
182function
183returns no value.
184.Pp
185.Rv -std fgetpos fseek fseeko fsetpos
186.Pp
187Upon successful completion,
188.Fn ftell
189and
190.Fn ftello
191return the current offset.
192Otherwise, \-1 is returned and the global variable
193.Va errno
194is set to indicate the error.
195.Sh ERRORS
196.Bl -tag -width Er
197.It Bq Er EBADF
198The
199.Fa stream
200argument
201is not a seekable stream.
202.It Bq Er EINVAL
203The
204.Fa whence
205argument is invalid or
206the resulting file-position
207indicator would be set to a negative value.
208.It Bq Er EOVERFLOW
209The resulting file offset would be a value which
210cannot be represented correctly in an object of type
211.Fa off_t
212for
213.Fn fseeko
214and
215.Fn ftello
216or
217.Fa long
218for
219.Fn fseek
220and
221.Fn ftell .
222.It Bq Er ESPIPE
223The file descriptor underlying stream is associated with a pipe or FIFO
224or file-position indicator value is unspecified
225(see
226.Xr ungetc 3 ) .
227.El
228.Pp
229The functions
230.Fn fgetpos ,
231.Fn fseek ,
232.Fn fseeko ,
233.Fn fsetpos ,
234.Fn ftell ,
235.Fn ftello ,
236and
237.Fn rewind
238may also fail and set
239.Va errno
240for any of the errors specified for the routines
241.Xr fflush 3 ,
242.Xr fstat 2 ,
243.Xr lseek 2 ,
244and
245.Xr malloc 3 .
246.Sh SEE ALSO
247.Xr lseek 2 ,
248.Xr clearerr 3 ,
249.Xr fwide 3 ,
250.Xr ungetc 3 ,
251.Xr ungetwc 3
252.Sh STANDARDS
253The
254.Fn fgetpos ,
255.Fn fsetpos ,
256.Fn fseek ,
257.Fn ftell ,
258and
259.Fn rewind
260functions
261conform to
262.St -isoC .
263.Pp
264The
265.Fn fseeko
266and
267.Fn ftello
268functions conform to
269.St -p1003.1-2001 .
270