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