1.\" $OpenBSD: fseek.3,v 1.12 2011/07/05 15:30:10 jmc 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: July 5 2011 $ 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.Fd #include <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 138.Pq non- Ns Tn UNIX 139systems an 140.Dq Fa fpos_t 141object may be a complex object 142and these routines may be the only way to portably reposition a text stream. 143.Sh RETURN VALUES 144The 145.Fn rewind 146function returns no value. 147Upon successful completion, 148.Fn fgetpos , 149.Fn fseek , 150.Fn fseeko , 151and 152.Fn fsetpos 153return 0 and 154.Fn ftell 155and 156.Fn ftello 157return the current offset. 158Otherwise, 159.Fn fseek , 160.Fn fseeko , 161.Fn ftell , 162and 163.Fn ftello 164return \-1 and 165.Fn fgetpos 166and 167.Fn fsetpos 168return a non-zero value and the global variable 169.Va errno 170is set to indicate the error. 171.Sh ERRORS 172.Bl -tag -width Er 173.It Bq Er EBADF 174The 175.Fa stream 176specified is not a seekable stream. 177.It Bq Er EINVAL 178The 179.Fa whence 180argument to 181.Fn fseek 182was not 183.Dv SEEK_SET , 184.Dv SEEK_END , 185or 186.Dv SEEK_CUR . 187.El 188.Pp 189The functions 190.Fn fgetpos , 191.Fn fseek , 192.Fn fseeko , 193.Fn fsetpos , 194.Fn ftell , 195and 196.Fn ftello 197may also fail and set 198.Va errno 199for any of the errors specified for the routines 200.Xr fflush 3 , 201.Xr fstat 2 , 202.Xr lseek 2 , 203and 204.Xr malloc 3 . 205.Sh SEE ALSO 206.Xr lseek 2 207.Sh STANDARDS 208The 209.Fn fgetpos , 210.Fn fsetpos , 211.Fn fseek , 212.Fn ftell , 213and 214.Fn rewind 215functions conform to 216.St -ansiC 217and 218.St -xpg4 . 219.Pp 220The 221.Fn fseeko 222and 223.Fn ftello 224functions conform to 225.St -xpg4 . 226