1.\" $NetBSD: fseek.3,v 1.12 1999/03/08 10:27:34 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 June 4, 1993 41.Dt FSEEK 3 42.Os 43.Sh NAME 44.Nm fgetpos , 45.Nm fseek , 46.Nm fsetpos , 47.Nm ftell , 48.Nm rewind 49.Nd reposition a stream 50.Sh LIBRARY 51.Lb libc 52.Sh SYNOPSIS 53.Fd #include <stdio.h> 54.Ft int 55.Fn fseek "FILE *stream" "long offset" "int whence" 56.Ft long 57.Fn ftell "FILE *stream" 58.Ft void 59.Fn rewind "FILE *stream" 60.Ft int 61.Fn fgetpos "FILE *stream" "fpos_t *pos" 62.Ft int 63.Fn fsetpos "FILE *stream" "const fpos_t *pos" 64.Sh DESCRIPTION 65The 66.Fn fseek 67function sets the file position indicator for the stream pointed 68to by 69.Fa stream . 70The new position, measured in bytes, is obtained by adding 71.Fa offset 72bytes to the position specified by 73.Fa whence . 74If 75.Fa whence 76is set to 77.Dv SEEK_SET , 78.Dv SEEK_CUR , 79or 80.Dv SEEK_END , 81the offset is relative to the 82start of the file, the current position indicator, or end-of-file, 83respectively. 84A successful call to the 85.Fn fseek 86function clears the end-of-file indicator for the stream and undoes 87any effects of the 88.Xr ungetc 3 89function on the same stream. 90.Pp 91The 92.Fn ftell 93function 94obtains the current value of the file position indicator for the 95stream pointed to by 96.Fa stream . 97.Pp 98The 99.Fn rewind 100function sets the file position indicator for the stream pointed 101to by 102.Fa stream 103to the beginning of the file. 104It is equivalent to: 105.Pp 106.Dl (void)fseek(stream, 0L, SEEK_SET) 107.Pp 108except that the error indicator for the stream is also cleared 109(see 110.Xr clearerr 3 ) . 111.Pp 112The 113.Fn fgetpos 114and 115.Fn fsetpos 116functions 117are alternative interfaces equivalent to 118.Fn ftell 119and 120.Fn fseek 121(with whence set to 122.Dv SEEK_SET 123), setting and storing the current value of 124the file offset into or from the object referenced by 125.Fa pos . 126On systems other than 127.Ux , 128an 129.Dq Fa fpos_t 130object may be a complex object 131and these routines may be the only way to portably reposition a text stream. 132.Sh RETURN VALUES 133The 134.Fn rewind 135function 136returns no value. 137Upon successful completion, 138.Fn fgetpos , 139.Fn fseek , 140.Fn fsetpos 141return 0, 142and 143.Fn ftell 144returns the current offset. 145Otherwise, 146.Fn fseek 147and 148.Fn ftell 149return \-1 and 150the others 151return a nonzero value and the global variable 152.Va errno 153is set to indicate the error. 154.Sh ERRORS 155.Bl -tag -width Er 156.It Bq Er EBADF 157The 158.Fa stream 159specified 160is not a seekable stream. 161.It Bq Er EINVAL 162The 163.Fa whence 164argument to 165.Fn fseek 166was not 167.Dv SEEK_SET , 168.Dv SEEK_END , 169or 170.Dv SEEK_CUR . 171.El 172.Pp 173The function 174.Fn fgetpos , 175.Fn fseek , 176.Fn fsetpos , 177and 178.Fn ftell 179may also fail and set 180.Va errno 181for any of the errors specified for the routines 182.Xr fflush 3 , 183.Xr fstat 2 , 184.Xr lseek 2 , 185and 186.Xr malloc 3 . 187.Sh SEE ALSO 188.Xr lseek 2 189.Sh STANDARDS 190The 191.Fn fgetpos , 192.Fn fsetpos , 193.Fn fseek , 194.Fn ftell , 195and 196.Fn rewind 197functions 198conform to 199.St -ansiC . 200