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
98
99
100
101
102
103
104
105
106
|
.TH MPU_FGETC 3 "Август 2026" "libmpuio" "Руководство программиста LIBMPUIO"
.SH ИМЯ
mpu_fgetc, mpu_getc, mpu_getchar, mpu_ungetc, mpu_fputc, mpu_putc, mpu_putchar, mpu_fgets, mpu_fputs, mpu_puts, mpu_getline, mpu_getdelim \- ввод-вывод символов UCS-2, строк и динамических строк
.SH ОБЗОР
.nf
#include <libmpuio.h>
int mpu_fgetc( mpu_FILE *stream );
int mpu_getc( mpu_FILE *stream );
int mpu_getchar( void );
int mpu_ungetc( __mpu_char16_t c, mpu_FILE *stream );
int mpu_fputc( __mpu_char16_t c, mpu_FILE *stream );
int mpu_putc( __mpu_char16_t c, mpu_FILE *stream );
int mpu_putchar( __mpu_char16_t c );
__mpu_char16_t *mpu_fgets( __mpu_char16_t *s, int n, mpu_FILE *stream );
int mpu_fputs( const __mpu_char16_t *s, mpu_FILE *stream );
int mpu_puts( const __mpu_char16_t *s );
ssize_t mpu_getline( __mpu_char16_t **lineptr, size_t *n,
mpu_FILE *stream );
ssize_t mpu_getdelim( __mpu_char16_t **lineptr, size_t *n,
__mpu_char16_t delimiter, mpu_FILE *stream );
.fi
.SH ОПИСАНИЕ
Функции работы с символами и строками оперируют значениями UCS-2. Для потоков
реальных файлов UTF-8 декодируется при вводе и кодируется при выводе. Строковые
потоки хранят UCS-2 непосредственно.
.PP
.B mpu_ungetc
гарантирует возврат во входной поток как минимум одного символа. Суррогатные
значения отвергаются.
.B mpu_fgets
сохраняет не более n-1 символов UCS-2 и завершает строку назначения нулём.
.B mpu_puts
добавляет символ новой строки.
.SH ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Символьные функции возвращают значение символа UCS-2 либо
.BR mpu_EOF .
Функции строкового вывода возвращают неотрицательное значение при успехе либо
mpu_EOF при ошибке. mpu_fgets возвращает указатель на буфер назначения или
NULL.
.SH ОШИБКИ
Некорректный UTF-8, скалярные значения Unicode, не представимые в UCS-2, и
суррогатные символы приводят к
.BR EILSEQ .
.SH КОДИРОВКА ТЕКСТА
Символы, возвращаемые текстовым API, являются значениями UCS-2. Backend
реального файла декодирует современный UTF-8 и отвергает с EILSEQ некорректный
ввод, суррогатные значения и скалярные значения выше U+FFFF. Расширение через
пары суррогатов не используется.
.SH ВОЗВРАТ СИМВОЛА В ПОТОК
.BR mpu_ungetc ()
возвращает один символ UCS-2 во внутреннее состояние pushback потока.
Возвращённые символы участвуют в логическом позиционировании; для реального
UTF-8-файла их ширина в закодированных байтах учитывается функцией
.BR mpu_ftello (3).
Успешная операция позиционирования отбрасывает pushback.
.SH ДИНАМИЧЕСКИЙ ВВОД СТРОК
.BR mpu_getline ()
и
.BR mpu_getdelim ()
являются UCS-2-аналогами динамических интерфейсов ввода строк POSIX/GNU.
Вызывающая сторона передаёт адрес указателя UCS-2 и выделенную ёмкость буфера в
символах. Если указатель равен NULL или ёмкость равна нулю, LIBMPUIO выделяет
начальный буфер. По мере необходимости буфер увеличивается с помощью realloc,
а, возможно, изменившиеся указатель и ёмкость возвращаются через объекты
вызывающей стороны.
.PP
.B mpu_getdelim
читает до указанного разделителя UCS-2 включительно.
.B mpu_getline
\- ровно та же вспомогательная форма с разделителем «новая строка».
Завершающий NUL UCS-2 сохраняется, но не включается в возвращаемое число
символов. При достижении конца файла непустая последняя строка без завершающего
разделителя возвращается как обычно; следующий вызов возвращает -1. Суррогатный
разделитель отвергается с EILSEQ.
.PP
Выделенный буфер принадлежит вызывающей стороне и может быть освобождён через
free(3). Аргумент размера измеряется в элементах UCS-2, а не в байтах.
.SH БЛОКИРУЕМЫЕ И НЕБЛОКИРУЕМЫЕ ФОРМЫ
Семейства fgetc/getc/getchar, fputc/putc/putchar, fgets, fputs, getline и
getdelim имеют формы
.B _unlocked
с идентичными преобразованием символов, буферизацией, индикаторами,
возвращаемыми значениями и ошибками, но без неявной блокировки потока.
Используйте их только при удержании
.BR mpu_flockfile (3)
или когда эксклюзивный доступ гарантирован иным способом.
.PP
.BR mpu_ungetc ()
и
.BR mpu_puts ()
не имеют публичных вариантов unlocked.
.SH ПОТОКОБЕЗОПАСНОСТЬ
Обычные формы сериализуют доступ к отдельному потоку. Последовательность
нескольких обычных вызовов автоматически не становится атомарной как единое
целое; если транзакция из нескольких вызовов не должна перемешиваться с
другими, используйте
.BR mpu_flockfile (3)
вместе с unlocked-вызовами.
.SH СМ. ТАКЖЕ
.BR libmpuio (3),
.BR mpu_fread (3),
.BR mpu_printf (3)
|
