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 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)fseek.3     8.1 (Berkeley) 6/4/93
  37 .\" $FreeBSD: src/lib/libc/stdio/fseek.3,v 1.24 2002/12/19 09:40:24 ru Exp $
  38 .\"
  39 .Dd October 12, 2002
  40 .Dt FSEEK 3
  41 .Os
  42 .Sh NAME
  43 .Nm fgetpos ,
  44 .Nm fseek ,
  45 .Nm fseeko ,
  46 .Nm fsetpos ,
  47 .Nm ftell ,
  48 .Nm ftello ,
  49 .Nm rewind
  50 .Nd reposition a stream
  51 .Sh LIBRARY
  52 .Lb libc
  53 .Sh SYNOPSIS
  54 .In stdio.h
  55 .Ft int
  56 .Fn fseek "FILE *stream" "long offset" "int whence"
  57 .Ft long
  58 .Fn ftell "FILE *stream"
  59 .Ft void
  60 .Fn rewind "FILE *stream"
  61 .Ft int
  62 .Fn fgetpos "FILE * restrict stream" "fpos_t * restrict pos"
  63 .Ft int
  64 .Fn fsetpos "FILE *stream" "const fpos_t *pos"
  65 .In sys/types.h
  66 .Ft int
  67 .Fn fseeko "FILE *stream" "off_t offset" "int whence"
  68 .Ft off_t
  69 .Fn ftello "FILE *stream"
  70 .Sh DESCRIPTION
  71 The
  72 .Fn fseek
  73 function sets the file position indicator for the stream pointed
  74 to by
  75 .Fa stream .
  76 The new position, measured in bytes, is obtained by adding
  77 .Fa offset
  78 bytes to the position specified by
  79 .Fa whence .
  80 If
  81 .Fa whence
  82 is set to
  83 .Dv SEEK_SET ,
  84 .Dv SEEK_CUR ,
  85 or
  86 .Dv SEEK_END ,
  87 the offset is relative to the
  88 start of the file, the current position indicator, or end-of-file,
  89 respectively.
  90 A successful call to the
  91 .Fn fseek
  92 function clears the end-of-file indicator for the stream and undoes
  93 any effects of the
  94 .Xr ungetc 3
  95 and
  96 .Xr ungetwc 3
  97 functions on the same stream.
  98 .Pp
  99 The
 100 .Fn ftell
 101 function
 102 obtains the current value of the file position indicator for the
 103 stream pointed to by
 104 .Fa stream .
 105 .Pp
 106 The
 107 .Fn rewind
 108 function sets the file position indicator for the stream pointed
 109 to by
 110 .Fa stream
 111 to the beginning of the file.
 112 It is equivalent to:
 113 .Pp
 114 .Dl (void)fseek(stream, 0L, SEEK_SET)
 115 .Pp
 116 except that the error indicator for the stream is also cleared
 117 (see
 118 .Xr clearerr 3 ) .
 119 .Pp
 120 Since
 121 .Fn rewind
 122 does not return a value,
 123 an application wishing to detect errors should clear
 124 .Va errno ,
 125 then call
 126 .Fn rewind ,
 127 and if
 128 .Va errno
 129 is non-zero, assume an error has occurred.
 130 .Pp
 131 The
 132 .Fn fseeko
 133 function is identical to
 134 .Fn fseek ,
 135 except it takes an
 136 .Fa off_t
 137 argument
 138 instead of a
 139 .Fa long .
 140 Likewise, the
 141 .Fn ftello
 142 function is identical to
 143 .Fn ftell ,
 144 except it returns an
 145 .Fa off_t .
 146 .Pp
 147 The
 148 .Fn fgetpos
 149 and
 150 .Fn fsetpos
 151 functions
 152 are alternate interfaces equivalent to
 153 .Fn ftell
 154 and
 155 .Fn fseek
 156 (with whence set to
 157 .Dv SEEK_SET ) ,
 158 setting and storing the current value of
 159 the file offset into or from the object referenced by
 160 .Fa pos .
 161 On some
 162 .Pq non- Ns Tn UNIX
 163 systems an
 164 .Dq Fa fpos_t
 165 object may be a complex object
 166 and these routines may be the only way to portably reposition a text stream.
 167 .Pp
 168 If the stream is a wide character stream (see
 169 .Xr fwide 3 ) ,
 170 the position specified by the combination of
 171 .Fa offset
 172 and
 173 .Fa whence
 174 must contain the first byte of a multibyte sequence.
 175 .Sh RETURN VALUES
 176 The
 177 .Fn rewind
 178 function
 179 returns no value.
 180 .Pp
 181 .Rv -std fgetpos fseek fseeko fsetpos
 182 .Pp
 183 Upon successful completion,
 184 .Fn ftell
 185 and
 186 .Fn ftello
 187 return the current offset.
 188 Otherwise, \-1 is returned and the global variable
 189 .Va errno
 190 is set to indicate the error.
 191 .Sh ERRORS
 192 .Bl -tag -width Er
 193 .It Bq Er EBADF
 194 The
 195 .Fa stream
 196 argument
 197 is not a seekable stream.
 198 .It Bq Er EINVAL
 199 The
 200 .Fa whence
 201 argument is invalid or
 202 the resulting file-position
 203 indicator would be set to a negative value.
 204 .It Bq Er EOVERFLOW
 205 The resulting file offset would be a value which
 206 cannot be represented correctly in an object of type
 207 .Fa off_t
 208 for
 209 .Fn fseeko
 210 and
 211 .Fn ftello
 212 or
 213 .Fa long
 214 for
 215 .Fn fseek
 216 and
 217 .Fn ftell .
 218 .It Bq Er ESPIPE
 219 The file descriptor underlying stream is associated with a pipe or FIFO
 220 or file-position indicator value is unspecified
 221 (see
 222 .Xr ungetc 3 ) .
 223 .El
 224 .Pp
 225 The functions
 226 .Fn fgetpos ,
 227 .Fn fseek ,
 228 .Fn fseeko ,
 229 .Fn fsetpos ,
 230 .Fn ftell ,
 231 and
 232 .Fn ftello
 233 may also fail and set
 234 .Va errno
 235 for any of the errors specified for the routines
 236 .Xr fflush 3 ,
 237 .Xr fstat 2 ,
 238 .Xr lseek 2 ,
 239 and
 240 .Xr malloc 3 .
 241 .Sh SEE ALSO
 242 .Xr lseek 2 ,
 243 .Xr clearerr 3 ,
 244 .Xr fwide 3 ,
 245 .Xr ungetc 3 ,
 246 .Xr ungetwc 3
 247 .Sh STANDARDS
 248 The
 249 .Fn fgetpos ,
 250 .Fn fsetpos ,
 251 .Fn fseek ,
 252 .Fn ftell ,
 253 and
 254 .Fn rewind
 255 functions
 256 conform to
 257 .St -isoC .
 258 .Pp
 259 The
 260 .Fn fseeko
 261 and
 262 .Fn ftello
 263 functions conform to
 264 .St -p1003.1-2001 .