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.Dd April 2, 2022 33.Dt FSEEK 3 34.Os 35.Sh NAME 36.Nm fgetpos , 37.Nm fseek , 38.Nm fseeko , 39.Nm fsetpos , 40.Nm ftell , 41.Nm ftello , 42.Nm rewind 43.Nd reposition a stream 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.In stdio.h 48.Ft int 49.Fn fseek "FILE *stream" "long offset" "int whence" 50.Ft long 51.Fn ftell "FILE *stream" 52.Ft void 53.Fn rewind "FILE *stream" 54.Ft int 55.Fn fgetpos "FILE * restrict stream" "fpos_t * restrict pos" 56.Ft int 57.Fn fsetpos "FILE *stream" "const fpos_t *pos" 58.In sys/types.h 59.Ft int 60.Fn fseeko "FILE *stream" "off_t offset" "int whence" 61.Ft off_t 62.Fn ftello "FILE *stream" 63.Sh DESCRIPTION 64The 65.Fn fseek 66function sets the file position indicator for the stream pointed 67to by 68.Fa stream . 69The new position, measured in bytes, is obtained by adding 70.Fa offset 71bytes to the position specified by 72.Fa whence . 73If 74.Fa whence 75is set to 76.Dv SEEK_SET , 77.Dv SEEK_CUR , 78or 79.Dv SEEK_END , 80the offset is relative to the 81start of the file, the current position indicator, or end-of-file, 82respectively. 83A successful call to the 84.Fn fseek 85function clears the end-of-file indicator for the stream and undoes 86any effects of the 87.Xr ungetc 3 88and 89.Xr ungetwc 3 90functions on the same stream. 91.Pp 92The 93.Fn ftell 94function 95obtains the current value of the file position indicator for the 96stream pointed to by 97.Fa stream . 98.Pp 99The 100.Fn rewind 101function sets the file position indicator for the stream pointed 102to by 103.Fa stream 104to the beginning of the file. 105It is equivalent to: 106.Pp 107.Dl (void)fseek(stream, 0L, SEEK_SET) 108.Pp 109except that the error indicator for the stream is also cleared 110(see 111.Xr clearerr 3 ) . 112.Pp 113Since 114.Fn rewind 115does not return a value, 116an application wishing to detect errors should clear 117.Va errno , 118then call 119.Fn rewind , 120and if 121.Va errno 122is non-zero, assume an error has occurred. 123.Pp 124The 125.Fn fseeko 126function is identical to 127.Fn fseek , 128except it takes an 129.Fa off_t 130argument 131instead of a 132.Fa long . 133Likewise, the 134.Fn ftello 135function is identical to 136.Fn ftell , 137except it returns an 138.Fa off_t . 139.Pp 140The 141.Fn fgetpos 142and 143.Fn fsetpos 144functions 145are alternate interfaces for retrieving and setting the current position in 146the file, similar to 147.Fn ftell 148and 149.Fn fseek , 150except that the current position is stored in an opaque object of 151type 152.Vt fpos_t 153pointed to by 154.Fa pos . 155These functions provide a portable way to seek to offsets larger than 156those that can be represented by a 157.Vt long int . 158They may also store additional state information in the 159.Vt fpos_t 160object to facilitate seeking within files containing multibyte 161characters with state-dependent encodings. 162Although 163.Vt fpos_t 164has traditionally been an integral type, 165applications cannot assume that it is; 166in particular, they must not perform arithmetic on objects 167of this type. 168.Pp 169If the stream is a wide character stream (see 170.Xr fwide 3 ) , 171the position specified by the combination of 172.Fa offset 173and 174.Fa whence 175must contain the first byte of a multibyte sequence. 176.Sh RETURN VALUES 177The 178.Fn rewind 179function 180returns no value. 181.Pp 182.Rv -std fgetpos fseek fseeko fsetpos 183.Pp 184Upon successful completion, 185.Fn ftell 186and 187.Fn ftello 188return the current offset. 189Otherwise, \-1 is returned and the global variable 190.Va errno 191is set to indicate the error. 192.Sh ERRORS 193.Bl -tag -width Er 194.It Bq Er EBADF 195The 196.Fa stream 197argument 198is not a seekable stream. 199.It Bq Er EINVAL 200The 201.Fa whence 202argument is invalid or 203the resulting file-position 204indicator would be set to a negative value. 205.It Bq Er EOVERFLOW 206The resulting file offset would be a value which 207cannot be represented correctly in an object of type 208.Fa off_t 209for 210.Fn fseeko 211and 212.Fn ftello 213or 214.Fa long 215for 216.Fn fseek 217and 218.Fn ftell . 219.It Bq Er ESPIPE 220The file descriptor underlying stream is associated with a pipe or FIFO 221or file-position indicator value is unspecified 222(see 223.Xr ungetc 3 ) . 224.El 225.Pp 226The functions 227.Fn fgetpos , 228.Fn fseek , 229.Fn fseeko , 230.Fn fsetpos , 231.Fn ftell , 232.Fn ftello , 233and 234.Fn rewind 235may also fail and set 236.Va errno 237for any of the errors specified for the routines 238.Xr fflush 3 , 239.Xr fstat 2 , 240.Xr lseek 2 , 241and 242.Xr malloc 3 . 243.Sh SEE ALSO 244.Xr lseek 2 , 245.Xr clearerr 3 , 246.Xr fwide 3 , 247.Xr ungetc 3 , 248.Xr ungetwc 3 249.Sh STANDARDS 250The 251.Fn fgetpos , 252.Fn fsetpos , 253.Fn fseek , 254.Fn ftell , 255and 256.Fn rewind 257functions 258conform to 259.St -isoC . 260.Pp 261The 262.Fn fseeko 263and 264.Fn ftello 265functions conform to 266.St -p1003.1-2001 . 267.Sh HISTORY 268The functions 269.Fn fseek , 270.Fn ftell , 271and 272.Fn rewind 273first appeared in 274.At v7 . 275