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$ 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 is invalid. 184The resulting file-position 185indicator would be set to a negative value. 186.It Bq Er EOVERFLOW 187The resulting file offset would be a value which 188cannot be represented correctly in an object of type off_t 189for 190.Fn fseeko 191or long for 192.Fn fseek . 193.El 194.Pp 195The functions 196.Fn fgetpos , 197.Fn fseek , 198.Fn fseeko , 199.Fn fsetpos , 200.Fn ftell , 201and 202.Fn ftello 203may also fail and set 204.Va errno 205for any of the errors specified for the routines 206.Xr fflush 3 , 207.Xr fstat 2 , 208.Xr lseek 2 , 209and 210.Xr malloc 3 . 211.Sh SEE ALSO 212.Xr lseek 2 213.Sh STANDARDS 214The 215.Fn fgetpos , 216.Fn fsetpos , 217.Fn fseek , 218.Fn ftell , 219and 220.Fn rewind 221functions 222conform to 223.St -isoC . 224.Pp 225The 226.Fn fseeko 227and 228.Fn ftello 229functions conform to 230.St -susv2 . 231