.TH MPU_PERROR 3 "August 2026" "libmpuio" "LIBMPUIO Programmer's Manual"
.SH NAME
mpu_perror, mpu_strerror_r \- produce strict UCS-2 diagnostics for errno values
.SH SYNOPSIS
.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 DESCRIPTION
.B mpu_strerror_r
obtains the libc diagnostic associated with
.I errnum
and converts it from the current
.B LC_CTYPE
multibyte encoding to strict UCS-2.  The converted string is stored in
.I buffer
and terminated by a UCS-2 NUL.
.PP
.I size
is measured in
.B __mpu_char16_t
code units, not bytes.  The caller owns the buffer and may reuse it after the
function returns.  On success the function preserves the caller's existing
.B errno
value.
.PP
.B mpu_perror
prints the diagnostic for the current value of
.B errno
to
.BR mpu_stderr .
If
.I prefix
is non-NULL and nonempty, it is written first, followed by a colon, one space,
the converted diagnostic, and a newline.  The complete record is protected by
the recursive lock of
.B mpu_stderr
so LIBMPUIO callers do not interleave individual prefix/message fragments.
.B mpu_perror
restores the original errno value before returning.
.SH CHARACTER CONVERSION
The source error text comes from libc and therefore follows the process
.B LC_CTYPE
locale.  LIBMPUIO converts that multibyte text to its strict 16-bit UCS-2
representation before sending it through the ordinary stream layer.  Real-file
output then crosses the usual UCS-2 to UTF-8 boundary.
.PP
Surrogate code units and characters requiring Unicode scalar values above
U+FFFF cannot be represented by LIBMPUIO strict UCS-2 and cause conversion
failure with
.BR EILSEQ .
For
.B mpu_perror
itself, a conversion/allocation failure is replaced by a simple ASCII
"Error N" fallback so that the diagnostic operation still emits a record.
.SH RETURN VALUE
.B mpu_strerror_r
returns zero on success and -1 on failure.
.B mpu_perror
has no return value.
.SH ERRORS
.B mpu_strerror_r
may fail with:
.TP
.B EINVAL
.I buffer
is NULL or
.I size
is zero.
.TP
.B ERANGE
The caller buffer does not have room for the complete UCS-2 diagnostic and its
terminating NUL.  If a nonzero buffer was supplied, its first code unit is set
to NUL.
.TP
.B EILSEQ
The current-locale multibyte diagnostic is invalid or is not representable in
strict UCS-2.
.TP
.B ENOMEM
Temporary storage for the libc diagnostic could not be allocated.
.SH THREAD SAFETY
Each
.B mpu_strerror_r
result is placed in caller-owned storage.  Access to libc's transient
.B strerror
result is serialized while LIBMPUIO makes a private copy, so concurrent
LIBMPUIO diagnostic conversions do not expose shared result storage.
.PP
As with other locale-sensitive C library conversions, changing the global
process locale concurrently with active conversions is outside the guaranteed
usage model.
.SH EXAMPLES
.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 SEE ALSO
.BR libmpuio (3),
.BR mpu_fopen (3),
.BR mpu_fprintf (3),
.BR mpu_flockfile (3)