1.\" $NetBSD: fseek.3,v 1.27 2012/01/22 19:13:42 wiz 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.\" @(#)fseek.3 8.1 (Berkeley) 6/4/93 35.\" 36.Dd January 21, 2012 37.Dt FSEEK 3 38.Os 39.Sh NAME 40.Nm fgetpos , 41.Nm fseek , 42.Nm fseeko , 43.Nm fsetpos , 44.Nm ftell , 45.Nm ftello , 46.Nm rewind 47.Nd reposition a stream 48.Sh LIBRARY 49.Lb libc 50.Sh SYNOPSIS 51.In stdio.h 52.Ft int 53.Fn fseek "FILE *stream" "long int offset" "int whence" 54.Ft int 55.Fn fseeko "FILE *stream" "off_t offset" "int whence" 56.Ft long int 57.Fn ftell "FILE *stream" 58.Ft off_t 59.Fn ftello "FILE *stream" 60.Ft void 61.Fn rewind "FILE *stream" 62.Ft int 63.Fn fgetpos "FILE * restrict stream" "fpos_t * restrict pos" 64.Ft int 65.Fn fsetpos "FILE * restrict stream" "const fpos_t * restrict pos" 66.Sh DESCRIPTION 67The 68.Fn fseek 69function sets the file position indicator for the stream pointed 70to by 71.Fa stream . 72The new position, measured in bytes, is obtained by adding 73.Fa offset 74bytes to the position specified by 75.Fa whence . 76If 77.Fa whence 78is set to 79.Dv SEEK_SET , 80.Dv SEEK_CUR , 81or 82.Dv SEEK_END , 83the offset is relative to the 84start of the file, the current position indicator, or end-of-file, 85respectively. 86A successful call to the 87.Fn fseek 88function clears the end-of-file indicator for the stream and undoes 89any effects of the 90.Xr ungetc 3 91function on the same stream. 92.Pp 93The 94.Fn fseeko 95function is identical to the 96.Fn fseek 97function except that the 98.Fa offset 99argument is of type 100.Fa off_t . 101.Pp 102The 103.Fn ftell 104function 105obtains the current value of the file position indicator for the 106stream pointed to by 107.Fa stream . 108.Pp 109The 110.Fn ftello 111function is identical to the 112.Fn ftell 113function except that the return value is of type 114.Fa off_t . 115.Pp 116The 117.Fn rewind 118function sets the file position indicator for the stream pointed 119to by 120.Fa stream 121to the beginning of the file. 122It is equivalent to: 123.Pp 124.Dl (void)fseek(stream, 0L, SEEK_SET) 125.Pp 126except that the error indicator for the stream is also cleared 127(see 128.Xr clearerr 3 ) . 129.Pp 130In this implementations, an 131.Dq Fa fpos_t 132object is a complex object that represents both the position and the parse 133state of the stream making these routines are the only way to portably 134reposition a text stream. 135The 136.Ar pos 137argument of 138.Fn fsetpos 139must always be initialized by 140a call to 141.Fn fgetpos . 142.Sh RETURN VALUES 143The 144.Fn rewind 145function 146returns no value. 147Upon successful completion, 148.Fn fgetpos , 149.Fn fseek , 150.Fn fseeko , 151and 152.Fn fsetpos 153return 0. 154The functions 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 while 166.Fn fgetpos 167and 168.Fn fsetpos 169return a nonzero value. 170On error all functions the global variable 171.Va errno 172is set to indicate the error. 173Since the 174.Fn rewind 175function does not return an error code, applications need to clear 176.Va errno 177before calling it in order to detect errors. 178.Sh ERRORS 179.Bl -tag -width Er 180.It Bq Er EBADF 181The 182.Fa stream 183specified 184is not a seekable stream. 185.It Bq Er EINVAL 186The 187.Fa whence 188argument to 189.Fn fseek 190was not 191.Dv SEEK_SET , 192.Dv SEEK_END , 193or 194.Dv SEEK_CUR . 195.It Bq Er EOVERFLOW 196For 197.Fn ftell , 198the current file offset cannot be represented correctly in an object of type 199.Fa long . 200.El 201.Pp 202The function 203.Fn fgetpos , 204.Fn fseek , 205.Fn fseeko , 206.Fn fsetpos , 207.Fn ftell , 208.Fn ftello , 209and 210.Fn rewind 211may also fail and set 212.Va errno 213for any of the errors specified for the routines 214.Xr fflush 3 , 215.Xr fstat 2 , 216.Xr lseek 2 , 217and 218.Xr malloc 3 . 219.Sh SEE ALSO 220.Xr lseek 2 221.Sh STANDARDS 222The 223.Fn fgetpos , 224.Fn fsetpos , 225.Fn fseek , 226.Fn ftell , 227and 228.Fn rewind 229functions 230conform to 231.St -ansiC . 232The 233.Fn fseeko 234and 235.Fn ftello 236functions conform to 237.St -xsh5 . 238.Sh BUGS 239The 240.Fn fgetpos 241and 242.Fn fsetpos 243functions don't store/set shift states of the stream in this implementation. 244