draft/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 .\"O .SH NAME
  46 .\"O popen, pclose \- pipe stream to or from a process
  47 .SH 名前
  48 popen, pclose \- プロセスとの入力/出力用のパイプ・ストリーム
  49 .\"O .SH SYNOPSIS
  50 .SH 書式
  51 .nf
  52 .B #include <stdio.h>
  53 .sp
  54 .BI "FILE *popen(const char *" command ", const char *" type );
  55 .sp
  56 .BI "int pclose(FILE *" stream );
  57 .fi
  58 .sp
  59 .in -4n
  60 .\"O Feature Test Macro Requirements for glibc (see
  61 .\"O .BR feature_test_macros (7)):
  62 glibc 向けの機能検査マクロの要件
  63 .RB ( feature_test_macros (7)
  64 参照):
  65 .ad l
  66 .in
  67 .sp
  68 .BR popen (),
  69 .BR pclose ():
  70 .RS 4
  71 _POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE
  72 .RE
  73 .ad b
  74 .\"O .SH DESCRIPTION
  75 .SH 説明
  76 .\"O The
  77 .\"O .BR popen ()
  78 .\"O function opens a process by creating a pipe, forking, and invoking the
  79 .\"O shell.
  80 .\"O Since a pipe is by definition unidirectional, the
  81 .\"O .I type
  82 .\"O argument may specify only reading or writing, not both; the resulting
  83 .\"O stream is correspondingly read-only or write-only.
  84 .BR popen ()
  85 関数は、プロセスをオープンする。具体的には、
  86 パイプを生成し、フォークを行い、シェルを起動する。
  87 定義から分かるように、パイプは一方向なので、
  88 .I type
  89 引き数には読み込みか書き込みのどちらか一方だけを指定できる
  90 (両方は指定できない)。
  91 生成されるストリームは、この指定に対応して、読み取り専用または
  92 書き込み専用のいずれかとなる。
  93 .PP
  94 .\"O The
  95 .\"O .I command
  96 .\"O argument is a pointer to a null-terminated string containing a shell
  97 .\"O command line.
  98 .\"O This command is passed to
  99 .\"O .I /bin/sh
 100 .\"O using the
 101 .\"O .B \-c
 102 .\"O flag; interpretation, if any, is performed by the shell.
 103 .\"O The
 104 .\"O .I type
 105 .\"O argument is a pointer to a null-terminated string which must contain
 106 .\"O either the letter \(aqr\(aq for reading or the letter \(aqw\(aq for writing.
 107 .I command
 108 引き数は、シェルのコマンドラインを含む
 109 NULL 終端された文字列へのポインタである。
 110 このコマンドは
 111 .B \-c
 112 フラグを用いて
 113 .I /bin/sh
 114 に渡される。
 115 コマンドの解釈は (もし必要ならば) シェルによって行われる。
 116 .I type
 117 引き数は、NULL 終端された文字列へのポインタで、
 118 読み込みを示す文字 \(aqr\(aq か、書き込みを示す文字 \(aqw\(aq の
 119 どちらか一方を指定しなければならない。
 120 .\"O Since glibc 2.9,
 121 .\"O this argument can additionally include the letter \(aqe\(aq,
 122 .\"O which causes the close-on-exec flag
 123 .\"O .RB ( FD_CLOEXEC )
 124 .\"O to be set on the underlying file descriptor;
 125 .\"O see the description of the
 126 .\"O .B O_CLOEXEC
 127 .\"O flag in
 128 .\"O .BR open (2)
 129 .\"O for reasons why this may be useful.
 130 glibc 2.9 以降では、この引き数に文字 \(aqe\(aq を追加で指定できる。
 131 文字 \(aqe\(aq を指定すると、
 132 対応するファイルディスクリプタにおいて、
 133 close-on-exec フラグ
 134 .RB ( FD_CLOEXEC )
 135 がセットされる。
 136 これが役に立つ理由については、
 137 .BR open (2)
 138 の
 139 .B O_CLOEXEC
 140 フラグの説明を参照のこと。
 141 .PP
 142 .\"O The return value from
 143 .\"O .BR popen ()
 144 .\"O is a normal standard I/O stream in all respects save that it must be closed
 145 .\"O with
 146 .\"O .BR pclose ()
 147 .\"O rather than
 148 .\"O .BR fclose (3).
 149 .BR popen ()
 150 からの返り値は、通常の標準 I/O ストリームと同じであるが、
 151 .BR fclose (3)
 152 ではなく
 153 .BR pclose ()
 154 で閉じなくてはならないことだけが異なる。
 155 .\"O Writing to such a stream writes to the standard input of the command; the
 156 .\"O command's standard output is the same as that of the process that called
 157 .\"O .BR popen (),
 158 .\"O unless this is altered by the command itself.
 159 .\"O Conversely, reading from a
 160 .\"O "popened" stream reads the command's standard output, and the command's
 161 .\"O standard input is the same as that of the process that called
 162 .\"O .BR popen ().
 163 このストリームへ書き込んだ結果はコマンドの標準入力に書き込まれる。
 164 そして、コマンドの標準出力は、
 165 コマンドそのものが置き換わってしまわない限り、
 166 .BR popen ()
 167 を呼んだプロセスの標準出力と同じことになる。
 168 逆に、"popened"
 169 .RB ( popen ()
 170 によって開かれた) ストリームからの読み込みは、
 171 そのコマンドの標準出力を読み込むことになる。
 172 そして、そのコマンドの標準入力は
 173 .BR popen ()
 174 を呼んだプロセスの標準入力と同一である。
 175 .PP
 176 .\"O Note that output
 177 .\"O .BR popen ()
 178 .\"O streams are fully buffered by default.
 179 デフォルトでは、
 180 .BR popen ()
 181 の出力ストリームは完全にバッファリングされることに注意しよう。
 182 .PP
 183 .\"O The
 184 .\"O .BR pclose ()
 185 .\"O function waits for the associated process to terminate and returns the exit
 186 .\"O status of the command as returned by
 187 .\"O .BR wait4 (2).
 188 .BR pclose ()
 189 関数は、(パイプに) 関連づけられたプロセスが終了するのを待ち、
 190 .BR wait4 (2)
 191 によって返されたコマンドの終了状態を返す。
 192 .\"O .SH "RETURN VALUE"
 193 .SH 返り値
 194 .\"O The
 195 .\"O .BR popen ()
 196 .\"O function returns NULL if the
 197 .\"O .BR fork (2)
 198 .\"O or
 199 .\"O .BR pipe (2)
 200 .\"O calls fail, or if it cannot allocate memory.
 201 .BR popen ()
 202 関数は、
 203 .BR fork (2)
 204 または
 205 .BR pipe (2)
 206 呼び出しが失敗した場合や、
 207 メモリ割り当てができなかった場合、 NULL を返す。
 208 .PP
 209 .\"O The
 210 .\"O .BR pclose ()
 211 .\"O function returns \-1 if
 212 .\"O .\" These conditions actually give undefined results, so I commented
 213 .\"O .\" them out.
 214 .\"O .\" .I stream
 215 .\"O .\" is not associated with a "popen()ed" command, if
 216 .\"O .\".I stream
 217 .\"O .\" already "pclose()d", or if
 218 .\"O .BR wait4 (2)
 219 .\"O returns an error, or some other error is detected.
 220 .BR pclose ()
 221 関数は、
 222 .BR wait4 (2)
 223 がエラーを返したり、何か他のエラーが見つかった場合、
 224 \-1 を返す。
 225 .\"O .SH ERRORS
 226 .SH エラー
 227 .\"O The
 228 .\"O .BR popen ()
 229 .\"O function does not set
 230 .\"O .I errno
 231 .\"O if memory allocation fails.
 232 .\"O If the underlying
 233 .\"O .BR fork (2)
 234 .\"O or
 235 .\"O .BR pipe (2)
 236 .\"O fails,
 237 .\"O .I errno
 238 .\"O is set appropriately.
 239 .\"O If the
 240 .\"O .I type
 241 .\"O argument is invalid, and this condition is detected,
 242 .\"O .I errno
 243 .\"O is set to
 244 .\"O .BR EINVAL .
 245 .BR popen ()
 246 関数は、メモリアロケーションに失敗しても
 247 .I errno
 248 をセットしない。
 249 .BR popen ()
 250 が中で呼び出す
 251 .BR fork (2)
 252 や
 253 .BR pipe (2)
 254 が失敗した場合には、
 255 .I errno
 256 が適切にセットされる。
 257 引き数
 258 .I type
 259 が無効であり、この状態が検知された場合には、
 260 .I errno
 261 が
 262 .B EINVAL
 263 にセットされる。
 264 .PP
 265 .\"O If
 266 .\"O .BR pclose ()
 267 .\"O cannot obtain the child status,
 268 .\"O .I errno
 269 .\"O is set to
 270 .\"O .BR ECHILD .
 271 .BR pclose ()
 272 が、子プロセスの状態を取得できなかった場合、
 273 .I errno
 274 が
 275 .B ECHILD
 276 にセットされる。
 277 .\"O .SH "CONFORMING TO"
 278 .SH 準拠
 279 POSIX.1-2001.
 280
 281 .\"O The \(aqe\(aq value for
 282 .\"O .I type
 283 .\"O is a Linux extension.
 284 .I type
 285 に指定できる \(aqe\(aq は Linux での拡張である。
 286 .\"O .SH BUGS
 287 .SH バグ
 288 .\"O Since the standard input of a command opened for reading shares its seek
 289 .\"O offset with the process that called
 290 .\"O .BR popen (),
 291 .\"O if the original process has done a buffered read, the command's input
 292 .\"O position may not be as expected.
 293 .\"O Similarly, the output from a command
 294 .\"O opened for writing may become intermingled with that of the original
 295 .\"O process.
 296 .\"O The latter can be avoided by calling
 297 .\"O .BR fflush (3)
 298 .\"O before
 299 .\"O .BR popen ().
 300 読み込みのために開かれたコマンドの標準入力は
 301 .BR popen (),
 302 を呼んだプロセスと一緒に、その読み取り位置を共有する。
 303 そのため、もとのプロセスがバッファリングされた読み取りを終了したら、
 304 そのコマンドの入力位置は予想されたものには
 305 なっていないかもしれない。
 306 同様に、書き込みのために開かれたコマンドからの出力は、
 307 もとのプロセスの出力と混ざり合うことになるかもしれない。
 308 後者は
 309 .BR popen ()
 310 の前に
 311 .BR fflush (3)
 312 を呼び出すことによって回避可能である。
 313 .PP
 314 .\"O Failure to execute the shell is indistinguishable from the shell's failure
 315 .\"O to execute command, or an immediate exit of the command.
 316 .\"O The only hint is an exit status of 127.
 317 シェルの実行の失敗は、
 318 シェルがコマンドの実行に失敗したことや、
 319 コマンドがすぐに終了してしまったことと、区別がつかない。
 320 唯一のヒントは終了状態が 127 になることである。
 321 .\"O .\" .SH HISTORY
 322 .\" .SH 履歴
 323 .\"O .\" A
 324 .\"O .\" .BR popen ()
 325 .\"O .\" and a
 326 .\"O .\" .BR pclose ()
 327 .\"O .\" function appeared in Version 7 AT&T UNIX.
 328 .\" .BR popen ()
 329 .\" 関数と
 330 .\" .BR pclose ()
 331 .\" 関数は AT&T UNIX の Version 7 から導入された。
 332 .\"O .SH "SEE ALSO"
 333 .SH 関連項目
 334 .BR sh (1),
 335 .BR fork (2),
 336 .BR pipe (2),
 337 .BR wait4 (2),
 338 .BR fclose (3),
 339 .BR fflush (3),
 340 .BR fopen (3),
 341 .BR stdio (3),
 342 .BR system (3)