lib/libc/stdio/fseek.3

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Chris Torek and the American National Standards Committee X3,
   6 .\" on Information Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)fseek.3     8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/stdio/fseek.3,v 1.27 2007/06/18 02:13:04 ache Exp $
  34 .\" $DragonFly: src/lib/libc/stdio/fseek.3,v 1.3 2007/07/30 22:11:33 swildner Exp $
  35 .\"
  36 .Dd March 19, 2004
  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 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 * restrict stream" "fpos_t * restrict pos"
  60 .Ft int
  61 .Fn fsetpos "FILE *stream" "const fpos_t *pos"
  62 .In sys/types.h
  63 .Ft int
  64 .Fn fseeko "FILE *stream" "off_t offset" "int whence"
  65 .Ft off_t
  66 .Fn ftello "FILE *stream"
  67 .Sh DESCRIPTION
  68 The
  69 .Fn fseek
  70 function sets the file position indicator for the stream pointed
  71 to by
  72 .Fa stream .
  73 The new position, measured in bytes, is obtained by adding
  74 .Fa offset
  75 bytes to the position specified by
  76 .Fa whence .
  77 If
  78 .Fa whence
  79 is set to
  80 .Dv SEEK_SET ,
  81 .Dv SEEK_CUR ,
  82 or
  83 .Dv SEEK_END ,
  84 the offset is relative to the
  85 start of the file, the current position indicator, or end-of-file,
  86 respectively.
  87 A successful call to the
  88 .Fn fseek
  89 function clears the end-of-file indicator for the stream and undoes
  90 any effects of the
  91 .Xr ungetc 3
  92 and
  93 .Xr ungetwc 3
  94 functions on the same stream.
  95 .Pp
  96 The
  97 .Fn ftell
  98 function
  99 obtains the current value of the file position indicator for the
 100 stream pointed to by
 101 .Fa stream .
 102 .Pp
 103 The
 104 .Fn rewind
 105 function sets the file position indicator for the stream pointed
 106 to by
 107 .Fa stream
 108 to the beginning of the file.
 109 It is equivalent to:
 110 .Pp
 111 .Dl (void)fseek(stream, 0L, SEEK_SET)
 112 .Pp
 113 except that the error indicator for the stream is also cleared
 114 (see
 115 .Xr clearerr 3 ) .
 116 .Pp
 117 Since
 118 .Fn rewind
 119 does not return a value,
 120 an application wishing to detect errors should clear
 121 .Va errno ,
 122 then call
 123 .Fn rewind ,
 124 and if
 125 .Va errno
 126 is non-zero, assume an error has occurred.
 127 .Pp
 128 The
 129 .Fn fseeko
 130 function is identical to
 131 .Fn fseek ,
 132 except it takes an
 133 .Fa off_t
 134 argument
 135 instead of a
 136 .Fa long .
 137 Likewise, the
 138 .Fn ftello
 139 function is identical to
 140 .Fn ftell ,
 141 except it returns an
 142 .Fa off_t .
 143 .Pp
 144 The
 145 .Fn fgetpos
 146 and
 147 .Fn fsetpos
 148 functions
 149 are alternate interfaces for retrieving and setting the current position in
 150 the file, similar to
 151 .Fn ftell
 152 and
 153 .Fn fseek ,
 154 except that the current position is stored in an opaque object of
 155 type
 156 .Vt fpos_t
 157 pointed to by
 158 .Fa pos .
 159 These functions provide a portable way to seek to offsets larger than
 160 those that can be represented by a
 161 .Vt long int .
 162 They may also store additional state information in the
 163 .Vt fpos_t
 164 object to facilitate seeking within files containing multibyte
 165 characters with state-dependent encodings.
 166 Although
 167 .Vt fpos_t
 168 has traditionally been an integral type,
 169 applications cannot assume that it is;
 170 in particular, they must not perform arithmetic on objects
 171 of this type.
 172 .Pp
 173 If the stream is a wide character stream (see
 174 .Xr fwide 3 ) ,
 175 the position specified by the combination of
 176 .Fa offset
 177 and
 178 .Fa whence
 179 must contain the first byte of a multibyte sequence.
 180 .Sh RETURN VALUES
 181 The
 182 .Fn rewind
 183 function
 184 returns no value.
 185 .Pp
 186 .Rv -std fgetpos fseek fseeko fsetpos
 187 .Pp
 188 Upon successful completion,
 189 .Fn ftell
 190 and
 191 .Fn ftello
 192 return the current offset.
 193 Otherwise, \-1 is returned and the global variable
 194 .Va errno
 195 is set to indicate the error.
 196 .Sh ERRORS
 197 .Bl -tag -width Er
 198 .It Bq Er EBADF
 199 The
 200 .Fa stream
 201 argument
 202 is not a seekable stream.
 203 .It Bq Er EINVAL
 204 The
 205 .Fa whence
 206 argument is invalid or
 207 the resulting file-position
 208 indicator would be set to a negative value.
 209 .It Bq Er EOVERFLOW
 210 The resulting file offset would be a value which
 211 cannot be represented correctly in an object of type
 212 .Fa off_t
 213 for
 214 .Fn fseeko
 215 and
 216 .Fn ftello
 217 or
 218 .Fa long
 219 for
 220 .Fn fseek
 221 and
 222 .Fn ftell .
 223 .It Bq Er ESPIPE
 224 The file descriptor underlying stream is associated with a pipe or FIFO
 225 or file-position indicator value is unspecified
 226 (see
 227 .Xr ungetc 3 ) .
 228 .El
 229 .Pp
 230 The functions
 231 .Fn fgetpos ,
 232 .Fn fseek ,
 233 .Fn fseeko ,
 234 .Fn fsetpos ,
 235 .Fn ftell ,
 236 .Fn ftello ,
 237 and
 238 .Fn rewind
 239 may also fail and set
 240 .Va errno
 241 for any of the errors specified for the routines
 242 .Xr fflush 3 ,
 243 .Xr fstat 2 ,
 244 .Xr lseek 2 ,
 245 and
 246 .Xr malloc 3 .
 247 .Sh SEE ALSO
 248 .Xr lseek 2 ,
 249 .Xr clearerr 3 ,
 250 .Xr fwide 3 ,
 251 .Xr ungetc 3 ,
 252 .Xr ungetwc 3
 253 .Sh STANDARDS
 254 The
 255 .Fn fgetpos ,
 256 .Fn fsetpos ,
 257 .Fn fseek ,
 258 .Fn ftell ,
 259 and
 260 .Fn rewind
 261 functions
 262 conform to
 263 .St -isoC .
 264 .Pp
 265 The
 266 .Fn fseeko
 267 and
 268 .Fn ftello
 269 functions conform to
 270 .St -p1003.1-2001 .