xref: /minix3/lib/libc/stdio/fseek.3 (revision f14fb602092e015ff630df58e17c2a9cd57d29b3)
1.\"	$NetBSD: fseek.3,v 1.27 2012/01/22 19:13:42 wiz Exp $
2.\"
3.\" Copyright (c) 1990, 1991, 1993
4.\"	The Regents of the University of California.  All rights reserved.
5.\"
6.\" This code is derived from software contributed to Berkeley by
7.\" Chris Torek and the American National Standards Committee X3,
8.\" on Information Processing Systems.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\"    notice, this list of conditions and the following disclaimer in the
17.\"    documentation and/or other materials provided with the distribution.
18.\" 3. Neither the name of the University nor the names of its contributors
19.\"    may be used to endorse or promote products derived from this software
20.\"    without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\"     @(#)fseek.3	8.1 (Berkeley) 6/4/93
35.\"
36.Dd January 21, 2012
37.Dt FSEEK 3
38.Os
39.Sh NAME
40.Nm fgetpos ,
41.Nm fseek ,
42.Nm fseeko ,
43.Nm fsetpos ,
44.Nm ftell ,
45.Nm ftello ,
46.Nm rewind
47.Nd reposition a stream
48.Sh LIBRARY
49.Lb libc
50.Sh SYNOPSIS
51.In stdio.h
52.Ft int
53.Fn fseek "FILE *stream" "long int offset" "int whence"
54.Ft int
55.Fn fseeko "FILE *stream" "off_t offset" "int whence"
56.Ft long int
57.Fn ftell "FILE *stream"
58.Ft off_t
59.Fn ftello "FILE *stream"
60.Ft void
61.Fn rewind "FILE *stream"
62.Ft int
63.Fn fgetpos "FILE * restrict stream" "fpos_t * restrict pos"
64.Ft int
65.Fn fsetpos "FILE * restrict stream" "const fpos_t * restrict pos"
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
91function on the same stream.
92.Pp
93The
94.Fn fseeko
95function is identical to the
96.Fn fseek
97function except that the
98.Fa offset
99argument is of type
100.Fa off_t .
101.Pp
102The
103.Fn ftell
104function
105obtains the current value of the file position indicator for the
106stream pointed to by
107.Fa stream .
108.Pp
109The
110.Fn ftello
111function is identical to the
112.Fn ftell
113function except that the return value is of type
114.Fa off_t .
115.Pp
116The
117.Fn rewind
118function sets the file position indicator for the stream pointed
119to by
120.Fa stream
121to the beginning of the file.
122It is equivalent to:
123.Pp
124.Dl (void)fseek(stream, 0L, SEEK_SET)
125.Pp
126except that the error indicator for the stream is also cleared
127(see
128.Xr clearerr 3 ) .
129.Pp
130In this implementations, an
131.Dq Fa fpos_t
132object is a complex object that represents both the position and the parse
133state of the stream making these routines are the only way to portably
134reposition a text stream.
135The
136.Ar pos
137argument of
138.Fn fsetpos
139must always be initialized by
140a call to
141.Fn fgetpos .
142.Sh RETURN VALUES
143The
144.Fn rewind
145function
146returns no value.
147Upon successful completion,
148.Fn fgetpos ,
149.Fn fseek ,
150.Fn fseeko ,
151and
152.Fn fsetpos
153return 0.
154The functions
155.Fn ftell
156and
157.Fn ftello
158return the current offset.
159Otherwise,
160.Fn fseek ,
161.Fn fseeko ,
162.Fn ftell ,
163and
164.Fn ftello
165return \-1 while
166.Fn fgetpos
167and
168.Fn fsetpos
169return a nonzero value.
170On error all functions the global variable
171.Va errno
172is set to indicate the error.
173Since the
174.Fn rewind
175function does not return an error code, applications need to clear
176.Va errno
177before calling it in order to detect errors.
178.Sh ERRORS
179.Bl -tag -width Er
180.It Bq Er EBADF
181The
182.Fa stream
183specified
184is not a seekable stream.
185.It Bq Er EINVAL
186The
187.Fa whence
188argument to
189.Fn fseek
190was not
191.Dv SEEK_SET ,
192.Dv SEEK_END ,
193or
194.Dv SEEK_CUR .
195.It Bq Er EOVERFLOW
196For
197.Fn ftell ,
198the current file offset cannot be represented correctly in an object of type
199.Fa long .
200.El
201.Pp
202The function
203.Fn fgetpos ,
204.Fn fseek ,
205.Fn fseeko ,
206.Fn fsetpos ,
207.Fn ftell ,
208.Fn ftello ,
209and
210.Fn rewind
211may also fail and set
212.Va errno
213for any of the errors specified for the routines
214.Xr fflush 3 ,
215.Xr fstat 2 ,
216.Xr lseek 2 ,
217and
218.Xr malloc 3 .
219.Sh SEE ALSO
220.Xr lseek 2
221.Sh STANDARDS
222The
223.Fn fgetpos ,
224.Fn fsetpos ,
225.Fn fseek ,
226.Fn ftell ,
227and
228.Fn rewind
229functions
230conform to
231.St -ansiC .
232The
233.Fn fseeko
234and
235.Fn ftello
236functions conform to
237.St -xsh5 .
238.Sh BUGS
239The
240.Fn fgetpos
241and
242.Fn fsetpos
243functions don't store/set shift states of the stream in this implementation.
244