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