1.\" $NetBSD: fseek.3,v 1.17 2000/12/29 15:22:50 kleink 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. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.\" @(#)fseek.3 8.1 (Berkeley) 6/4/93 39.\" 40.Dd July 8, 2000 41.Dt FSEEK 3 42.Os 43.Sh NAME 44.Nm fgetpos , 45.Nm fseek , 46.Nm fseeko , 47.Nm fsetpos , 48.Nm ftell , 49.Nm ftello , 50.Nm rewind 51.Nd reposition a stream 52.Sh LIBRARY 53.Lb libc 54.Sh SYNOPSIS 55.Fd #include <stdio.h> 56.Ft int 57.Fn fseek "FILE *stream" "long int offset" "int whence" 58.Ft int 59.Fn fseeko "FILE *stream" "off_t offset" "int whence" 60.Ft long int 61.Fn ftell "FILE *stream" 62.Ft off_t 63.Fn ftello "FILE *stream" 64.Ft void 65.Fn rewind "FILE *stream" 66.Ft int 67.Fn fgetpos "FILE * restrict stream" "fpos_t * restrict pos" 68.Ft int 69.Fn fsetpos "FILE * restrict stream" "const fpos_t * restrict pos" 70.Sh DESCRIPTION 71The 72.Fn fseek 73function sets the file position indicator for the stream pointed 74to by 75.Fa stream . 76The new position, measured in bytes, is obtained by adding 77.Fa offset 78bytes to the position specified by 79.Fa whence . 80If 81.Fa whence 82is set to 83.Dv SEEK_SET , 84.Dv SEEK_CUR , 85or 86.Dv SEEK_END , 87the offset is relative to the 88start of the file, the current position indicator, or end-of-file, 89respectively. 90A successful call to the 91.Fn fseek 92function clears the end-of-file indicator for the stream and undoes 93any effects of the 94.Xr ungetc 3 95function on the same stream. 96.Pp 97The 98.Fn fseeko 99function is identical to the 100.Fn fseek 101function except that the 102.Fa offset 103argument is of type 104.Fa off_t . 105.Pp 106The 107.Fn ftell 108function 109obtains the current value of the file position indicator for the 110stream pointed to by 111.Fa stream . 112.Pp 113The 114.Fn ftello 115function is identical to the 116.Fn ftell 117function except that the return value is of type 118.Fa off_t . 119.Pp 120The 121.Fn rewind 122function sets the file position indicator for the stream pointed 123to by 124.Fa stream 125to the beginning of the file. 126It is equivalent to: 127.Pp 128.Dl (void)fseek(stream, 0L, SEEK_SET) 129.Pp 130except that the error indicator for the stream is also cleared 131(see 132.Xr clearerr 3 ) . 133.Pp 134The 135.Fn fgetpos 136and 137.Fn fsetpos 138functions 139are alternative interfaces equivalent to 140.Fn ftell , 141.Fn ftello , 142.Fn fseek 143and 144.Fn fseeko 145(with whence set to 146.Dv SEEK_SET 147), setting and storing the current value of 148the file offset into or from the object referenced by 149.Fa pos . 150On systems other than 151.Ux , 152an 153.Dq Fa fpos_t 154object may be a complex object 155and these routines may be the only way to portably reposition a text stream. 156.Sh RETURN VALUES 157The 158.Fn rewind 159function 160returns no value. 161Upon successful completion, 162.Fn fgetpos , 163.Fn fseek , 164.Fn fsetpos 165return 0, 166and 167.Fn ftell 168returns the current offset. 169Otherwise, 170.Fn fseek 171and 172.Fn ftell 173return \-1 and 174the others 175return a nonzero value and the global variable 176.Va errno 177is set to indicate the error. 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 196.\" For 197.\" .Fn ftell , 198.\" the current file offset cannot be represented correctly in an object of type 199.\" .Fa long . 200.\" .Pp 201.\" For 202.\" .Fn fseek , 203.\" the resulting file offset would be a value which cannot be represented 204.\" correctly in an object of type 205.\" .Fa long. 206.El 207.Pp 208The function 209.Fn fgetpos , 210.Fn fseek , 211.Fn fseeko , 212.Fn fsetpos , 213.Fn ftell , 214.Fn ftello , 215and 216.Fn rewind 217may also fail and set 218.Va errno 219for any of the errors specified for the routines 220.Xr fflush 3 , 221.Xr fstat 2 , 222.Xr lseek 2 , 223and 224.Xr malloc 3 . 225.Sh SEE ALSO 226.Xr lseek 2 227.Sh STANDARDS 228The 229.Fn fgetpos , 230.Fn fsetpos , 231.Fn fseek , 232.Fn ftell , 233and 234.Fn rewind 235functions 236conform to 237.St -ansiC . 238The 239.Fn fseeko 240and 241.Fn ftello 242functions conform to 243.St -xsh5 . 244