man3/fseek.3

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