2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "FSEEK" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" fseek
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH PROLOG
|
|
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
|
|
The Linux implementation of this interface may differ (consult
|
|
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
|
|
or the interface may not be implemented on Linux.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
fseek, fseeko \- reposition a file-position indicator in a stream
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fB#include <stdio.h>
|
|
|
|
.br
|
|
|
|
.sp
|
|
|
|
int fseek(FILE *\fP\fIstream\fP\fB, long\fP \fIoffset\fP\fB, int\fP
|
|
|
|
\fIwhence\fP\fB);
|
|
|
|
.br
|
|
|
|
\fP
|
|
|
|
.LP
|
|
|
|
\fBint fseeko(FILE *\fP\fIstream\fP\fB, off_t\fP \fIoffset\fP\fB,
|
|
|
|
int\fP \fIwhence\fP\fB);
|
|
|
|
\fP
|
|
|
|
\fB
|
|
|
|
.br
|
|
|
|
\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fIfseek\fP() function shall set the file-position indicator for
|
|
|
|
the stream pointed to by \fIstream\fP. If a read or write
|
|
|
|
error occurs, the error indicator for the stream shall be set and
|
|
|
|
\fIfseek\fP() fails.
|
|
|
|
.LP
|
|
|
|
The new position, measured in bytes from the beginning of the file,
|
|
|
|
shall be obtained by adding \fIoffset\fP to the position
|
|
|
|
specified by \fIwhence\fP. The specified point is the beginning of
|
|
|
|
the file for SEEK_SET, the current value of the file-position
|
|
|
|
indicator for SEEK_CUR, or end-of-file for SEEK_END.
|
|
|
|
.LP
|
|
|
|
If the stream is to be used with wide-character input/output functions,
|
|
|
|
the application shall ensure that \fIoffset\fP is
|
|
|
|
either 0 or a value returned by an earlier call to \fIftell\fP() on
|
|
|
|
the same stream and
|
|
|
|
\fIwhence\fP is SEEK_SET.
|
|
|
|
.LP
|
|
|
|
A successful call to \fIfseek\fP() shall clear the end-of-file indicator
|
|
|
|
for the stream and undo any effects of \fIungetc\fP() and \fIungetwc\fP()
|
|
|
|
on the same stream.
|
|
|
|
After an \fIfseek\fP() call, the next operation on an update stream
|
|
|
|
may be either input or output.
|
|
|
|
.LP
|
|
|
|
If
|
|
|
|
the most recent operation, other than \fIftell\fP(), on a given stream
|
|
|
|
is \fIfflush\fP(), the file offset in the underlying open file description
|
|
|
|
shall be adjusted to
|
|
|
|
reflect the location specified by \fIfseek\fP().
|
|
|
|
.LP
|
|
|
|
The \fIfseek\fP() function shall allow 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 shall return bytes with the value 0 until data is actually
|
|
|
|
written into the gap.
|
|
|
|
.LP
|
|
|
|
The behavior of \fIfseek\fP() on devices which are incapable of seeking
|
|
|
|
is implementation-defined. The value of the file offset
|
|
|
|
associated with such a device is undefined.
|
|
|
|
.LP
|
|
|
|
If the stream is writable and buffered data had not been written to
|
|
|
|
the underlying file, \fIfseek\fP() shall cause the
|
|
|
|
unwritten data to be written to the file and shall mark the \fIst_ctime\fP
|
|
|
|
and \fIst_mtime\fP fields of the file for update.
|
|
|
|
.LP
|
|
|
|
In a locale with state-dependent encoding, whether \fIfseek\fP() restores
|
|
|
|
the stream's shift state is
|
|
|
|
implementation-defined.
|
|
|
|
.LP
|
|
|
|
The \fIfseeko\fP() function shall be equivalent to the \fIfseek\fP()
|
|
|
|
function except that the \fIoffset\fP argument is of
|
|
|
|
type \fBoff_t\fP.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
.LP
|
2007-11-18 06:52:48 +00:00
|
|
|
The \fIfseek\fP() and \fIfseeko\fP() functions
|
2004-11-03 13:51:07 +00:00
|
|
|
shall return 0 if they succeed.
|
|
|
|
.LP
|
|
|
|
Otherwise, they shall return -1 and set \fIerrno\fP to indicate the
|
|
|
|
error.
|
|
|
|
.SH ERRORS
|
|
|
|
.LP
|
2007-11-18 06:52:48 +00:00
|
|
|
The \fIfseek\fP() and \fIfseeko\fP()
|
|
|
|
\ functions shall fail if, either the \fIstream\fP is unbuffered
|
2004-11-03 13:51:07 +00:00
|
|
|
or the \fIstream\fP's buffer needed to be flushed, and
|
|
|
|
the call to \fIfseek\fP() or \fIfseeko\fP() causes an underlying \fIlseek\fP()
|
|
|
|
or \fIwrite\fP() to be invoked, and:
|
|
|
|
.TP 7
|
|
|
|
.B EAGAIN
|
|
|
|
The O_NONBLOCK flag is set for the file descriptor and the process
|
|
|
|
would be delayed in the write operation.
|
|
|
|
.TP 7
|
|
|
|
.B EBADF
|
|
|
|
The file descriptor underlying the stream file is not open for writing
|
|
|
|
or the stream's buffer needed to be flushed and the file is
|
|
|
|
not open.
|
|
|
|
.TP 7
|
|
|
|
.B EFBIG
|
|
|
|
An
|
|
|
|
attempt was made to write a file that exceeds the maximum file size.
|
|
|
|
.TP 7
|
|
|
|
.B EFBIG
|
|
|
|
An attempt was made to write a file that exceeds the process' file
|
|
|
|
size limit.
|
|
|
|
.TP 7
|
|
|
|
.B EFBIG
|
|
|
|
The file is a regular file and an attempt was made to write at or
|
|
|
|
beyond the offset maximum associated with the corresponding
|
|
|
|
stream.
|
|
|
|
.TP 7
|
|
|
|
.B EINTR
|
|
|
|
The write operation was terminated due to the receipt of a signal,
|
|
|
|
and no data was transferred.
|
|
|
|
.TP 7
|
|
|
|
.B EINVAL
|
|
|
|
The \fIwhence\fP argument is invalid. The resulting file-position
|
|
|
|
indicator would be set to a negative value.
|
|
|
|
.TP 7
|
|
|
|
.B EIO
|
|
|
|
A
|
|
|
|
physical I/O error has occurred, or the process is a member of a background
|
|
|
|
process group attempting to perform a \fIwrite\fP() to its controlling
|
|
|
|
terminal, TOSTOP is set, the process is neither ignoring nor
|
|
|
|
blocking SIGTTOU, and the process group of the process is orphaned.
|
|
|
|
This error may also be returned under implementation-defined
|
|
|
|
conditions.
|
|
|
|
.TP 7
|
|
|
|
.B ENOSPC
|
|
|
|
There was no free space remaining on the device containing the file.
|
|
|
|
.TP 7
|
|
|
|
.B ENXIO
|
|
|
|
A
|
|
|
|
request was made of a nonexistent device, or the request was outside
|
|
|
|
the capabilities of the device.
|
|
|
|
.TP 7
|
|
|
|
.B EOVERFLOW
|
|
|
|
For \fIfseek\fP(), the resulting file offset would be a value which
|
|
|
|
cannot be represented correctly in an object of type
|
|
|
|
\fBlong\fP.
|
|
|
|
.TP 7
|
|
|
|
.B EOVERFLOW
|
|
|
|
For \fIfseeko\fP(), the resulting file offset would be a value which
|
|
|
|
cannot be represented correctly in an object of type
|
|
|
|
\fBoff_t\fP.
|
|
|
|
.TP 7
|
|
|
|
.B EPIPE
|
|
|
|
An
|
|
|
|
attempt was made to write to a pipe or FIFO that is not open for reading
|
|
|
|
by any process; a SIGPIPE signal shall also be sent to the
|
|
|
|
thread.
|
|
|
|
.TP 7
|
|
|
|
.B ESPIPE
|
|
|
|
The file descriptor underlying \fIstream\fP is associated with a pipe
|
|
|
|
or FIFO.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
2007-09-20 17:56:19 +00:00
|
|
|
\fIfopen\fP(), \fIfsetpos\fP(), \fIftell\fP(),
|
|
|
|
\fIgetrlimit\fP(), \fIlseek\fP(), \fIrewind\fP(), \fIulimit\fP(),
|
|
|
|
\fIungetc\fP(), \fIwrite\fP(), the Base Definitions volume of
|
2004-11-03 13:51:07 +00:00
|
|
|
IEEE\ Std\ 1003.1-2001, \fI<stdio.h>\fP
|
|
|
|
.SH COPYRIGHT
|
|
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
|
|
event of any discrepancy between this version and the original IEEE and
|
|
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
|
|
is the referee document. The original Standard can be obtained online at
|
|
|
|
http://www.opengroup.org/unix/online.html .
|