release/man3/popen.3

   1 .\" Copyright 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)popen.3     6.4 (Berkeley) 4/30/91
  33 .\"
  34 .\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu
  35 .\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de)
  36 .\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
  37 .\"
  38 .\" Japanese Version Copyright (c) 1997 Takashi Yoshino
  39 .\"       all rights reserved.
  40 .\" Translated 1997-01-21, Takashi Yoshino <tyoshino@eng.toyo.ac.jp>
  41 .\" Modified 2007-05-03, Akihiro MOTOKI
  42 .\" Modified 2008-11-09, Akihiro MOTOKI, LDP v3.13
  43 .\"
  44 .TH POPEN 3  2010-02-03 "GNU" "Linux Programmer's Manual"
  45 .SH 名前
  46 popen, pclose \- プロセスとの入力/出力用のパイプ・ストリーム
  47 .SH 書式
  48 .nf
  49 .B #include <stdio.h>
  50 .sp
  51 .BI "FILE *popen(const char *" command ", const char *" type );
  52 .sp
  53 .BI "int pclose(FILE *" stream );
  54 .fi
  55 .sp
  56 .in -4n
  57 glibc 向けの機能検査マクロの要件
  58 .RB ( feature_test_macros (7)
  59 参照):
  60 .ad l
  61 .in
  62 .sp
  63 .BR popen (),
  64 .BR pclose ():
  65 .RS 4
  66 _POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE
  67 .RE
  68 .ad b
  69 .SH 説明
  70 .BR popen ()
  71 関数は、プロセスをオープンする。具体的には、
  72 パイプを生成し、フォークを行い、シェルを起動する。
  73 定義から分かるように、パイプは一方向なので、
  74 .I type
  75 引き数には読み込みか書き込みのどちらか一方だけを指定できる
  76 (両方は指定できない)。
  77 生成されるストリームは、この指定に対応して、読み取り専用または
  78 書き込み専用のいずれかとなる。
  79 .PP
  80 .I command
  81 引き数は、シェルのコマンドラインを含む
  82 NULL 終端された文字列へのポインタである。
  83 このコマンドは
  84 .B \-c
  85 フラグを用いて
  86 .I /bin/sh
  87 に渡される。
  88 コマンドの解釈は (もし必要ならば) シェルによって行われる。
  89 .I type
  90 引き数は、NULL 終端された文字列へのポインタで、
  91 読み込みを示す文字 \(aqr\(aq か、書き込みを示す文字 \(aqw\(aq の
  92 どちらか一方を指定しなければならない。
  93 glibc 2.9 以降では、この引き数に文字 \(aqe\(aq を追加で指定できる。
  94 文字 \(aqe\(aq を指定すると、
  95 対応するファイルディスクリプタにおいて、
  96 close-on-exec フラグ
  97 .RB ( FD_CLOEXEC )
  98 がセットされる。
  99 これが役に立つ理由については、
 100 .BR open (2)
 101 の
 102 .B O_CLOEXEC
 103 フラグの説明を参照のこと。
 104 .PP
 105 .BR popen ()
 106 からの返り値は、通常の標準 I/O ストリームと同じであるが、
 107 .BR fclose (3)
 108 ではなく
 109 .BR pclose ()
 110 で閉じなくてはならないことだけが異なる。
 111 このストリームへ書き込んだ結果はコマンドの標準入力に書き込まれる。
 112 そして、コマンドの標準出力は、
 113 コマンドそのものが置き換わってしまわない限り、
 114 .BR popen ()
 115 を呼んだプロセスの標準出力と同じことになる。
 116 逆に、"popened"
 117 .RB ( popen ()
 118 によって開かれた) ストリームからの読み込みは、
 119 そのコマンドの標準出力を読み込むことになる。
 120 そして、そのコマンドの標準入力は
 121 .BR popen ()
 122 を呼んだプロセスの標準入力と同一である。
 123 .PP
 124 デフォルトでは、
 125 .BR popen ()
 126 の出力ストリームは完全にバッファリングされることに注意しよう。
 127 .PP
 128 .BR pclose ()
 129 関数は、(パイプに) 関連づけられたプロセスが終了するのを待ち、
 130 .BR wait4 (2)
 131 によって返されたコマンドの終了状態を返す。
 132 .SH 返り値
 133 .BR popen ()
 134 関数は、
 135 .BR fork (2)
 136 または
 137 .BR pipe (2)
 138 呼び出しが失敗した場合や、
 139 メモリ割り当てができなかった場合、 NULL を返す。
 140 .PP
 141 .BR pclose ()
 142 関数は、
 143 .BR wait4 (2)
 144 がエラーを返したり、何か他のエラーが見つかった場合、
 145 \-1 を返す。
 146 .SH エラー
 147 .BR popen ()
 148 関数は、メモリアロケーションに失敗しても
 149 .I errno
 150 をセットしない。
 151 .BR popen ()
 152 が中で呼び出す
 153 .BR fork (2)
 154 や
 155 .BR pipe (2)
 156 が失敗した場合には、
 157 .I errno
 158 が適切にセットされる。
 159 引き数
 160 .I type
 161 が無効であり、この状態が検知された場合には、
 162 .I errno
 163 が
 164 .B EINVAL
 165 にセットされる。
 166 .PP
 167 .BR pclose ()
 168 が、子プロセスの状態を取得できなかった場合、
 169 .I errno
 170 が
 171 .B ECHILD
 172 にセットされる。
 173 .SH 準拠
 174 POSIX.1-2001.
 175
 176 .I type
 177 に指定できる \(aqe\(aq は Linux での拡張である。
 178 .SH バグ
 179 読み込みのために開かれたコマンドの標準入力は
 180 .BR popen (),
 181 を呼んだプロセスと一緒に、その読み取り位置を共有する。
 182 そのため、もとのプロセスがバッファリングされた読み取りを終了したら、
 183 そのコマンドの入力位置は予想されたものには
 184 なっていないかもしれない。
 185 同様に、書き込みのために開かれたコマンドからの出力は、
 186 もとのプロセスの出力と混ざり合うことになるかもしれない。
 187 後者は
 188 .BR popen ()
 189 の前に
 190 .BR fflush (3)
 191 を呼び出すことによって回避可能である。
 192 .PP
 193 シェルの実行の失敗は、
 194 シェルがコマンドの実行に失敗したことや、
 195 コマンドがすぐに終了してしまったことと、区別がつかない。
 196 唯一のヒントは終了状態が 127 になることである。
 197 .\" .SH 履歴
 198 .\" .BR popen ()
 199 .\" 関数と
 200 .\" .BR pclose ()
 201 .\" 関数は AT&T UNIX の Version 7 から導入された。
 202 .SH 関連項目
 203 .BR sh (1),
 204 .BR fork (2),
 205 .BR pipe (2),
 206 .BR wait4 (2),
 207 .BR fclose (3),
 208 .BR fflush (3),
 209 .BR fopen (3),
 210 .BR stdio (3),
 211 .BR system (3)