1.\" $OpenBSD: fseek.3,v 1.18 2016/03/26 22:32:29 tb Exp $ 2.\" 3.\" Copyright (c) 1990, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Chris Torek and the American National Standards Committee X3, 8.\" on Information Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.Dd $Mdocdate: March 26 2016 $ 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 SYNOPSIS 47.In stdio.h 48.Ft int 49.Fn fgetpos "FILE *stream" "fpos_t *pos" 50.Ft int 51.Fn fseek "FILE *stream" "long offset" "int whence" 52.Ft int 53.Fn fseeko "FILE *stream" "off_t offset" "int whence" 54.Ft int 55.Fn fsetpos "FILE *stream" "const fpos_t *pos" 56.Ft long 57.Fn ftell "FILE *stream" 58.Ft off_t 59.Fn ftello "FILE *stream" 60.Ft void 61.Fn rewind "FILE *stream" 62.Sh DESCRIPTION 63The 64.Fn fseek 65function sets the file position indicator for the stream pointed to by 66.Fa stream . 67The new position, measured in bytes, is obtained by adding 68.Fa offset 69bytes to the position specified by 70.Fa whence . 71If 72.Fa whence 73is set to 74.Dv SEEK_SET , 75.Dv SEEK_CUR , 76or 77.Dv SEEK_END , 78the offset is relative to the 79start of the file, the current position indicator, or end-of-file, 80respectively. 81A successful call to the 82.Fn fseek 83function clears the end-of-file indicator for the stream and undoes 84any effects of the 85.Xr ungetc 3 86function on the same stream. 87.Pp 88The 89.Fn fseeko 90function is identical to 91.Fn fseek 92except that it takes an 93.Li off_t 94as its 95.Fa offset . 96.Pp 97The 98.Fn ftell 99function obtains the current value of the file position indicator for the 100stream pointed to by 101.Fa stream . 102.Pp 103The 104.Fn ftello 105function is identical to 106.Fn ftell 107except that its return value is of type 108.Li off_t . 109.Pp 110The 111.Fn rewind 112function sets the file position indicator for the stream pointed 113to by 114.Fa stream 115to the beginning of the file. 116It is equivalent to: 117.Pp 118.Dl (void)fseek(stream, 0L, SEEK_SET) 119.Pp 120except that the error indicator for the stream is also cleared 121(see 122.Xr clearerr 3 ) . 123.Pp 124The 125.Fn fgetpos 126and 127.Fn fsetpos 128functions are alternate interfaces equivalent to 129.Fn ftell 130and 131.Fn fseek 132(with whence set to 133.Dv SEEK_SET ) , 134setting and storing the current value of 135the file offset into or from the object referenced by 136.Fa pos . 137On some systems an 138.Dq Fa fpos_t 139object may be a complex object 140and these routines may be the only way to portably reposition a text stream. 141.Sh RETURN VALUES 142The 143.Fn rewind 144function returns no value. 145Prefer 146.Fn fseek , 147which is just as portable, and does not hide errors. 148Upon successful completion, 149.Fn fgetpos , 150.Fn fseek , 151.Fn fseeko , 152and 153.Fn fsetpos 154return 0 and 155.Fn ftell 156and 157.Fn ftello 158return the current offset. 159Otherwise, 160.Fn fseek , 161.Fn fseeko , 162.Fn ftell , 163and 164.Fn ftello 165return \-1 and 166.Fn fgetpos 167and 168.Fn fsetpos 169return a non-zero value and the global variable 170.Va errno 171is set to indicate the error. 172.Sh ERRORS 173The 174.Fn fgetpos , 175.Fn fseek , 176.Fn fseeko , 177.Fn fsetpos , 178.Fn ftell , 179.Fn ftello , 180and 181.Fn rewind 182functions will fail if: 183.Bl -tag -width Er 184.It Bq Er EBADF 185The 186.Fa stream 187specified is not a seekable stream. 188.El 189.Pp 190Additionally, the 191.Fn fseek 192and 193.Fn fseeko 194functions will fail if: 195.Bl -tag -width Er 196.It Bq Er EINVAL 197The 198.Fa whence 199argument was not 200.Dv SEEK_SET , 201.Dv SEEK_END , 202or 203.Dv SEEK_CUR . 204.El 205.Pp 206Additionally, the 207.Fn ftell 208function will fail if: 209.Bl -tag -width Er 210.It Bq Er EOVERFLOW 211The value of the file position indicator is too large to be represented by a 212.Vt long . 213.El 214.Pp 215Finally, the functions 216.Fn fgetpos , 217.Fn fseek , 218.Fn fseeko , 219.Fn fsetpos , 220.Fn ftell , 221and 222.Fn ftello 223may also fail and set 224.Va errno 225for any of the errors specified for the routines 226.Xr fflush 3 , 227.Xr fstat 2 , 228.Xr lseek 2 , 229and 230.Xr malloc 3 . 231.Sh SEE ALSO 232.Xr lseek 2 233.Sh STANDARDS 234The 235.Fn fgetpos , 236.Fn fsetpos , 237.Fn fseek , 238.Fn ftell , 239and 240.Fn rewind 241functions conform to 242.St -ansiC 243and 244.St -xpg4 . 245.Pp 246The 247.Fn fseeko 248and 249.Fn ftello 250functions conform to 251.St -xpg4 . 252.Sh HISTORY 253The functions 254.Fn fseek , 255.Fn ftell , 256and 257.Fn rewind 258first appeared in 259.At v7 . 260