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