.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)popen.3	8.2 (Berkeley) 5/3/95
.\"
.\" $FreeBSD$
.\"
.Dd May 3, 1995
.Dt POPEN 3
.Os
.Sh 名称
.Nm popen ,
.Nm pclose
.Nd 
.Tn 入出力処理
.Sh ライブラリ
.Lb libc
.Sh 書式
.Fd #include <stdio.h>
.Ft FILE *
.Fn popen "const char *command" "const char *type"
.Ft int
.Fn pclose "FILE *stream"
.Sh 解説
.Fn popen
関数は、双方向パイプフォークを作成し、シェルを起動してプロセスを
.Dq 開き
ます。
親プロセスで事前に
.Fn popen
を呼び出して開いたストリームは、
新しい子プロセスによってクローズされます。
以前の
.Fn popen
は単方向のパイプで実装されていたため、
.Fn popen
の多くの実装は、
読み書きの両方ではなく、
.Fa type
引数が読込もしくは書込のどちらかを指定すること
だけ許可していました。
現在の
.Fn popen
は双方向パイプで実装しているので、
.Fa type
引数で双方向データフローを要求できます。
.Fa type
引数はヌル文字で終わる文字列のポインタで、
読取りの場合は
.Ql r
、書込みの場合は
.Ql w
、読み書きの場合は
.Ql r+
である必要があります。
.Pp
.Fa command
引数は、シェルコマンドラインを含む、
ヌル文字で終了する文字列のポインタです。
このコマンドは、
.Fl c
フラグで
.Pa /bin/sh
に渡されます。解釈がある場合、シェルで実行されます。
.Pp
.Fn popen
の戻り値は通常の標準
.Tn 入出力
とあらゆる点で同等のものです。
ただし、閉じるときは、
.Fn fclose
ではなく
.Fn pclose
を使わなければなりません。
このようなストリームに書込むと、
コマンドの標準入力に書込まれます。
コマンドの標準出力は、
そのコマンド自体で変更しないかぎり、
.Fn popen
で呼び出したプロセスのものと同じです。
反対に、
.Fn popen
で
.Dq 開かれた
ストリームからの読込みは、
コマンドの標準出力から読込まれます。
コマンドの標準入力は 
.Fn popen
を呼び出したプロセスのものと同じです。
.Pp
出力
.Fn popen
ストリームは、デフォルトで完全にバッファ
されることに注意してください。
.Pp
.Fn pclose
関数は、結び付けられたプロセスの終了を待機し、
.Fn wait4
が戻すコマンドの終了ステータスを返します。
.Sh 戻り値
.Fn popen
関数は、
.Xr fork 2
か
.Xr pipe 2
でエラーが発生した場合、またはメモリを割り当てられない場合は
.Dv ヌル
を戻します。
.Pp
.Fn pclose
関数は、
.Fa ストリーム
が
.Fn popen
で
.Dq 開いた
コマンドと
結び付いていなかった場合、または
.Fa ストリーム
がすでに
.Fn pclose
で
.Dq 閉じている
場合、あるいは
.Xr wait4
でエラーが発生した場合は \-1 を戻します。
.Sh エラー
.Fn popen
関数は、信頼性のある
.Va errno
を設定しません。
.Sh 関連項目
.Xr sh 1 ,
.Xr fork 2 ,
.Xr pipe 2 ,
.Xr wait4 2 ,
.Xr fclose 3 ,
.Xr fflush 3 ,
.Xr fopen 3 ,
.Xr stdio 3 ,
.Xr system 3
.Sh バグ
読取り用に開いたコマンドの標準入力は、
.Fn popen
を呼び出したプロセスとシークオフセットを共有するので、
オリジナルプロセスがバッファ読取りを実行すると、
コマンドの入力位置が予想どおりにならないことがあります。
同様に、書込み用に開いたコマンドの出力は、
オリジナルプロセスのものと混ざることがあります。後者は、
.Fn popen
の前に
.Xr fflush 3
を呼び出すことで回避できます。
.Pp
シェルを実行しないことには、それが実行できないコマンドのシェル
なのか、すぐに終了してしまうコマンドか、区別できません。
終了ステータスの 127 のみがヒントになります。
.Pp
.Fn popen
の引数は常に
.Xr sh 1
を呼び出し、
.Xr csh 1
は呼び出しません。
.Sh 歴史
.Fn popen
関数と
.Fn pclose
関数は、
.At v7
で登場しました。
.Pp
双方向機能は、
.Fx 2.2.6
で追加されました。