.TH MPU_FPURGE 3 "August 2026" "libmpuio" "LIBMPUIO Programmer's Manual"
.SH NAME
mpu_fpurge, mpu_fpurge_unlocked \- discard buffered LIBMPUIO stream state without backend synchronization
.SH SYNOPSIS
.nf
#include <libmpuio.h>

int       mpu_fpurge( mpu_FILE *stream );
int       mpu_fpurge_unlocked( mpu_FILE *stream );
.fi
.SH DESCRIPTION
.B mpu_fpurge
forgets buffered state associated with
.I stream
without synchronizing that state with the underlying backend.  It is therefore
fundamentally different from
.BR mpu_fflush (3).
.PP
For a descriptor-backed file or callback cookie stream that is currently
writing, pending bytes in the LIBMPUIO output buffer are discarded.  They are
not written to the file descriptor and no cookie write callback is invoked.
Bytes that were already transferred to the backend remain unchanged.
.PP
For a descriptor-backed file or callback cookie stream that is currently
reading, unread read-ahead bytes are discarded.  The underlying descriptor or
cookie position is not moved backward.  Consequently the logical stream
position advances past the discarded read-ahead.  No lseek operation and no
cookie seek callback is performed, so input purge is valid on pipes and other
nonseekable streams.
.PP
Generic UCS-2 pushback created by
.BR mpu_ungetc (3)
or by scanner rollback is always discarded.  This applies to every backend.
.PP
.B mpu_fpurge
preserves the stream's EOF indicator, error indicator, and current read/write
direction.  It is not a synchronization point for update-stream direction
changes and does not replace a required flush or positioning operation.
.SH NATIVE UCS-2 MEMORY STREAMS
The native string backend used by
.BR mpu_fmemopen (3)
and
.BR mpu_open_memstream (3)
operates directly on UCS-2 storage and does not have the generic external-byte
read/write buffer used by file and cookie backends.  Therefore purge does not
undo UCS-2 characters already written to that storage.  It still discards
UCS-2 pushback.
.PP
For
.BR mpu_open_memstream (),
mpu_fpurge() is deliberately not a publication point: it does not update the
caller's published size merely because purge was requested.  A later
mpu_fflush() or mpu_fclose() performs the normal publication of the current
memory-stream contents.
.SH LOCKING
.B mpu_fpurge
acquires the recursive stream mutex.
.B mpu_fpurge_unlocked
performs the same operation without acquiring that mutex and is intended for
use under
.BR mpu_flockfile (3)
or equivalent caller synchronization.
.SH RETURN VALUE
Both functions return 0 on success and
.B mpu_EOF
on failure.
.SH ERRORS
A NULL stream is rejected with
.BR EINVAL .
An invalid or already disassociated stream is rejected with
.BR EBADF .
Normal purge performs no backend I/O and therefore does not fail merely because
a descriptor or cookie is nonseekable.
.SH NOTES
Input purge is intentionally destructive.  Data already fetched from an
underlying file descriptor or cookie but not yet returned to the application
is permanently forgotten by the stream.  Use it only when discarding such
read-ahead is actually desired.
.PP
To clear EOF or error indicators, use
.BR mpu_clearerr (3);
mpu_fpurge() intentionally leaves both indicators unchanged.
.SH SEE ALSO
.BR libmpuio (3),
.BR mpu_fflush (3),
.BR mpu_fmemopen (3),
.BR mpu_fopencookie (3),
.BR mpu_flockfile (3),
.BR mpu_ungetc (3),
.BR mpu_unlocked (3)