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
95
96
97
|
.TH MPU_FSEEK 3 "Август 2026" "libmpuio" "Руководство программиста LIBMPUIO"
.SH ИМЯ
mpu_fseek, mpu_fseeko, mpu_ftell, mpu_ftello, mpu_fgetpos, mpu_fsetpos, mpu_rewind \- позиционирование потока LIBMPUIO
.SH ОБЗОР
.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 ОПИСАНИЕ
Аргумент
.I whence
принимает одно из значений MPU_SEEK_SET, MPU_SEEK_CUR или MPU_SEEK_END.
Успешный seek синхронизирует буферизованное состояние, отбрасывает pushback,
сбрасывает состояние направления чтения/записи update-потока и очищает
индикатор EOF. Уже установленный индикатор ошибки потока при этом не очищается.
.PP
.B mpu_fgetpos()
сохраняет текущую логическую позицию потока в объекте
.IR mpu_fpos_t .
Позиция включает те же поправки на буферизованный ввод и pushback UCS-2, которые
использует mpu_ftello(). Объект также содержит зарезервированное состояние
преобразования, аналогичное состоянию преобразования в glibc fpos_t; текущий
UTF-8 backend не имеет состояния между полными символами UCS-2, поэтому это
поле равно нулю.
.PP
.B mpu_fsetpos()
восстанавливает позицию, ранее полученную через mpu_fgetpos(). Влияние на
состояние потока такое же, как у успешного
mpu_fseeko(stream, pos, MPU_SEEK_SET): pushback отбрасывается, EOF очищается,
направление update-потока сбрасывается, а существующий индикатор ошибки
сохраняется.
.PP
.B mpu_rewind()
позиционирует поток на смещение ноль и после успешного перемещения очищает оба
индикатора \- EOF и ошибки. Это намеренно отличается от mpu_fseek(), которая
очищает только EOF.
.PP
Для update-потока операция позиционирования является точкой синхронизации между
чтением и записью. mpu_fflush() аналогично синхронизирует ожидающий вывод и,
для позиционируемых входных потоков, согласует буферизованный ввод с позицией
нижележащего файла.
.PP
Для потоков реальных файлов позиции являются байтовыми смещениями во внешнем
UTF-8. mpu_ftello() сообщает логическую позицию, компенсируя непрочитанные
буферизованные байты и символы, возвращённые mpu_ungetc(). Поэтому возвращённый
в поток символ UCS-2 сдвигает логическую позицию назад на число байтов его
UTF-8-представления. MPU_SEEK_CUR вычисляется от этой же логической позиции,
а не от позиции нижележащего дескриптора. Успешный seek отбрасывает pushback.
.PP
Все интерфейсы позиционирования используют
.BR off_t .
На системах с 64-битным off_t они поддерживают разреженные и обычные файловые
позиции за пределами 4 GiB. mpu_fgetpos() сохраняет ту же позицию off_t в
mpu_fpos_t. Для непозиционируемых дескрипторов, например каналов, ftello,
fgetpos, fseeko и fsetpos завершаются с
.B ESPIPE
и устанавливают индикатор ошибки потока.
.SH ЛОГИЧЕСКАЯ ПОЗИЦИЯ
В реальном текстовом потоке позиция является внешним байтовым смещением UTF-8,
а не числом символов UCS-2. Упреждающее чтение в буфер может продвинуть
нижележащий дескриптор дальше логической позиции приложения; ftello/fgetpos
компенсируют непрочитанные буферизованные байты и pushback.
.PP
MPU_SEEK_CUR вычисляется относительно этой логической позиции. Успешное
позиционирование синхронизирует буферизованное состояние, отбрасывает pushback,
очищает EOF и сбрасывает состояние направления update-потока. Уже установленный
индикатор ошибки не очищается fseek/fseeko/fsetpos; rewind при успехе очищает и
EOF, и ошибку.
.SH FGETPOS И FSETPOS
.B mpu_fpos_t
содержит байтовую позицию и зарезервированное состояние преобразования.
Текущий строгий UTF-8 decoder не имеет сохраняемого shift-state между полными
символами UCS-2, поэтому поле состояния сейчас равно нулю, но оно оставлено в
публичном типе для будущего ABI-совместимого расширения.
.SH НЕПОЗИЦИОНИРУЕМЫЕ ПОТОКИ
Каналы и подобные дескрипторы отвергают операции seek/tell/fgetpos/fsetpos с
ESPIPE и, где требуется, устанавливают индикатор ошибки потока.
.SH БОЛЬШИЕ ФАЙЛЫ
API использует off_t для позиций seek/tell и тестируется с разреженными
смещениями выше 4 GiB на системах, предоставляющих 64-битный off_t.
.SH БЛОКИРОВКА
Функции позиционирования синхронизированы и в настоящее время не имеют публичных
unlocked-вариантов, поскольку атомарно изменяют несколько частей состояния
потока.
.SH СМ. ТАКЖЕ
.BR mpu_fopen (3),
.BR mpu_fflush (3),
.BR libmpuio (3)
|
