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 .\"
  39 .Dd March 5, 1999
  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 *stream" "fpos_t *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 function on the same stream.
  96 .Pp
  97 The
  98 .Fn ftell
  99 function
 100 obtains the current value of the file position indicator for the
 101 stream pointed to by
 102 .Fa stream .
 103 .Pp
 104 The
 105 .Fn rewind
 106 function sets the file position indicator for the stream pointed
 107 to by
 108 .Fa stream
 109 to the beginning of the file.
 110 It is equivalent to:
 111 .Pp
 112 .Dl (void)fseek(stream, 0L, SEEK_SET)
 113 .Pp
 114 except that the error indicator for the stream is also cleared
 115 (see
 116 .Xr clearerr 3 ) .
 117 .Pp
 118 The
 119 .Fn fseeko
 120 function is identical to
 121 .Fn fseek ,
 122 except it takes an
 123 .Fa off_t
 124 argument
 125 instead of a
 126 .Fa long .
 127 Likewise, the
 128 .Fn ftello
 129 function is identical to
 130 .Fn ftell ,
 131 except it returns an
 132 .Fa off_t .
 133 .Pp
 134 The
 135 .Fn fgetpos
 136 and
 137 .Fn fsetpos
 138 functions
 139 are alternate interfaces equivalent to
 140 .Fn ftell
 141 and
 142 .Fn fseek
 143 (with whence set to
 144 .Dv SEEK_SET ) ,
 145 setting and storing the current value of
 146 the file offset into or from the object referenced by
 147 .Fa pos .
 148 On some
 149 .Pq non- Ns Tn UNIX
 150 systems an
 151 .Dq Fa fpos_t
 152 object may be a complex object
 153 and these routines may be the only way to portably reposition a text stream.
 154 .Sh RETURN VALUES
 155 The
 156 .Fn rewind
 157 function
 158 returns no value.
 159 .Pp
 160 .Rv -std fgetpos fseek fseeko fsetpos
 161 .Pp
 162 Upon successful completion,
 163 .Fn ftell
 164 and
 165 .Fn ftello
 166 return the current offset.
 167 Otherwise, \-1 is returned and the global variable
 168 .Va errno
 169 is set to indicate the error.
 170 .Sh ERRORS
 171 .Bl -tag -width Er
 172 .It Bq Er EBADF
 173 The
 174 .Fa stream
 175 specified
 176 is not a seekable stream.
 177 .It Bq Er EINVAL
 178 The
 179 .Fa whence
 180 argument to
 181 .Fn fseek
 182 was not
 183 .Dv SEEK_SET ,
 184 .Dv SEEK_END ,
 185 or
 186 .Dv SEEK_CUR .
 187 .It Bq Er EOVERFLOW
 188 For
 189 .Fn ftell ,
 190 the resulting file offset would be a value which
 191 cannot be represented correctly in an object of type long.
 192 .El
 193 .Pp
 194 The functions
 195 .Fn fgetpos ,
 196 .Fn fseek ,
 197 .Fn fseeko ,
 198 .Fn fsetpos ,
 199 .Fn ftell ,
 200 and
 201 .Fn ftello
 202 may also fail and set
 203 .Va errno
 204 for any of the errors specified for the routines
 205 .Xr fflush 3 ,
 206 .Xr fstat 2 ,
 207 .Xr lseek 2 ,
 208 and
 209 .Xr malloc 3 .
 210 .Sh SEE ALSO
 211 .Xr lseek 2
 212 .Sh STANDARDS
 213 The
 214 .Fn fgetpos ,
 215 .Fn fsetpos ,
 216 .Fn fseek ,
 217 .Fn ftell ,
 218 and
 219 .Fn rewind
 220 functions
 221 conform to
 222 .St -isoC .
 223 .Pp
 224 The
 225 .Fn fseeko
 226 and
 227 .Fn ftello
 228 functions conform to
 229 .St -susv2 .