.TH MPU_FGETC 3 "August 2026" "libmpuio" "LIBMPUIO Programmer's Manual"
.SH NAME
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 character, string, and dynamic line I/O
.SH SYNOPSIS
.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 DESCRIPTION
Character and string functions operate on UCS-2 values.  On real-file streams,
UTF-8 is decoded on input and encoded on output.  String streams store UCS-2
directly.
.PP
.B mpu_ungetc
guarantees at least one character of pushback.  Surrogate values are rejected.
.B mpu_fgets
stores at most n-1 UCS-2 characters and terminates the destination with zero.
.B mpu_puts
appends a newline.
.SH RETURN VALUE
Character functions return the UCS-2 character value or
.BR mpu_EOF .
String output functions return a nonnegative value on success or mpu_EOF on
failure.  mpu_fgets returns its destination pointer or NULL.
.SH ERRORS
Malformed UTF-8, non-UCS-2 Unicode scalars, and surrogate characters cause
.BR EILSEQ .
.SH TEXT ENCODING
Characters returned by the text API are UCS-2 values.  A real-file backend
decodes modern UTF-8 and rejects malformed input, surrogate values, and scalar
values above U+FFFF with EILSEQ.  No surrogate-pair extension is used.
.SH PUSHBACK
.BR mpu_ungetc ()
pushes one UCS-2 character back into the stream's internal pushback state.
Pushed-back characters participate in logical positioning; on a real UTF-8
file their encoded byte width is accounted for by
.BR mpu_ftello (3).
A successful positioning operation discards pushback.

.SH DYNAMIC LINE INPUT
.BR mpu_getline ()
and
.BR mpu_getdelim ()
are the UCS-2 counterparts of the POSIX/GNU dynamic line-input interfaces.
The caller passes the address of a UCS-2 pointer and its allocated capacity in
characters.  If the pointer is NULL or the capacity is zero, LIBMPUIO allocates
an initial buffer.  The buffer is enlarged with realloc as required and the
possibly changed pointer and capacity are returned through the caller objects.
.PP
.B mpu_getdelim
reads through and includes the requested UCS-2 delimiter.
.B mpu_getline
is exactly the newline-delimited convenience form.  A terminating UCS-2 NUL is
stored but is not included in the returned character count.  At end of file, a
nonempty final unterminated line is returned normally; a subsequent call returns
-1.  A surrogate delimiter is rejected with EILSEQ.
.PP
The allocated buffer belongs to the caller and may be released with free(3).
The size argument is measured in UCS-2 elements, not bytes.

.SH LOCKED AND UNLOCKED FORMS
The fgetc/getc/getchar, fputc/putc/putchar, fgets, fputs, getline, and getdelim families have
.B _unlocked
forms with identical character conversion, buffering, indicators, return
values, and errors, but without implicit stream locking.  Use them only while
holding
.BR mpu_flockfile (3)
or when exclusive access is otherwise guaranteed.
.PP
.BR mpu_ungetc ()
and
.BR mpu_puts ()
have no public unlocked variants.
.SH THREAD SAFETY
Ordinary forms serialize access to an individual stream.  A sequence of
multiple ordinary calls is not automatically atomic as a group; use
.BR mpu_flockfile (3)
with unlocked calls when a multi-call transaction must not interleave.

.SH SEE ALSO
.BR libmpuio (3),
.BR mpu_fread (3),
.BR mpu_printf (3)