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
|
.TH MPU_FPURGE 3 "Август 2026" "libmpuio" "Руководство программиста LIBMPUIO"
.SH ИМЯ
mpu_fpurge, mpu_fpurge_unlocked \- отбросить буферизованное состояние потока LIBMPUIO без синхронизации backend
.SH ОБЗОР
.nf
#include <libmpuio.h>
int mpu_fpurge( mpu_FILE *stream );
int mpu_fpurge_unlocked( mpu_FILE *stream );
.fi
.SH ОПИСАНИЕ
.B mpu_fpurge
забывает буферизованное состояние, связанное с
.IR stream ,
не синхронизируя это состояние с нижележащим backend. Поэтому операция
принципиально отличается от
.BR mpu_fflush (3).
.PP
Для потока файла на основе дескриптора или cookie-потока callback, который в
данный момент выполняет запись, ожидающие байты в выходном буфере LIBMPUIO
отбрасываются. Они не записываются в файловый дескриптор и callback записи
cookie не вызывается. Байты, уже переданные backend, остаются без изменений.
.PP
Для потока файла на основе дескриптора или cookie-потока callback, который в
данный момент выполняет чтение, непрочитанные байты упреждающего чтения
отбрасываются. Позиция нижележащего дескриптора или cookie назад не
перемещается. Следовательно, логическая позиция потока перескакивает через
отброшенные данные упреждающего чтения. Операция lseek и callback seek cookie
не выполняются, поэтому очистка входного буфера допустима для каналов и других
непозиционируемых потоков.
.PP
Общий pushback UCS-2, созданный
.BR mpu_ungetc (3)
либо откатом scanner, всегда отбрасывается. Это относится ко всем backend.
.PP
.B mpu_fpurge
сохраняет индикатор EOF, индикатор ошибки и текущее направление чтения/записи
потока. Эта функция не является точкой синхронизации для смены направления
update-потока и не заменяет обязательный flush или операцию позиционирования.
.SH НАТИВНЫЕ ПОТОКИ ПАМЯТИ UCS-2
Нативный строковый backend, используемый
.BR mpu_fmemopen (3)
и
.BR mpu_open_memstream (3),
работает непосредственно с хранилищем UCS-2 и не имеет общего внешнего
байтового буфера чтения/записи, используемого backend файлов и cookie. Поэтому
purge не отменяет символы UCS-2, уже записанные в это хранилище. Pushback UCS-2
при этом всё равно отбрасывается.
.PP
Для
.BR mpu_open_memstream ()
mpu_fpurge() намеренно не является точкой публикации: функция не обновляет
опубликованный для вызывающей стороны размер только потому, что была запрошена
очистка. Последующий mpu_fflush() или mpu_fclose() выполняет обычную
публикацию текущего содержимого потока памяти.
.SH БЛОКИРОВКА
.B mpu_fpurge
захватывает рекурсивный mutex потока.
.B mpu_fpurge_unlocked
выполняет ту же операцию без захвата mutex и предназначена для использования
под
.BR mpu_flockfile (3)
или при эквивалентной синхронизации вызывающей стороны.
.SH ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Обе функции возвращают 0 при успехе и
.B mpu_EOF
при ошибке.
.SH ОШИБКИ
NULL-поток отвергается с
.BR EINVAL .
Недопустимый или уже отсоединённый поток отвергается с
.BR EBADF .
Обычная операция purge не выполняет I/O backend и потому не завершается ошибкой
лишь из-за того, что дескриптор или cookie не поддерживает позиционирование.
.SH ПРИМЕЧАНИЯ
Очистка входного буфера намеренно разрушительна. Данные, уже полученные из
нижележащего файлового дескриптора или cookie, но ещё не возвращённые
приложению, навсегда забываются потоком. Используйте эту операцию только если
такое отбрасывание упреждающего чтения действительно требуется.
.PP
Для очистки индикаторов EOF или ошибки используйте
.BR mpu_clearerr (3);
mpu_fpurge() намеренно оставляет оба индикатора без изменений.
.SH СМ. ТАКЖЕ
.BR libmpuio (3),
.BR mpu_fflush (3),
.BR mpu_fmemopen (3),
.BR mpu_fopencookie (3),
.BR mpu_flockfile (3),
.BR mpu_ungetc (3),
.BR mpu_unlocked (3)
|
