Unison/NANO: fseek

NAME

fseek, rewind, ftell - reposition a file pointer in a stream

SYNOPSIS

#include <stdio.h>

int fseek( FILE *stream , long offset , int ptrname );
void rewind( FILE *stream );
long ftell( FILE *stream );

DESCRIPTION

fseek() sets the position of the next input or output operation on the stream. The new position is at the signed distance offset bytes from the beginning, from the current position, or from the end of the file, according to a ptrname value of SEEK_SET, SEEK_CUR, or SEEK_END (defined in <stdio.h>) as follows:

SEEK_SET: set position equal to offset bytes.
SEEK_CUR: set position to current location plus offset.
SEEK_END: set position to EOF plus offset.

fseek() allows the file position indicator to be set beyond the end of the existing data in the file. If data is later written at this point, subsequent reads of data in the gap will return zero until data is actually written into the gap. fseek() , , by itself, does not extend the size of the file.

rewind(stream) is equivalent to: (void)fseek(stream, 0L, SEEK_SET); except that rewind() also clears the error indicator on stream.

fseek() and rewind() clear the EOF indicator and undo any effects of ungetc() on stream. After fseek() or rewind() , , the next operation on a file opened for update may be either input or output.

If stream is writable and buffered data has not been written to the underlying file, fseek() and rewind() cause the unwritten data to be written to the file.

ftell() returns the offset of the current byte relative to the beginning of the file associated with the named stream .

RETURN VALUES

fseek() returns -1 for improper seeks, otherwise zero. An improper seek can be, for example, an fseek() done on a file that has not been opened via fopen(). After a stream is closed, no further operations are defined on that stream.

ERRORS

These functions are members of Unison's STDIO implementation. The STDIO implementation rests on top of IOLIB and inherits IOLIB's dependency on each specific server to report an appropriate error code for its usage.

For an exact list of error codes returned by a particular server, refer to that server's documentation in the Unison Programmer's Guide for each specific platform.

Servers may implement these errors codes in response to this function.

For fseek() and rewind():

[EAGAIN]: The O_NONBLOCK flag is set for the file descriptor and the thread would be delayed in the write operation.
[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.
[EFBIG]: An attempt was made to write a file that exceeds the maximum file size.
[EINVAL]: The whence argument is invalid. The resulting file-position indicator would be set to a negative value.
[EIO]: A physical I/O error has occurred, or the process is a member of a background process group attempting to perform a write() 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.
[ENOSPC]: There was no free space remaining on the device containing the file.
[ENXIO]: A request was made of a nonexistent device, or the request was outside the capabilities of the device.

For ftell():

[EBADF]: The file descriptor underlying stream is not an open file descriptor.

NOTES

Although on the UNIX system an offset returned by ftell() is measured in bytes, and it is permissible to seek to positions relative to that offset, portability to non-UNIX systems requires that an offset be used by fseek() directly. Arithmetic may not meaningfully be performed on such an offset, which is not necessarily measured in bytes.