1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
.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)
|
