.TH MPU_POPEN 3 "August 2026" "libmpuio" "LIBMPUIO Programmer's Manual"
.SH NAME
mpu_popen, mpu_pclose \- open and close a LIBMPUIO command pipe
.SH SYNOPSIS
.nf
#include <libmpuio.h>

mpu_FILE *mpu_popen( const char *command, const char *mode );
int       mpu_pclose( mpu_FILE *stream );
.fi
.SH DESCRIPTION
.B mpu_popen
starts
.I command
through
.B /bin/sh -c
and returns a unidirectional descriptor-backed LIBMPUIO stream.
The mode is exactly
.B "r"
for reading the command's standard output or
.B "w"
for writing the command's standard input.
.PP
Text operations retain the normal LIBMPUIO boundary: data in the stream is
UCS-2 and the pipe carries external UTF-8 bytes.  Raw
.BR mpu_fread (3)
and
.BR mpu_fwrite (3)
operate directly on pipe bytes.
.PP
.B mpu_pclose
flushes and closes a stream created by
.BR mpu_popen ,
then waits for the command process to terminate.  A command stream must be
finalized with mpu_pclose(), not detached with mpu_freopen() or finalized with
mpu_fclose(), because mpu_pclose() performs the required wait for the child.
.SH RETURN VALUE
.B mpu_popen
returns a stream pointer on success and NULL on failure.
.B mpu_pclose
returns the child wait status on success, or -1 on failure with
.B errno
set.  The status can be examined with the macros described by
.BR waitpid (2).
.SH ERRORS
.B EINVAL
is reported for a NULL command, an unsupported mode, or an attempt to call
.B mpu_pclose
on a stream not created by
.BR mpu_popen .
.BR mpu_freopen (3)
also reports EINVAL when passed a command-pipe stream.
.SH NOTES
The command string is interpreted by the shell and follows normal shell
quoting and expansion rules.  Do not construct it from untrusted text without
appropriate validation or quoting.
.PP
Only the POSIX unidirectional
.B r
and
.B w
modes are supported.  The parent pipe endpoint is close-on-exec so previously
opened command streams are not leaked into subsequently executed commands.
.SH EXAMPLE
.nf
mpu_FILE       *fp = mpu_popen( "printf 'hello\\n'", "r" );
__mpu_char16_t  line[32];
int             status;

if( fp != NULL )
{
  mpu_fgets( line, 32, fp );
  status = mpu_pclose( fp );
}
.fi
.SH SEE ALSO
.BR libmpuio (3),
.BR mpu_fopen (3),
.BR mpu_fclose (3),
.BR mpu_fread (3),
.BR mpu_fwrite (3),
.BR waitpid (2)