stdio/FreeBSD/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 .\"
  35 .Dd March 19, 2004
  36 .Dt FSEEK 3
  37 .Os
  38 .Sh NAME
  39 .Nm fgetpos ,
  40 .Nm fseek ,
  41 .Nm fseeko ,
  42 .Nm fsetpos ,
  43 .Nm ftell ,
  44 .Nm ftello ,
  45 .Nm rewind
  46 .Nd reposition a stream
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In stdio.h
  51 .Ft int
  52 .Fo fgetpos
  53 .Fa "FILE *restrict stream"
  54 .Fa "fpos_t *restrict pos"
  55 .Fc
  56 .Ft int
  57 .Fo fseek
  58 .Fa "FILE *stream"
  59 .Fa "long offset"
  60 .Fa "int whence"
  61 .Fc
  62 .Ft int
  63 .Fo fseeko
  64 .Fa "FILE *stream"
  65 .Fa "off_t offset"
  66 .Fa "int whence"
  67 .Fc
  68 .Ft int
  69 .Fo fsetpos
  70 .Fa "FILE *stream"
  71 .Fa "const fpos_t *pos"
  72 .Fc
  73 .Ft long
  74 .Fo ftell
  75 .Fa "FILE *stream"
  76 .Fc
  77 .Ft off_t
  78 .Fo ftello
  79 .Fa "FILE *stream"
  80 .Fc
  81 .Ft void
  82 .Fo rewind
  83 .Fa "FILE *stream"
  84 .Fc
  85 .Sh DESCRIPTION
  86 The
  87 .Fn fseek
  88 function sets the file position indicator for the stream pointed
  89 to by
  90 .Fa stream .
  91 The new position, measured in bytes, is obtained by adding
  92 .Fa offset
  93 bytes to the position specified by
  94 .Fa whence .
  95 If
  96 .Fa whence
  97 is set to
  98 .Dv SEEK_SET ,
  99 .Dv SEEK_CUR ,
 100 or
 101 .Dv SEEK_END ,
 102 the offset is relative to the
 103 start of the file, the current position indicator, or end-of-file,
 104 respectively.
 105 A successful call to the
 106 .Fn fseek
 107 function clears the end-of-file indicator for the stream and undoes
 108 any effects of the
 109 .Xr ungetc 3
 110 and
 111 .Xr ungetwc 3
 112 functions on the same stream.
 113 .Pp
 114 The
 115 .Fn ftell
 116 function
 117 obtains the current value of the file position indicator for the
 118 stream pointed to by
 119 .Fa stream .
 120 .Pp
 121 The
 122 .Fn rewind
 123 function sets the file position indicator for the stream pointed
 124 to by
 125 .Fa stream
 126 to the beginning of the file.
 127 It is equivalent to:
 128 .Pp
 129 .Dl (void)fseek(stream, 0L, SEEK_SET)
 130 .Pp
 131 except that the error indicator for the stream is also cleared
 132 (see
 133 .Xr clearerr 3 ) .
 134 .Pp
 135 Since
 136 .Fn rewind
 137 does not return a value,
 138 an application wishing to detect errors should clear
 139 .Va errno ,
 140 then call
 141 .Fn rewind ,
 142 and if
 143 .Va errno
 144 is non-zero, assume an error has occurred.
 145 .Pp
 146 The
 147 .Fn fseeko
 148 function is identical to
 149 .Fn fseek ,
 150 except it takes an
 151 .Fa off_t
 152 argument
 153 instead of a
 154 .Fa long .
 155 Likewise, the
 156 .Fn ftello
 157 function is identical to
 158 .Fn ftell ,
 159 except it returns an
 160 .Fa off_t .
 161 .Pp
 162 The
 163 .Fn fgetpos
 164 and
 165 .Fn fsetpos
 166 functions
 167 are alternate interfaces for retrieving and setting the current position in
 168 the file, similar to
 169 .Fn ftell
 170 and
 171 .Fn fseek ,
 172 except that the current position is stored in an opaque object of
 173 type
 174 .Vt fpos_t
 175 pointed to by
 176 .Fa pos .
 177 These functions provide a portable way to seek to offsets larger than
 178 those that can be represented by a
 179 .Vt long int .
 180 They may also store additional state information in the
 181 .Vt fpos_t
 182 object to facilitate seeking within files containing multibyte
 183 characters with state-dependent encodings.
 184 Although
 185 .Vt fpos_t
 186 has traditionally been an integral type,
 187 applications cannot assume that it is;
 188 in particular, they must not perform arithmetic on objects
 189 of this type.
 190 .Pp
 191 If the stream is a wide character stream (see
 192 .Xr fwide 3 ) ,
 193 the position specified by the combination of
 194 .Fa offset
 195 and
 196 .Fa whence
 197 must contain the first byte of a multibyte sequence.
 198 .Sh RETURN VALUES
 199 The
 200 .Fn rewind
 201 function
 202 returns no value.
 203 .Pp
 204 .Rv -std fgetpos fseek fseeko fsetpos
 205 .Pp
 206 Upon successful completion,
 207 .Fn ftell
 208 and
 209 .Fn ftello
 210 return the current offset.
 211 Otherwise, \-1 is returned and the global variable
 212 .Va errno
 213 is set to indicate the error.
 214 .Sh ERRORS
 215 .Bl -tag -width Er
 216 .It Bq Er EBADF
 217 The
 218 .Fa stream
 219 argument
 220 is not a seekable stream.
 221 .It Bq Er EINVAL
 222 The
 223 .Fa whence
 224 argument is invalid or
 225 the resulting file-position
 226 indicator would be set to a negative value.
 227 .It Bq Er EOVERFLOW
 228 The resulting file offset would be a value which
 229 cannot be represented correctly in an object of type
 230 .Fa off_t
 231 for
 232 .Fn fseeko
 233 and
 234 .Fn ftello
 235 or
 236 .Fa long
 237 for
 238 .Fn fseek
 239 and
 240 .Fn ftell .
 241 .It Bq Er ESPIPE
 242 The file descriptor underlying stream is associated with a pipe or FIFO
 243 or file-position indicator value is unspecified
 244 (see
 245 .Xr ungetc 3 ) .
 246 .El
 247 .Pp
 248 The functions
 249 .Fn fgetpos ,
 250 .Fn fseek ,
 251 .Fn fseeko ,
 252 .Fn fsetpos ,
 253 .Fn ftell ,
 254 .Fn ftello ,
 255 and
 256 .Fn rewind
 257 may also fail and set
 258 .Va errno
 259 for any of the errors specified for the routines
 260 .Xr fflush 3 ,
 261 .Xr fstat 2 ,
 262 .Xr lseek 2 ,
 263 and
 264 .Xr malloc 3 .
 265 .Sh LEGACY SYNOPSIS
 266 .Fd #include <stdio.h>
 267 .Fd #include <sys/types.h>
 268 .Pp
 269 .Ft int
 270 .br
 271 .Fo fseeko
 272 .Fa "FILE *stream"
 273 .Fa "off_t offset"
 274 .Fa "int whence"
 275 .Fc ;
 276 .Pp
 277 The include file
 278 .In sys/types.h
 279 supplies the definition for
 280 .Vt off_t .
 281 .Sh SEE ALSO
 282 .Xr lseek 2 ,
 283 .Xr clearerr 3 ,
 284 .Xr fwide 3 ,
 285 .Xr ungetc 3 ,
 286 .Xr ungetwc 3 ,
 287 .Xr compat 5
 288 .Sh STANDARDS
 289 The
 290 .Fn fgetpos ,
 291 .Fn fsetpos ,
 292 .Fn fseek ,
 293 .Fn ftell ,
 294 and
 295 .Fn rewind
 296 functions
 297 conform to
 298 .St -isoC .
 299 .Pp
 300 The
 301 .Fn fseeko
 302 and
 303 .Fn ftello
 304 functions conform to
 305 .St -p1003.1-2001 .