man3/fseek.3

   1 '\" t
   2 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to Berkeley by
   6 .\" Chris Torek and the American National Standards Committee X3,
   7 .\" on Information Processing Systems.
   8 .\"
   9 .\" SPDX-License-Identifier: BSD-4-Clause-UC
  10 .\"
  11 .\"     @(#)fseek.3     6.11 (Berkeley) 6/29/91
  12 .\"
  13 .\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu
  14 .\"
  15 .TH fseek 3 (date) "Linux man-pages (unreleased)"
  16 .SH NAME
  17 fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream
  18 .SH LIBRARY
  19 Standard C library
  20 .RI ( libc ", " \-lc )
  21 .SH SYNOPSIS
  22 .nf
  23 .B #include <stdio.h>
  24 .PP
  25 .BI "int fseek(FILE *" stream ", long " offset ", int " whence );
  26 .BI "long ftell(FILE *" stream );
  27 .PP
  28 .BI "void rewind(FILE *" stream );
  29 .PP
  30 .BI "int fgetpos(FILE *restrict " stream ", fpos_t *restrict " pos );
  31 .BI "int fsetpos(FILE *" stream ", const fpos_t *" pos );
  32 .fi
  33 .SH DESCRIPTION
  34 The
  35 .BR fseek ()
  36 function sets the file position indicator for the stream pointed to by
  37 .IR stream .
  38 The new position, measured in bytes, is obtained by adding
  39 .I offset
  40 bytes to the position specified by
  41 .IR whence .
  42 If
  43 .I whence
  44 is set to
  45 .BR SEEK_SET ,
  46 .BR SEEK_CUR ,
  47 or
  48 .BR SEEK_END ,
  49 the offset is relative to the start of the file, the current position
  50 indicator, or end-of-file, respectively.
  51 A successful call to the
  52 .BR fseek ()
  53 function clears the end-of-file indicator for the stream and undoes
  54 any effects of the
  55 .BR ungetc (3)
  56 function on the same stream.
  57 .PP
  58 The
  59 .BR ftell ()
  60 function obtains the current value of the file position indicator for the
  61 stream pointed to by
  62 .IR stream .
  63 .PP
  64 The
  65 .BR rewind ()
  66 function sets the file position indicator for the stream pointed to by
  67 .I stream
  68 to the beginning of the file.
  69 It is equivalent to:
  70 .PP
  71 .RS
  72 (void) fseek(stream, 0L, SEEK_SET)
  73 .RE
  74 .PP
  75 except that the error indicator for the stream is also cleared (see
  76 .BR clearerr (3)).
  77 .PP
  78 The
  79 .BR fgetpos ()
  80 and
  81 .BR fsetpos ()
  82 functions are alternate interfaces equivalent to
  83 .BR ftell ()
  84 and
  85 .BR fseek ()
  86 (with
  87 .I whence
  88 set to
  89 .BR SEEK_SET ),
  90 setting and storing the current value of the file offset into or from the
  91 object referenced by
  92 .IR pos .
  93 On some non-UNIX systems, an
  94 .I fpos_t
  95 object may be a complex object and these routines may be the only way to
  96 portably reposition a text stream.
  97 .PP
  98 If the stream refers to a regular file
  99 and the resulting stream offset is beyond the size of the file,
 100 subsequent writes will extend the file with a hole, up to the offset,
 101 before committing any data.
 102 See
 103 .BR lseek (2)
 104 for details on file seeking semantics.
 105 .SH RETURN VALUE
 106 The
 107 .BR rewind ()
 108 function returns no value.
 109 Upon successful completion,
 110 .BR fgetpos (),
 111 .BR fseek (),
 112 .BR fsetpos ()
 113 return 0,
 114 and
 115 .BR ftell ()
 116 returns the current offset.
 117 Otherwise, \-1 is returned and
 118 .I errno
 119 is set to indicate the error.
 120 .SH ERRORS
 121 .TP
 122 .B EINVAL
 123 The
 124 .I whence
 125 argument to
 126 .BR fseek ()
 127 was not
 128 .BR SEEK_SET ,
 129 .BR SEEK_END ,
 130 or
 131 .BR SEEK_CUR .
 132 Or: the resulting file offset would be negative.
 133 .TP
 134 .B ESPIPE
 135 The file descriptor underlying
 136 .I stream
 137 is not seekable (e.g., it refers to a pipe, FIFO, or socket).
 138 .PP
 139 The functions
 140 .BR fgetpos (),
 141 .BR fseek (),
 142 .BR fsetpos (),
 143 and
 144 .BR ftell ()
 145 may also fail and set
 146 .I errno
 147 for any of the errors specified for the routines
 148 .BR fflush (3),
 149 .BR fstat (2),
 150 .BR lseek (2),
 151 and
 152 .BR malloc (3).
 153 .SH ATTRIBUTES
 154 For an explanation of the terms used in this section, see
 155 .BR attributes (7).
 156 .TS
 157 allbox;
 158 lbx lb lb
 159 l l l.
 160 Interface       Attribute       Value
 161 T{
 162 .na
 163 .nh
 164 .BR fseek (),
 165 .BR ftell (),
 166 .BR rewind (),
 167 .BR fgetpos (),
 168 .BR fsetpos ()
 169 T}      Thread safety   MT-Safe
 170 .TE
 171 .sp 1
 172 .SH STANDARDS
 173 C11, POSIX.1-2008.
 174 .SH HISTORY
 175 POSIX.1-2001, C89.
 176 .SH SEE ALSO
 177 .BR lseek (2),
 178 .BR fseeko (3)