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