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 19, 2004 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 for retrieving and setting the current position in 153the file, similar to 154.Fn ftell 155and 156.Fn fseek , 157except that the current position is stored in an opaque object of 158type 159.Vt fpos_t 160pointed to by 161.Fa pos . 162These functions provide a portable way to seek to offsets larger than 163those that can be represented by a 164.Vt long int . 165They may also store additional state information in the 166.Vt fpos_t 167object to facilitate seeking within files containing multibyte 168characters with state-dependent encodings. 169Although 170.Vt fpos_t 171has traditionally been an integral type, 172applications cannot assume that it is; 173in particular, they must not perform arithmetic on objects 174of this type. 175.Pp 176If the stream is a wide character stream (see 177.Xr fwide 3 ) , 178the position specified by the combination of 179.Fa offset 180and 181.Fa whence 182must contain the first byte of a multibyte sequence. 183.Sh RETURN VALUES 184The 185.Fn rewind 186function 187returns no value. 188.Pp 189.Rv -std fgetpos fseek fseeko fsetpos 190.Pp 191Upon successful completion, 192.Fn ftell 193and 194.Fn ftello 195return the current offset. 196Otherwise, \-1 is returned and the global variable 197.Va errno 198is set to indicate the error. 199.Sh ERRORS 200.Bl -tag -width Er 201.It Bq Er EBADF 202The 203.Fa stream 204argument 205is not a seekable stream. 206.It Bq Er EINVAL 207The 208.Fa whence 209argument is invalid or 210the resulting file-position 211indicator would be set to a negative value. 212.It Bq Er EOVERFLOW 213The resulting file offset would be a value which 214cannot be represented correctly in an object of type 215.Fa off_t 216for 217.Fn fseeko 218and 219.Fn ftello 220or 221.Fa long 222for 223.Fn fseek 224and 225.Fn ftell . 226.It Bq Er ESPIPE 227The file descriptor underlying stream is associated with a pipe or FIFO 228or file-position indicator value is unspecified 229(see 230.Xr ungetc 3 ) . 231.El 232.Pp 233The functions 234.Fn fgetpos , 235.Fn fseek , 236.Fn fseeko , 237.Fn fsetpos , 238.Fn ftell , 239and 240.Fn ftello 241may also fail and set 242.Va errno 243for any of the errors specified for the routines 244.Xr fflush 3 , 245.Xr fstat 2 , 246.Xr lseek 2 , 247and 248.Xr malloc 3 . 249.Sh SEE ALSO 250.Xr lseek 2 , 251.Xr clearerr 3 , 252.Xr fwide 3 , 253.Xr ungetc 3 , 254.Xr ungetwc 3 255.Sh STANDARDS 256The 257.Fn fgetpos , 258.Fn fsetpos , 259.Fn fseek , 260.Fn ftell , 261and 262.Fn rewind 263functions 264conform to 265.St -isoC . 266.Pp 267The 268.Fn fseeko 269and 270.Fn ftello 271functions conform to 272.St -p1003.1-2001 . 273