1.\" $NetBSD: fseek.3,v 1.25 2010/10/22 21:29:31 christos 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 October 22, 2010 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 implementation, the 131.Fn fgetpos 132and 133.Fn fsetpos 134functions 135are alternative interfaces equivalent to 136.Fn ftell , 137.Fn ftello , 138.Fn fseek , 139and 140.Fn fseeko 141(with whence set to 142.Dv SEEK_SET ) , 143setting and storing the current value of 144the file offset into or from the object referenced by 145.Fa pos . 146In others implementations, an 147.Dq Fa fpos_t 148object may be a complex object 149and these routines may be the only way to portably reposition a text stream. 150.Sh RETURN VALUES 151The 152.Fn rewind 153function 154returns no value. 155Upon successful completion, 156.Fn fgetpos , 157.Fn fseek , 158.Fn fseeko , 159and 160.Fn fsetpos 161return 0. 162The functions 163.Fn ftell 164and 165.Fn ftello 166return the current offset. 167Otherwise, 168.Fn fseek , 169.Fn fseeko , 170.Fn ftell , 171and 172.Fn ftello 173return \-1 while 174.Fn fgetpos 175and 176.Fn fsetpos 177return a nonzero value. 178On error all functions the global variable 179.Va errno 180is set to indicate the error. 181Since the 182.Fn rewind 183function does not return an error code, applications need to clear 184.Va errno 185before calling it in order to detect errors. 186.Sh ERRORS 187.Bl -tag -width Er 188.It Bq Er EBADF 189The 190.Fa stream 191specified 192is not a seekable stream. 193.It Bq Er EINVAL 194The 195.Fa whence 196argument to 197.Fn fseek 198was not 199.Dv SEEK_SET , 200.Dv SEEK_END , 201or 202.Dv SEEK_CUR . 203.It Bq Er EOVERFLOW 204For 205.Fn ftell , 206the current file offset cannot be represented correctly in an object of type 207.Fa long . 208.El 209.Pp 210The function 211.Fn fgetpos , 212.Fn fseek , 213.Fn fseeko , 214.Fn fsetpos , 215.Fn ftell , 216.Fn ftello , 217and 218.Fn rewind 219may also fail and set 220.Va errno 221for any of the errors specified for the routines 222.Xr fflush 3 , 223.Xr fstat 2 , 224.Xr lseek 2 , 225and 226.Xr malloc 3 . 227.Sh SEE ALSO 228.Xr lseek 2 229.Sh STANDARDS 230The 231.Fn fgetpos , 232.Fn fsetpos , 233.Fn fseek , 234.Fn ftell , 235and 236.Fn rewind 237functions 238conform to 239.St -ansiC . 240The 241.Fn fseeko 242and 243.Fn ftello 244functions conform to 245.St -xsh5 . 246.Sh BUGS 247The 248.Fn fgetpos 249and 250.Fn fsetpos 251functions don't store/set shift states of the stream in this implementation. 252