summaryrefslogtreecommitdiffstats
path: root/man3/fseek.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/fseek.3')
-rw-r--r--man3/fseek.3178
1 files changed, 178 insertions, 0 deletions
diff --git a/man3/fseek.3 b/man3/fseek.3
new file mode 100644
index 0000000..4b7a9af
--- /dev/null
+++ b/man3/fseek.3
@@ -0,0 +1,178 @@
+'\" t
+.\" Copyright (c) 1990, 1991 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to Berkeley by
+.\" Chris Torek and the American National Standards Committee X3,
+.\" on Information Processing Systems.
+.\"
+.\" SPDX-License-Identifier: BSD-4-Clause-UC
+.\"
+.\" @(#)fseek.3 6.11 (Berkeley) 6/29/91
+.\"
+.\" Converted for Linux, Mon Nov 29 15:22:01 1993, faith@cs.unc.edu
+.\"
+.TH fseek 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+fgetpos, fseek, fsetpos, ftell, rewind \- reposition a stream
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdio.h>
+.PP
+.BI "int fseek(FILE *" stream ", long " offset ", int " whence );
+.BI "long ftell(FILE *" stream );
+.PP
+.BI "void rewind(FILE *" stream );
+.PP
+.BI "int fgetpos(FILE *restrict " stream ", fpos_t *restrict " pos );
+.BI "int fsetpos(FILE *" stream ", const fpos_t *" pos );
+.fi
+.SH DESCRIPTION
+The
+.BR fseek ()
+function sets the file position indicator for the stream pointed to by
+.IR stream .
+The new position, measured in bytes, is obtained by adding
+.I offset
+bytes to the position specified by
+.IR whence .
+If
+.I whence
+is set to
+.BR SEEK_SET ,
+.BR SEEK_CUR ,
+or
+.BR SEEK_END ,
+the offset is relative to the start of the file, the current position
+indicator, or end-of-file, respectively.
+A successful call to the
+.BR fseek ()
+function clears the end-of-file indicator for the stream and undoes
+any effects of the
+.BR ungetc (3)
+function on the same stream.
+.PP
+The
+.BR ftell ()
+function obtains the current value of the file position indicator for the
+stream pointed to by
+.IR stream .
+.PP
+The
+.BR rewind ()
+function sets the file position indicator for the stream pointed to by
+.I stream
+to the beginning of the file.
+It is equivalent to:
+.PP
+.RS
+(void) fseek(stream, 0L, SEEK_SET)
+.RE
+.PP
+except that the error indicator for the stream is also cleared (see
+.BR clearerr (3)).
+.PP
+The
+.BR fgetpos ()
+and
+.BR fsetpos ()
+functions are alternate interfaces equivalent to
+.BR ftell ()
+and
+.BR fseek ()
+(with
+.I whence
+set to
+.BR SEEK_SET ),
+setting and storing the current value of the file offset into or from the
+object referenced by
+.IR pos .
+On some non-UNIX systems, an
+.I fpos_t
+object may be a complex object and these routines may be the only way to
+portably reposition a text stream.
+.PP
+If the stream refers to a regular file
+and the resulting stream offset is beyond the size of the file,
+subsequent writes will extend the file with a hole, up to the offset,
+before committing any data.
+See
+.BR lseek (2)
+for details on file seeking semantics.
+.SH RETURN VALUE
+The
+.BR rewind ()
+function returns no value.
+Upon successful completion,
+.BR fgetpos (),
+.BR fseek (),
+.BR fsetpos ()
+return 0,
+and
+.BR ftell ()
+returns the current offset.
+Otherwise, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+The
+.I whence
+argument to
+.BR fseek ()
+was not
+.BR SEEK_SET ,
+.BR SEEK_END ,
+or
+.BR SEEK_CUR .
+Or: the resulting file offset would be negative.
+.TP
+.B ESPIPE
+The file descriptor underlying
+.I stream
+is not seekable (e.g., it refers to a pipe, FIFO, or socket).
+.PP
+The functions
+.BR fgetpos (),
+.BR fseek (),
+.BR fsetpos (),
+and
+.BR ftell ()
+may also fail and set
+.I errno
+for any of the errors specified for the routines
+.BR fflush (3),
+.BR fstat (2),
+.BR lseek (2),
+and
+.BR malloc (3).
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR fseek (),
+.BR ftell (),
+.BR rewind (),
+.BR fgetpos (),
+.BR fsetpos ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+C11, POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, C89.
+.SH SEE ALSO
+.BR lseek (2),
+.BR fseeko (3)