1.\" $NetBSD: fseek.3,v 1.24 2003/08/07 16:43:25 agc 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 July 8, 2000 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 fsetpos 159return 0, 160and 161.Fn ftell 162returns the current offset. 163Otherwise, 164.Fn fseek 165and 166.Fn ftell 167return \-1 and 168the others 169return a nonzero value and the global variable 170.Va errno 171is set to indicate the error. 172.Sh ERRORS 173.Bl -tag -width Er 174.It Bq Er EBADF 175The 176.Fa stream 177specified 178is not a seekable stream. 179.It Bq Er EINVAL 180The 181.Fa whence 182argument to 183.Fn fseek 184was not 185.Dv SEEK_SET , 186.Dv SEEK_END , 187or 188.Dv SEEK_CUR . 189.\" .It Bq Er EOVERFLOW 190.\" For 191.\" .Fn ftell , 192.\" the current file offset cannot be represented correctly in an object of type 193.\" .Fa long . 194.\" .Pp 195.\" For 196.\" .Fn fseek , 197.\" the resulting file offset would be a value which cannot be represented 198.\" 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