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 October 12, 2002 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.In 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 * restrict stream" "fpos_t * restrict pos" 63.Ft int 64.Fn fsetpos "FILE *stream" "const fpos_t *pos" 65.In 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 95and 96.Xr ungetwc 3 97functions on the same stream. 98.Pp 99The 100.Fn ftell 101function 102obtains the current value of the file position indicator for the 103stream pointed to by 104.Fa stream . 105.Pp 106The 107.Fn rewind 108function sets the file position indicator for the stream pointed 109to by 110.Fa stream 111to the beginning of the file. 112It is equivalent to: 113.Pp 114.Dl (void)fseek(stream, 0L, SEEK_SET) 115.Pp 116except that the error indicator for the stream is also cleared 117(see 118.Xr clearerr 3 ) . 119.Pp 120Since 121.Fn rewind 122does not return a value, 123an application wishing to detect errors should clear 124.Va errno , 125then call 126.Fn rewind , 127and if 128.Va errno 129is non-zero, assume an error has occurred. 130.Pp 131The 132.Fn fseeko 133function is identical to 134.Fn fseek , 135except it takes an 136.Fa off_t 137argument 138instead of a 139.Fa long . 140Likewise, the 141.Fn ftello 142function is identical to 143.Fn ftell , 144except it returns an 145.Fa off_t . 146.Pp 147The 148.Fn fgetpos 149and 150.Fn fsetpos 151functions 152are alternate interfaces equivalent to 153.Fn ftell 154and 155.Fn fseek 156(with whence set to 157.Dv SEEK_SET ) , 158setting and storing the current value of 159the file offset into or from the object referenced by 160.Fa pos . 161On some 162.Pq non- Ns Tn UNIX 163systems an 164.Dq Fa fpos_t 165object may be a complex object 166and these routines may be the only way to portably reposition a text stream. 167.Pp 168If the stream is a wide character stream (see 169.Xr fwide 3 Ns No ), 170the position specified by the combination of 171.Fa offset 172and 173.Fa whence 174must contain the first byte of a multibyte sequence. 175.Sh RETURN VALUES 176The 177.Fn rewind 178function 179returns no value. 180.Pp 181.Rv -std fgetpos fseek fseeko fsetpos 182.Pp 183Upon successful completion, 184.Fn ftell 185and 186.Fn ftello 187return the current offset. 188Otherwise, \-1 is returned and the global variable 189.Va errno 190is set to indicate the error. 191.Sh ERRORS 192.Bl -tag -width Er 193.It Bq Er EBADF 194The 195.Fa stream 196specified 197is not a seekable stream. 198.It Bq Er EINVAL 199The 200.Fa whence 201argument is invalid or 202the resulting file-position 203indicator would be set to a negative value. 204.It Bq Er EOVERFLOW 205The resulting file offset would be a value which 206cannot be represented correctly in an object of type 207.Fa off_t 208for 209.Fn fseeko 210and 211.Fn ftello 212or 213.Fa long 214for 215.Fn fseek 216and 217.Fn ftell . 218.It Bq Er ESPIPE 219The file descriptor underlying stream is associated with a pipe or FIFO 220or file-position indicator value is unspecified 221(see 222.Xr ungetc 3 ) . 223.El 224.Pp 225The functions 226.Fn fgetpos , 227.Fn fseek , 228.Fn fseeko , 229.Fn fsetpos , 230.Fn ftell , 231and 232.Fn ftello 233may also fail and set 234.Va errno 235for any of the errors specified for the routines 236.Xr fflush 3 , 237.Xr fstat 2 , 238.Xr lseek 2 , 239and 240.Xr malloc 3 . 241.Sh SEE ALSO 242.Xr lseek 2 , 243.Xr clearerr 3 , 244.Xr fwide 3 , 245.Xr ungetc 3 , 246.Xr ungetwc 3 247.Sh STANDARDS 248The 249.Fn fgetpos , 250.Fn fsetpos , 251.Fn fseek , 252.Fn ftell , 253and 254.Fn rewind 255functions 256conform to 257.St -isoC . 258.Pp 259The 260.Fn fseeko 261and 262.Fn ftello 263functions conform to 264.St -p1003.1-2001 . 265