.TH MPU_FREAD 3 "August 2026" "libmpuio" "LIBMPUIO Programmer's Manual"
.SH NAME
mpu_fread, mpu_fwrite \- raw byte block I/O on LIBMPUIO streams
.SH SYNOPSIS
.nf
#include <libmpuio.h>

size_t    mpu_fread( void *ptr, size_t size, size_t nmemb,
                     mpu_FILE *stream );
size_t    mpu_fwrite( const void *ptr, size_t size, size_t nmemb,
                      mpu_FILE *stream );
.fi
.SH DESCRIPTION
These functions transfer raw bytes.  They do not perform UCS-2/UTF-8
conversion.  The return value is the number of complete elements transferred.
.PP
If either
.I size
or
.I nmemb
is zero, zero is returned immediately and no backend read or write operation
is performed.  In that case a NULL data pointer is accepted.
.PP
The product
.I size * nmemb
is checked before the transfer.  If it cannot be represented by
.B size_t,
zero is returned,
.B errno
is set to
.B EOVERFLOW,
and the stream error indicator is set.
.PP
POSIX read and write operations interrupted by a signal are retried after
.B EINTR.
Short writes are accounted for exactly.  If a buffered flush writes a prefix
and then fails, only the unwritten suffix remains pending in the stream; a
later successful flush therefore does not duplicate bytes already committed
to the descriptor.  A short transfer can make mpu_fread() or mpu_fwrite()
return fewer complete elements than requested.
.SH BINARY VERSUS TEXT I/O
These functions transfer raw bytes and do not perform UTF-8/UCS-2 conversion.
They may therefore be used for binary data even though the text functions on
the same real-file backend use UTF-8.
.SH PARTIAL ELEMENTS
The return value counts complete elements.  If input ends or fails after some
bytes of the next element have already been transferred, those bytes remain
consumed and are present in the caller's buffer, but that incomplete element is
not included in the return count.
.PP
If size or nmemb is zero, no backend operation is performed and zero is
returned.  Multiplication overflow in size*nmemb is rejected with EOVERFLOW.
.SH NONBLOCKING AND INTERRUPTED I/O
EINTR from the underlying read/write operation is retried.  EAGAIN or
EWOULDBLOCK is an error condition, not EOF.  A caller may use
.BR mpu_clearerr (3)
and retry when the descriptor becomes ready.
.PP
For output, a partial successful write followed by failure advances the pending
buffer so a later flush retries only the unwritten suffix and does not duplicate
already transmitted bytes.
.SH LOCKED AND UNLOCKED FORMS
.BR mpu_fread_unlocked ()
and
.BR mpu_fwrite_unlocked ()
have the same element counting, partial-transfer, overflow, EINTR, EAGAIN,
indicator, and backend semantics as the ordinary functions, but do not acquire
the stream mutex.

.SH SEE ALSO
.BR mpu_fgetc (3),
.BR mpu_printf (3),
.BR libmpuio (3)
.SH NONBLOCKING INPUT
On a nonblocking descriptor, if no input is currently available,
.B mpu_fread()
returns the number of complete elements already obtained, possibly zero,
sets the stream error indicator, and leaves
.B errno
as
.B EAGAIN
or
.B EWOULDBLOCK.
This condition is not end-of-file, so the EOF indicator is not set.
After
.BR mpu_clearerr (3),
a later call can continue reading when more data becomes available.
.PP
If the underlying input ends or becomes temporarily unavailable after only
part of the final requested element has been read, those bytes have still
been consumed from the stream and copied to the caller's buffer.  The return
value nevertheless counts complete elements only, as required for fread-style
block I/O.