.TH MPU_PERROR 3 "Август 2026" "libmpuio" "Руководство программиста LIBMPUIO"
.SH ИМЯ
mpu_perror, mpu_strerror_r \- сформировать строгую UCS-2 диагностику для значений errno
.SH ОБЗОР
.nf
#include <libmpuio.h>

void      mpu_perror( const __mpu_char16_t *prefix );
int       mpu_strerror_r( int errnum, __mpu_char16_t *buffer, size_t size );
.fi
.SH ОПИСАНИЕ
.B mpu_strerror_r
получает из libc диагностическое сообщение, соответствующее
.IR errnum ,
и преобразует его из многобайтовой кодировки текущей локали
.B LC_CTYPE
в строгий UCS-2.  Преобразованная строка помещается в
.I buffer
и завершается нулём UCS-2.
.PP
.I size
измеряется в кодовых единицах
.BR __mpu_char16_t ,
а не в байтах.  Буфер принадлежит вызывающей стороне и после возврата функции
может использоваться повторно.  При успехе функция сохраняет исходное значение
.B errno
вызывающей стороны.
.PP
.B mpu_perror
выводит диагностическое сообщение для текущего значения
.B errno
в
.BR mpu_stderr .
Если
.I prefix
не равен NULL и не пуст, сначала выводится он, затем двоеточие, один пробел,
преобразованное диагностическое сообщение и символ новой строки.  Вся запись
защищается рекурсивной блокировкой
.BR mpu_stderr ,
поэтому вызовы LIBMPUIO не перемешивают отдельные части prefix/message.
.B mpu_perror
восстанавливает исходное значение errno перед возвратом.
.SH ПРЕОБРАЗОВАНИЕ СИМВОЛОВ
Исходный текст ошибки поступает из libc и, следовательно, соответствует локали
процесса
.BR LC_CTYPE .
LIBMPUIO преобразует этот многобайтовый текст в своё строгое 16-битное
представление UCS-2 до передачи через обычный потоковый слой.  Вывод в реальный
файл затем проходит стандартную границу преобразования UCS-2 в UTF-8.
.PP
Суррогатные кодовые единицы и символы, требующие скалярных значений Unicode
выше U+FFFF, не представимы в строгом UCS-2 LIBMPUIO и приводят к ошибке
преобразования
.BR EILSEQ .
Для самой
.B mpu_perror
ошибка преобразования или выделения памяти заменяется простым ASCII-сообщением
"Error N", чтобы диагностическая операция всё равно вывела запись.
.SH ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
.B mpu_strerror_r
возвращает ноль при успехе и -1 при ошибке.
.B mpu_perror
не возвращает значения.
.SH ОШИБКИ
.B mpu_strerror_r
может завершиться со следующими ошибками:
.TP
.B EINVAL
.I buffer
равен NULL или
.I size
равен нулю.
.TP
.B ERANGE
В буфере вызывающей стороны недостаточно места для полного диагностического
сообщения UCS-2 и завершающего NUL.  Если был предоставлен буфер ненулевого
размера, его первая кодовая единица устанавливается в NUL.
.TP
.B EILSEQ
Многобайтовое диагностическое сообщение текущей локали некорректно либо не
представимо в строгом UCS-2.
.TP
.B ENOMEM
Не удалось выделить временное хранилище для диагностического сообщения libc.
.SH ПОТОКОБЕЗОПАСНОСТЬ
Каждый результат
.B mpu_strerror_r
помещается в память, принадлежащую вызывающей стороне.  Доступ к временному
результату libc
.B strerror
сериализуется на время, пока LIBMPUIO делает приватную копию, поэтому
параллельные диагностические преобразования LIBMPUIO не открывают общий буфер
результата.
.PP
Как и для других зависящих от локали преобразований стандартной библиотеки C,
одновременное изменение глобальной локали процесса и выполнение активных
преобразований находится вне гарантированной модели использования.
.SH ПРИМЕРЫ
.nf
__mpu_char16_t  message[256];

if( mpu_strerror_r( errno, message, 256 ) == 0 )
  mpu_fprintf( mpu_stderr, MPU_UCS2("failure: %s\\n"), message );

errno = ENOENT;
mpu_perror( MPU_UCS2("open") );
.fi
.SH СМ. ТАКЖЕ
.BR libmpuio (3),
.BR mpu_fopen (3),
.BR mpu_fprintf (3),
.BR mpu_flockfile (3)