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