.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)