fgetpos(3)

1fseek(3)                   Library Functions Manual                   fseek(3)
2
3
4

NAME

6       fgetpos, fseek, fsetpos, ftell, rewind - reposition a stream
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <stdio.h>
13
14       int fseek(FILE *stream, long offset, int whence);
15       long ftell(FILE *stream);
16
17       void rewind(FILE *stream);
18
19       int fgetpos(FILE *restrict stream, fpos_t *restrict pos);
20       int fsetpos(FILE *stream, const fpos_t *pos);
21

DESCRIPTION

23       The  fseek()  function  sets the file position indicator for the stream
24       pointed to by stream.  The new position, measured in bytes, is obtained
25       by  adding offset bytes to the position specified by whence.  If whence
26       is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset  is  relative  to
27       the  start of the file, the current position indicator, or end-of-file,
28       respectively.  A successful call to the  fseek()  function  clears  the
29       end-of-file  indicator  for  the  stream  and undoes any effects of the
30       ungetc(3) function on the same stream.
31
32       The ftell() function obtains the current value of the file position in‐
33       dicator for the stream pointed to by stream.
34
35       The  rewind()  function sets the file position indicator for the stream
36       pointed to by stream to the beginning of the file.   It  is  equivalent
37       to:
38
39              (void) fseek(stream, 0L, SEEK_SET)
40
41       except  that  the  error  indicator for the stream is also cleared (see
42       clearerr(3)).
43
44       The fgetpos() and fsetpos() functions are alternate interfaces  equiva‐
45       lent  to ftell() and fseek() (with whence set to SEEK_SET), setting and
46       storing the current value of the file offset into or  from  the  object
47       referenced by pos.  On some non-UNIX systems, an fpos_t object may be a
48       complex object and these routines may be the only way to portably repo‐
49       sition a text stream.
50
51       If  the stream refers to a regular file and the resulting stream offset
52       is beyond the size of the file, subsequent writes will extend the  file
53       with  a  hole,  up  to  the  offset,  before  committing any data.  See
54       lseek(2) for details on file seeking semantics.
55

RETURN VALUE

57       The rewind() function returns no value.   Upon  successful  completion,
58       fgetpos(), fseek(), fsetpos() return 0, and ftell() returns the current
59       offset.  Otherwise, -1 is returned and errno is set to indicate the er‐
60       ror.
61

ERRORS

63       EINVAL The  whence  argument  to fseek() was not SEEK_SET, SEEK_END, or
64              SEEK_CUR.  Or: the resulting file offset would be negative.
65
66       ESPIPE The file descriptor underlying stream is not seekable (e.g.,  it
67              refers to a pipe, FIFO, or socket).
68
69       The  functions fgetpos(), fseek(), fsetpos(), and ftell() may also fail
70       and set errno  for  any  of  the  errors  specified  for  the  routines
71       fflush(3), fstat(2), lseek(2), and malloc(3).
72

ATTRIBUTES

74       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
75       tributes(7).
76
77       ┌────────────────────────────────────────────┬───────────────┬─────────┐
78       │Interface                                   │ Attribute     │ Value   │
79       ├────────────────────────────────────────────┼───────────────┼─────────┤
80       │fseek(), ftell(), rewind(), fgetpos(),      │ Thread safety │ MT-Safe │
81       │fsetpos()                                   │               │         │
82       └────────────────────────────────────────────┴───────────────┴─────────┘
83

STANDARDS

85       C11, POSIX.1-2008.
86

HISTORY

88       POSIX.1-2001, C89.
89