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. All advertising materials mentioning features or use of this software
17.\" must display the following acknowledgement:
18.\" This product includes software developed by the University of
19.\" California, Berkeley and its contributors.
20.\" 4. Neither the name of the University nor the names of its contributors
21.\" may be used to endorse or promote products derived from this software
22.\" without specific prior written permission.
23.\"
24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\" @(#)fseek.3 8.1 (Berkeley) 6/4/93
| 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. All advertising materials mentioning features or use of this software
17.\" must display the following acknowledgement:
18.\" This product includes software developed by the University of
19.\" California, Berkeley and its contributors.
20.\" 4. Neither the name of the University nor the names of its contributors
21.\" may be used to endorse or promote products derived from this software
22.\" without specific prior written permission.
23.\"
24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\" @(#)fseek.3 8.1 (Berkeley) 6/4/93
|
37.\" $FreeBSD: head/lib/libc/stdio/fseek.3 79754 2001-07-15 07:53:42Z dd $
| 37.\" $FreeBSD: head/lib/libc/stdio/fseek.3 81666 2001-08-15 02:07:47Z ache $
|
38.\"
39.Dd March 5, 1999
40.Dt FSEEK 3
41.Os
42.Sh NAME
43.Nm fgetpos ,
44.Nm fseek ,
45.Nm fseeko ,
46.Nm fsetpos ,
47.Nm ftell ,
48.Nm ftello ,
49.Nm rewind
50.Nd reposition a stream
51.Sh LIBRARY
52.Lb libc
53.Sh SYNOPSIS
54.Fd #include <stdio.h>
55.Ft int
56.Fn fseek "FILE *stream" "long offset" "int whence"
57.Ft long
58.Fn ftell "FILE *stream"
59.Ft void
60.Fn rewind "FILE *stream"
61.Ft int
62.Fn fgetpos "FILE *stream" "fpos_t *pos"
63.Ft int
64.Fn fsetpos "FILE *stream" "const fpos_t *pos"
65.Fd #include <sys/types.h>
66.Ft int
67.Fn fseeko "FILE *stream" "off_t offset" "int whence"
68.Ft off_t
69.Fn ftello "FILE *stream"
70.Sh DESCRIPTION
71The
72.Fn fseek
73function sets the file position indicator for the stream pointed
74to by
75.Fa stream .
76The new position, measured in bytes, is obtained by adding
77.Fa offset
78bytes to the position specified by
79.Fa whence .
80If
81.Fa whence
82is set to
83.Dv SEEK_SET ,
84.Dv SEEK_CUR ,
85or
86.Dv SEEK_END ,
87the offset is relative to the
88start of the file, the current position indicator, or end-of-file,
89respectively.
90A successful call to the
91.Fn fseek
92function clears the end-of-file indicator for the stream and undoes
93any effects of the
94.Xr ungetc 3
95function on the same stream.
96.Pp
97The
98.Fn ftell
99function
100obtains the current value of the file position indicator for the
101stream pointed to by
102.Fa stream .
103.Pp
104The
105.Fn rewind
106function sets the file position indicator for the stream pointed
107to by
108.Fa stream
109to the beginning of the file.
110It is equivalent to:
111.Pp
112.Dl (void)fseek(stream, 0L, SEEK_SET)
113.Pp
114except that the error indicator for the stream is also cleared
115(see
116.Xr clearerr 3 ) .
117.Pp
118The
119.Fn fseeko
120function is identical to
121.Fn fseek ,
122except it takes an
123.Fa off_t
124argument
125instead of a
126.Fa long .
127Likewise, the
128.Fn ftello
129function is identical to
130.Fn ftell ,
131except it returns an
132.Fa off_t .
133.Pp
134The
135.Fn fgetpos
136and
137.Fn fsetpos
138functions
139are alternate interfaces equivalent to
140.Fn ftell
141and
142.Fn fseek
143(with whence set to
144.Dv SEEK_SET ) ,
145setting and storing the current value of
146the file offset into or from the object referenced by
147.Fa pos .
148On some
149.Pq non- Ns Tn UNIX
150systems an
151.Dq Fa fpos_t
152object may be a complex object
153and these routines may be the only way to portably reposition a text stream.
154.Sh RETURN VALUES
155The
156.Fn rewind
157function
158returns no value.
159Upon successful completion,
160.Fn fgetpos ,
161.Fn fseek ,
162.Fn fseeko ,
163and
164.Fn fsetpos
165return 0,
166and
167.Fn ftell
168and
169.Fn ftello
170return the current offset.
171Otherwise, \-1 is returned and the global variable errno is set to
172indicate the error.
173.Sh ERRORS
174.Bl -tag -width Er
175.It Bq Er EBADF
176The
177.Fa stream
178specified
179is not a seekable stream.
180.It Bq Er EINVAL
181The
182.Fa whence
| 38.\"
39.Dd March 5, 1999
40.Dt FSEEK 3
41.Os
42.Sh NAME
43.Nm fgetpos ,
44.Nm fseek ,
45.Nm fseeko ,
46.Nm fsetpos ,
47.Nm ftell ,
48.Nm ftello ,
49.Nm rewind
50.Nd reposition a stream
51.Sh LIBRARY
52.Lb libc
53.Sh SYNOPSIS
54.Fd #include <stdio.h>
55.Ft int
56.Fn fseek "FILE *stream" "long offset" "int whence"
57.Ft long
58.Fn ftell "FILE *stream"
59.Ft void
60.Fn rewind "FILE *stream"
61.Ft int
62.Fn fgetpos "FILE *stream" "fpos_t *pos"
63.Ft int
64.Fn fsetpos "FILE *stream" "const fpos_t *pos"
65.Fd #include <sys/types.h>
66.Ft int
67.Fn fseeko "FILE *stream" "off_t offset" "int whence"
68.Ft off_t
69.Fn ftello "FILE *stream"
70.Sh DESCRIPTION
71The
72.Fn fseek
73function sets the file position indicator for the stream pointed
74to by
75.Fa stream .
76The new position, measured in bytes, is obtained by adding
77.Fa offset
78bytes to the position specified by
79.Fa whence .
80If
81.Fa whence
82is set to
83.Dv SEEK_SET ,
84.Dv SEEK_CUR ,
85or
86.Dv SEEK_END ,
87the offset is relative to the
88start of the file, the current position indicator, or end-of-file,
89respectively.
90A successful call to the
91.Fn fseek
92function clears the end-of-file indicator for the stream and undoes
93any effects of the
94.Xr ungetc 3
95function on the same stream.
96.Pp
97The
98.Fn ftell
99function
100obtains the current value of the file position indicator for the
101stream pointed to by
102.Fa stream .
103.Pp
104The
105.Fn rewind
106function sets the file position indicator for the stream pointed
107to by
108.Fa stream
109to the beginning of the file.
110It is equivalent to:
111.Pp
112.Dl (void)fseek(stream, 0L, SEEK_SET)
113.Pp
114except that the error indicator for the stream is also cleared
115(see
116.Xr clearerr 3 ) .
117.Pp
118The
119.Fn fseeko
120function is identical to
121.Fn fseek ,
122except it takes an
123.Fa off_t
124argument
125instead of a
126.Fa long .
127Likewise, the
128.Fn ftello
129function is identical to
130.Fn ftell ,
131except it returns an
132.Fa off_t .
133.Pp
134The
135.Fn fgetpos
136and
137.Fn fsetpos
138functions
139are alternate interfaces equivalent to
140.Fn ftell
141and
142.Fn fseek
143(with whence set to
144.Dv SEEK_SET ) ,
145setting and storing the current value of
146the file offset into or from the object referenced by
147.Fa pos .
148On some
149.Pq non- Ns Tn UNIX
150systems an
151.Dq Fa fpos_t
152object may be a complex object
153and these routines may be the only way to portably reposition a text stream.
154.Sh RETURN VALUES
155The
156.Fn rewind
157function
158returns no value.
159Upon successful completion,
160.Fn fgetpos ,
161.Fn fseek ,
162.Fn fseeko ,
163and
164.Fn fsetpos
165return 0,
166and
167.Fn ftell
168and
169.Fn ftello
170return the current offset.
171Otherwise, \-1 is returned and the global variable errno is set to
172indicate the error.
173.Sh ERRORS
174.Bl -tag -width Er
175.It Bq Er EBADF
176The
177.Fa stream
178specified
179is not a seekable stream.
180.It Bq Er EINVAL
181The
182.Fa whence
|
183argument to
184.Fn fseek
185was not
186.Dv SEEK_SET ,
187.Dv SEEK_END ,
188or
189.Dv SEEK_CUR .
| 183argument is invalid.
184The resulting file-position
185indicator would be set to a negative value.
|
190.It Bq Er EOVERFLOW
| 186.It Bq Er EOVERFLOW
|
191For
192.Fn ftell ,
193the resulting file offset would be a value which
194cannot be represented correctly in an object of type long.
| 187The resulting file offset would be a value which
188cannot be represented correctly in an object of type requested.
|
195.El
196.Pp
197The functions
198.Fn fgetpos ,
199.Fn fseek ,
200.Fn fseeko ,
201.Fn fsetpos ,
202.Fn ftell ,
203and
204.Fn ftello
205may also fail and set
206.Va errno
207for any of the errors specified for the routines
208.Xr fflush 3 ,
209.Xr fstat 2 ,
210.Xr lseek 2 ,
211and
212.Xr malloc 3 .
213.Sh SEE ALSO
214.Xr lseek 2
215.Sh STANDARDS
216The
217.Fn fgetpos ,
218.Fn fsetpos ,
219.Fn fseek ,
220.Fn ftell ,
221and
222.Fn rewind
223functions
224conform to
225.St -isoC .
226.Pp
227The
228.Fn fseeko
229and
230.Fn ftello
231functions conform to
232.St -susv2 .
| 189.El
190.Pp
191The functions
192.Fn fgetpos ,
193.Fn fseek ,
194.Fn fseeko ,
195.Fn fsetpos ,
196.Fn ftell ,
197and
198.Fn ftello
199may also fail and set
200.Va errno
201for any of the errors specified for the routines
202.Xr fflush 3 ,
203.Xr fstat 2 ,
204.Xr lseek 2 ,
205and
206.Xr malloc 3 .
207.Sh SEE ALSO
208.Xr lseek 2
209.Sh STANDARDS
210The
211.Fn fgetpos ,
212.Fn fsetpos ,
213.Fn fseek ,
214.Fn ftell ,
215and
216.Fn rewind
217functions
218conform to
219.St -isoC .
220.Pp
221The
222.Fn fseeko
223and
224.Fn ftello
225functions conform to
226.St -susv2 .
|