.TH MPU_FSEEK 3 "August 2026" "libmpuio" "LIBMPUIO Programmer's Manual"
.SH NAME
mpu_fseek, mpu_fseeko, mpu_ftell, mpu_ftello, mpu_fgetpos, mpu_fsetpos, mpu_rewind \- position a LIBMPUIO stream
.SH SYNOPSIS
.nf
#include <libmpuio.h>

int       mpu_fseek( mpu_FILE *stream, off_t offset, int whence );
int       mpu_fseeko( mpu_FILE *stream, off_t offset, int whence );
off_t     mpu_ftell( mpu_FILE *stream );
off_t     mpu_ftello( mpu_FILE *stream );
int       mpu_fgetpos( mpu_FILE *stream, mpu_fpos_t *pos );
int       mpu_fsetpos( mpu_FILE *stream, const mpu_fpos_t *pos );
void      mpu_rewind( mpu_FILE *stream );
.fi
.SH DESCRIPTION
The
.I whence
argument is one of MPU_SEEK_SET, MPU_SEEK_CUR or MPU_SEEK_END.
A successful seek synchronizes buffered state, discards pushback, resets the
read/write direction state of an update stream, and clears the EOF indicator.
It does not clear an already-set stream error indicator.

.PP
.B mpu_fgetpos()
saves the current logical stream position in an
.I mpu_fpos_t
object.  The position includes the same buffered-input and UCS-2 pushback
corrections used by mpu_ftello().  The object also contains reserved conversion
state, analogous to the conversion state carried by glibc fpos_t; the current
UTF-8 backend is stateless between complete UCS-2 characters, so this state is
zero.
.PP
.B mpu_fsetpos()
restores a position previously obtained with mpu_fgetpos().  It has the same
stream-state effects as a successful mpu_fseeko(stream, pos, MPU_SEEK_SET):
pushback is discarded, EOF is cleared, update-stream direction is reset, and
an existing error indicator is preserved.
.PP
.B mpu_rewind()
seeks to offset zero and, after a successful reposition, clears both EOF and
error indicators.  This differs intentionally from mpu_fseek(), which clears
EOF only.
.PP
On an update stream, a positioning operation is a synchronization point between
reading and writing.  mpu_fflush() likewise synchronizes pending output and,
for seekable input streams, reconciles buffered input with the underlying file
position.
.PP
For real-file streams, positions are UTF-8 byte offsets.  mpu_ftello() reports
the logical position, compensating for unread buffered bytes and for characters
returned by mpu_ungetc().  A pushed-back UCS-2 character therefore moves the
logical position backward by the number of bytes in its UTF-8 encoding.
MPU_SEEK_CUR is evaluated from this same logical position rather than from the
underlying descriptor position.  A successful seek discards pushback.
.PP
The positioning interfaces use
.B off_t
throughout.  On systems with a 64-bit off_t they therefore support sparse and
regular-file positions beyond 4 GiB.  mpu_fgetpos() preserves the same off_t
position in mpu_fpos_t.  On non-seekable descriptors such as pipes, ftello,
fgetpos, fseeko and fsetpos fail with
.B ESPIPE
and set the stream error indicator.
.SH LOGICAL POSITION
On a real text stream, positions are external UTF-8 byte offsets, not counts of
UCS-2 characters.  Buffered read-ahead may place the underlying descriptor
ahead of the logical application position; ftello/fgetpos compensate for
unread buffered bytes and pushback.
.PP
MPU_SEEK_CUR is evaluated relative to this logical position.  Successful
positioning synchronizes buffered state, discards pushback, clears EOF, and
resets update-stream direction state.  An already set error indicator is not
cleared by fseek/fseeko/fsetpos; rewind clears both EOF and error on success.
.SH FGETPOS AND FSETPOS
.B mpu_fpos_t
contains a byte position plus reserved conversion state.  The current strict
UTF-8 decoder has no persistent shift state between complete UCS-2 characters,
so the state field is presently zero, but it is retained in the public type for
future ABI-compatible extension.
.SH NONSEEKABLE STREAMS
Pipes and similar descriptors reject seek/tell/fgetpos/fsetpos operations with
ESPIPE and set the stream error indicator where appropriate.
.SH LARGE FILES
The API uses off_t for seek/tell positions and is tested with sparse offsets
above 4 GiB on systems providing a 64-bit off_t.
.SH LOCKING
Positioning functions are synchronized and currently have no public unlocked
variants because they change multiple pieces of stream state atomically.

.SH SEE ALSO
.BR mpu_fopen (3),
.BR mpu_fflush (3),
.BR libmpuio (3)