 |
Index for
Section 3 |
|
 |
Alphabetical
listing for F |
|
 |
Bottom of
page |
|
fseek(3)
NAME
fseek, fseeko, fseek_unlocked, rewind, ftell, ftello, fgetpos, fsetpos -
Reposition the file pointer of a stream
SYNOPSIS
#include <stdio.h>
int fseek(
FILE *stream,
long int offset,
int whence );
int fseeko(
FILE *stream,
off_t offset,
int whence );
int fseek_unlocked(
FILE *stream,
long int offset,
int whence );
void rewind(
FILE *stream );
long int ftell(
FILE *stream );
off_t ftello(
FILE *stream );
int fsetpos(
FILE *stream,
const fpos_t *position );
int fgetpos(
FILE *stream,
fpos_t *position );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
fseek(), fgetpos(), fsetpos(), ftell(), rewind(): XSH5.0, XNS5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
stream
Specifies the I/O stream.
offset
Determines the position of the next operation.
whence
Determines the value for the file pointer associated with the stream
parameter.
position
Specifies the value of the file position indicator.
DESCRIPTION
The fseek() function sets the position of the next input or output
operation on the I/O stream specified by the stream parameter. The position
of the next operation is determined by the offset parameter, which can be
either positive or negative.
The fseek() function sets the file pointer associated with the specified
stream as follows:
· If the whence parameter is SEEK_SET(0), the pointer is set to the
value of the offset parameter.
· If the whence parameter is SEEK_CUR(1), the pointer is set to its
current location plus the value of the offset parameter.
· If the whence parameter is SEEK_END(2), the pointer is set to the size
of the file plus the value of the offset parameter.
The fseek() function fails if attempted on a file that was not opened with
the fopen() function. In particular, the fseek() function cannot be used on
a terminal or on a file opened with the popen() function.
A successful call to the fseek() function clears the End-of-File indicator
for the stream and undoes any effects of the ungetc() function on the same
stream. After a call to the fseek() function, the next operation on an
update stream may be either input or output.
If the stream is writable, and buffered data was not written to the
underlying file, the fseek() function causes the unwritten data to be
written to the file and marks the st_ctime and st_mtime fields of the file
for update.
If the most recent operation (ignoring any ftell() operations) on a given
stream was fflush(), then the fseek() function causes the file offset in
the underlying open file descriptor to be adjusted to reflect the location
specified by the fseek() function.
The fseek() function allows the file-position indicator to be set beyond
the end of existing data in the file. If data is later written at this
point, subsequent reads of data in the gap will return bytes with the value
0 (zero) until data is actually written into the gap.
The rewind() function is equivalent to: (void) fseek (stream, 0L, SEEK_SET)
Except that rewind() also clears the error indicator.
The ftell() function obtains the current value of the file position
indicator for the specified stream.
The fgetpos() and fsetpos() functions are similar to the ftell() and
fseek() functions, respectively. The fgetpos() function stores the current
value of the file position indicator for the stream pointed to by the
stream parameter in the object pointed to by the position parameter. The
fsetpos function sets the file position indicator according to the value of
the position parameter that was returned by a prior call to the fgetpos()
function.
A successful call to the fsetpos() function clears the EOF indicator and
undoes any effects of the ungetc() function.
[Tru64 UNIX] The fseek_unlocked() function is functionally identical to
the fseek() function, except that fseek_unlocked() may be safely used only
within a scope that is protected by the flockfile() and funlockfile()
functions used as a pair. The caller must ensure that the stream is locked
before using these functions.
The fseeko() and ftello() functions behave identically to fseek() and
ftell().
RETURN VALUES
Upon successful completion, the fseek() and fseek_unlocked() functions
return a value of 0 (zero). If the fseek() or fseek_unlocked() function
fails, a value of -1 is returned and errno is set to indicate the error.
The rewind() function does not return a value. You can detect errors by
first clearing errno and then calling the rewindfunction. If errno is then
nonzero, assume an error has occurred.
Upon successful completion, the ftell() function returns the offset of the
current byte relative to the beginning of the file associated with the
named stream. Otherwise, a value of -1 is returned and errno is set to
indicate the error.
Upon successful completion, the fgetpos() and fsetpos() functions return a
value of 0 (zero). If the fgetpos() or fsetpos() function fails, a value of
-1 is returned and errno is set to indicate the error.
ERRORS
The fseek() or fseek_unlocked() function fails if either the stream is
unbuffered or the stream's buffer needed to be flushed and the call to
fseek() or fseek_unlocked() caused an underlying lseek() or write()
function to be invoked. In addition, if any of the following conditions
occurs, the fseek() or fseek_unlocked() function sets errno to the value
that corresponds to the condition.
[EAGAIN]
The O_NONBLOCK option is set for the file descriptor underlying the
stream parameter and the process would be delayed in the write
operation.
[EBADF]
The file descriptor underlying the stream parameter is not a valid file
descriptor open for writing.
[EFBIG]
An attempt was made to write to a file that exceeds the process's file
size limit or the maximum file size. (See the ulimit(3) reference
page.)
The file is a regular file and an attempt was made to write at or
beyond the offset maximum associated with the corresponding stream.
[EINTR]
The write operation was terminated by a signal, and either none, some,
or all the data was transferred. If buffered I/O is being used, it is
recommended that you call the fflush() function before the fseek()
function to guarantee that the buffer characters were written.
[EINVAL]
The whence parameter is an invalid value or the resulting file offset
would be invalid.
[EIO]
A physical I/O error has occurred or the following set of conditions
has occurred: the process is a member of a background process group
attempting to write to its controlling terminal, the TOSTOP signal is
set, the process is neither ignoring nor blocking SIGTTOU, and the
process group of the process is orphaned.
[ENOSPC]
No free space remained on the device containing the file.
[EPIPE]
The file descriptor underlying stream is associated with a pipe or
FIFO.
An attempt was made to write to a pipe or FIFO that is not open for
reading by any process. A SIGPIPE signal will also be sent to the
process.
[ENXIO]
A request was made of a nonexistent device or the request was outside
the capabilities of the device.
The rewind() function fails under the same conditions as the fseek()
function, with the exception of [EINVAL], which does not apply.
If the following conditions occur, the fgetpos(), fsetpos() or ftell()
function sets errno to the value that corresponds to the condition.
[EBADF]
The file descriptor underlying the stream parameter is not a valid file
descriptor.
[EINVAL]
[Tru64 UNIX] The stream parameter does not point to a valid FILE
structure or the position parameter is negative.
[ESPIPE]
An illegal attempt was made to get or set the file position of a pipe
or FIFO.
[XNS5.0] The file descriptor parameter underlying stream is associated
with a socket.
SEE ALSO
Functions: lseek(2), fopen(3)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for F |
|
 |
Top of
page |
|