1.\" $OpenBSD: fseek.3,v 1.11 2007/05/31 19:19:31 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: May 31 2007 $ 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 , 151.Fn fsetpos 152return 0 and 153.Fn ftell 154and 155.Fn ftello 156return the current offset. 157Otherwise, 158.Fn fseek 159and 160.Fn fseeko 161return \-1 and the others return a non-zero value and the global variable 162.Va errno 163is set to indicate the error. 164.Sh ERRORS 165.Bl -tag -width Er 166.It Bq Er EBADF 167The 168.Fa stream 169specified is not a seekable stream. 170.It Bq Er EINVAL 171The 172.Fa whence 173argument to 174.Fn fseek 175was not 176.Dv SEEK_SET , 177.Dv SEEK_END , 178or 179.Dv SEEK_CUR . 180.El 181.Pp 182The functions 183.Fn fgetpos , 184.Fn fseek , 185.Fn fseeko , 186.Fn fsetpos , 187.Fn ftell , 188and 189.Fn ftello 190may also fail and set 191.Va errno 192for any of the errors specified for the routines 193.Xr fflush 3 , 194.Xr fstat 2 , 195.Xr lseek 2 , 196and 197.Xr malloc 3 . 198.Sh SEE ALSO 199.Xr lseek 2 200.Sh STANDARDS 201The 202.Fn fgetpos , 203.Fn fsetpos , 204.Fn fseek , 205.Fn ftell , 206and 207.Fn rewind 208functions conform to 209.St -ansiC 210and 211.St -xpg4 . 212.Pp 213The 214.Fn fseeko 215and 216.Fn ftello 217functions conform to 218.St -xpg4 . 219