.TH MPU_FLOCKFILE 3 "August 2026" "libmpuio" "LIBMPUIO Programmer's Manual"
.SH NAME
mpu_flockfile, mpu_ftrylockfile, mpu_funlockfile \- lock an LIBMPUIO stream
.SH SYNOPSIS
.nf
#include <libmpuio.h>

void      mpu_flockfile( mpu_FILE *stream );
int       mpu_ftrylockfile( mpu_FILE *stream );
void      mpu_funlockfile( mpu_FILE *stream );
.fi
.SH DESCRIPTION
.BR mpu_flockfile ()
locks
.I stream
for exclusive use by the calling thread.  If another thread owns the
stream lock, the call waits until the lock becomes available.
.PP
LIBMPUIO stream locks are recursive.  The owning thread may call
.BR mpu_flockfile ()
again, and may call ordinary locking stream functions such as
.BR mpu_fputc (3)
or
.BR mpu_fprintf (3)
while the explicit lock is held.  A matching number of
.BR mpu_funlockfile ()
calls releases the lock.
.PP
.BR mpu_ftrylockfile ()
performs the same acquisition without waiting.
.BR mpu_funlockfile ()
releases one level of ownership held by the calling thread.
.SH RETURN VALUE
.BR mpu_ftrylockfile ()
returns zero when the lock was acquired.  It returns a nonzero pthread
error number when the lock could not be acquired.
.PP
.BR mpu_flockfile ()
and
.BR mpu_funlockfile ()
do not return a value.
.SH ERRORS
On an invalid stream LIBMPUIO sets
.BR errno .
A failed pthread locking operation is also reflected in
.BR errno .
.SH NOTES
The lock protects an
.B mpu_FILE
object, including its buffering state, UTF-8/UCS-2 conversion state and
formatted I/O operations.  It does not provide advisory or mandatory
locking of the underlying filesystem object.
.SH RELATION TO _UNLOCKED FUNCTIONS
The primary use of this family is to create an atomic region containing several
_unlocked operations.  The unlocked functions skip only the implicit stream
mutex; all conversion, buffering, validation, return-value, errno, EOF, and
error-indicator rules remain unchanged.
.PP
The mutex is recursive.  Therefore an ordinary locked LIBMPUIO function may be
called by a thread that already owns the stream lock, although using the
unlocked counterpart avoids redundant recursive locking.
.SH GLOBAL STREAM LIST
The internal all-stream list is protected separately from individual stream
mutexes.  Internal code uses a fixed order: global list lock first, then stream
lock.  This protects mpu_fflush(NULL) against concurrent stream removal.
Application code does not manipulate the list lock directly.
.SH LIFETIME RULE
An explicit stream lock does not turn a stale pointer into a valid stream.
Applications must arrange that mpu_fclose() cannot destroy a stream while
another thread may still attempt to lock or use that pointer.

.SH SEE ALSO
.BR libmpuio (3),
.BR mpu_fopen (3),
.BR mpu_printf (3),
.BR mpu_scanf (3)
.SH GLOBAL STREAM LIST LOCKING
LIBMPUIO uses an internal global-list lock to serialize mpu_fflush(NULL),
stream insertion, and stream removal.  The internal lock order is global list
first, then the individual stream lock.  mpu_fclose() follows that order and
unlinks the stream before close-time I/O and destruction.  User code does not
have direct access to the global-list lock and should not attempt to infer or
hold it through public interfaces.