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. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)fseek.3 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD$ 34.\" 35.Dd April 2, 2022 36.Dt FSEEK 3 37.Os 38.Sh NAME 39.Nm fgetpos , 40.Nm fseek , 41.Nm fseeko , 42.Nm fsetpos , 43.Nm ftell , 44.Nm ftello , 45.Nm rewind 46.Nd reposition a stream 47.Sh LIBRARY 48.Lb libc 49.Sh SYNOPSIS 50.In stdio.h 51.Ft int 52.Fn fseek "FILE *stream" "long offset" "int whence" 53.Ft long 54.Fn ftell "FILE *stream" 55.Ft void 56.Fn rewind "FILE *stream" 57.Ft int 58.Fn fgetpos "FILE * restrict stream" "fpos_t * restrict pos" 59.Ft int 60.Fn fsetpos "FILE *stream" "const fpos_t *pos" 61.In sys/types.h 62.Ft int 63.Fn fseeko "FILE *stream" "off_t offset" "int whence" 64.Ft off_t 65.Fn ftello "FILE *stream" 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 91and 92.Xr ungetwc 3 93functions on the same stream. 94.Pp 95The 96.Fn ftell 97function 98obtains the current value of the file position indicator for the 99stream pointed to by 100.Fa stream . 101.Pp 102The 103.Fn rewind 104function sets the file position indicator for the stream pointed 105to by 106.Fa stream 107to the beginning of the file. 108It is equivalent to: 109.Pp 110.Dl (void)fseek(stream, 0L, SEEK_SET) 111.Pp 112except that the error indicator for the stream is also cleared 113(see 114.Xr clearerr 3 ) . 115.Pp 116Since 117.Fn rewind 118does not return a value, 119an application wishing to detect errors should clear 120.Va errno , 121then call 122.Fn rewind , 123and if 124.Va errno 125is non-zero, assume an error has occurred. 126.Pp 127The 128.Fn fseeko 129function is identical to 130.Fn fseek , 131except it takes an 132.Fa off_t 133argument 134instead of a 135.Fa long . 136Likewise, the 137.Fn ftello 138function is identical to 139.Fn ftell , 140except it returns an 141.Fa off_t . 142.Pp 143The 144.Fn fgetpos 145and 146.Fn fsetpos 147functions 148are alternate interfaces for retrieving and setting the current position in 149the file, similar to 150.Fn ftell 151and 152.Fn fseek , 153except that the current position is stored in an opaque object of 154type 155.Vt fpos_t 156pointed to by 157.Fa pos . 158These functions provide a portable way to seek to offsets larger than 159those that can be represented by a 160.Vt long int . 161They may also store additional state information in the 162.Vt fpos_t 163object to facilitate seeking within files containing multibyte 164characters with state-dependent encodings. 165Although 166.Vt fpos_t 167has traditionally been an integral type, 168applications cannot assume that it is; 169in particular, they must not perform arithmetic on objects 170of this type. 171.Pp 172If the stream is a wide character stream (see 173.Xr fwide 3 ) , 174the position specified by the combination of 175.Fa offset 176and 177.Fa whence 178must contain the first byte of a multibyte sequence. 179.Sh RETURN VALUES 180The 181.Fn rewind 182function 183returns no value. 184.Pp 185.Rv -std fgetpos fseek fseeko fsetpos 186.Pp 187Upon successful completion, 188.Fn ftell 189and 190.Fn ftello 191return the current offset. 192Otherwise, \-1 is returned and the global variable 193.Va errno 194is set to indicate the error. 195.Sh ERRORS 196.Bl -tag -width Er 197.It Bq Er EBADF 198The 199.Fa stream 200argument 201is not a seekable stream. 202.It Bq Er EINVAL 203The 204.Fa whence 205argument is invalid or 206the resulting file-position 207indicator would be set to a negative value. 208.It Bq Er EOVERFLOW 209The resulting file offset would be a value which 210cannot be represented correctly in an object of type 211.Fa off_t 212for 213.Fn fseeko 214and 215.Fn ftello 216or 217.Fa long 218for 219.Fn fseek 220and 221.Fn ftell . 222.It Bq Er ESPIPE 223The file descriptor underlying stream is associated with a pipe or FIFO 224or file-position indicator value is unspecified 225(see 226.Xr ungetc 3 ) . 227.El 228.Pp 229The functions 230.Fn fgetpos , 231.Fn fseek , 232.Fn fseeko , 233.Fn fsetpos , 234.Fn ftell , 235.Fn ftello , 236and 237.Fn rewind 238may also fail and set 239.Va errno 240for any of the errors specified for the routines 241.Xr fflush 3 , 242.Xr fstat 2 , 243.Xr lseek 2 , 244and 245.Xr malloc 3 . 246.Sh SEE ALSO 247.Xr lseek 2 , 248.Xr clearerr 3 , 249.Xr fwide 3 , 250.Xr ungetc 3 , 251.Xr ungetwc 3 252.Sh STANDARDS 253The 254.Fn fgetpos , 255.Fn fsetpos , 256.Fn fseek , 257.Fn ftell , 258and 259.Fn rewind 260functions 261conform to 262.St -isoC . 263.Pp 264The 265.Fn fseeko 266and 267.Fn ftello 268functions conform to 269.St -p1003.1-2001 . 270.Sh HISTORY 271The functions 272.Fn fseek , 273.Fn ftell , 274and 275.Fn rewind 276first appeared in 277.At v7 . 278