draft/man3/popen.3

   1 .\" Copyright 1991 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by the University of
  16 .\"     California, Berkeley and its contributors.
  17 .\" 4. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\" %%%LICENSE_END
  33 .\"
  34 .\"     @(#)popen.3     6.4 (Berkeley) 4/30/91
  35 .\"
  36 .\" Converted for Linux, Mon Nov 29 14:45:38 1993, faith@cs.unc.edu
  37 .\" Modified Sat May 18 20:37:44 1996 by Martin Schulze (joey@linux.de)
  38 .\" Modified 7 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
  39 .\"
  40 .\"*******************************************************************
  41 .\"
  42 .\" This file was generated with po4a. Translate the source file.
  43 .\"
  44 .\"*******************************************************************
  45 .TH POPEN 3 2013\-04\-19 GNU "Linux Programmer's Manual"
  46 .SH 名前
  47 popen, pclose \- プロセスとの入力/出力用のパイプストリーム
  48 .SH 書式
  49 .nf
  50 \fB#include <stdio.h>\fP
  51 .sp
  52 \fBFILE *popen(const char *\fP\fIcommand\fP\fB, const char *\fP\fItype\fP\fB);\fP
  53 .sp
  54 \fBint pclose(FILE *\fP\fIstream\fP\fB);\fP
  55 .fi
  56 .sp
  57 .in -4n
  58 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  59 .ad l
  60 .in
  61 .sp
  62 \fBpopen\fP(), \fBpclose\fP():
  63 .RS 4
  64 _POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE
  65 .RE
  66 .ad b
  67 .SH 説明
  68 \fBpopen\fP()  関数は、プロセスをオープンする。具体的には、 パイプを生成し、フォークを行い、シェルを起動する。
  69 定義から分かるように、パイプは一方向なので、 \fItype\fP 引き数には読み込みか書き込みのどちらか一方だけを指定できる (両方は指定できない)。
  70 生成されるストリームは、この指定に対応して、読み取り専用または 書き込み専用のいずれかとなる。
  71 .PP
  72 \fIcommand\fP 引き数は、シェルのコマンドラインを含む NULL 終端された文字列へのポインタである。 このコマンドは \fB\-c\fP フラグを用いて
  73 \fI/bin/sh\fP に渡される。 コマンドの解釈は (もし必要ならば) シェルによって行われる。 \fItype\fP 引き数は、NULL
  74 終端された文字列へのポインタで、 読み込みを示す文字 \(aqr\(aq か、書き込みを示す文字 \(aqw\(aq の
  75 どちらか一方を指定しなければならない。 glibc 2.9 以降では、この引き数に文字 \(aqe\(aq を追加で指定できる。 文字
  76 \(aqe\(aq を指定すると、 対応するファイルディスクリプタにおいて、 close\-on\-exec フラグ (\fBFD_CLOEXEC\fP)
  77 がセットされる。 これが役に立つ理由については、 \fBopen\fP(2)  の \fBO_CLOEXEC\fP フラグの説明を参照のこと。
  78 .PP
  79 \fBpopen\fP()  からの返り値は、通常の標準 I/O ストリームと同じであるが、 \fBfclose\fP(3)  ではなく \fBpclose\fP()
  80 で閉じなくてはならないことだけが異なる。 このストリームへ書き込んだ結果はコマンドの標準入力に書き込まれる。 そして、コマンドの標準出力は、
  81 コマンドそのものが置き換わってしまわない限り、 \fBpopen\fP()  を呼んだプロセスの標準出力と同じことになる。 逆に、"popened"
  82 (\fBpopen\fP()  によって開かれた) ストリームからの読み込みは、 そのコマンドの標準出力を読み込むことになる。
  83 そして、そのコマンドの標準入力は \fBpopen\fP()  を呼んだプロセスの標準入力と同一である。
  84 .PP
  85 デフォルトでは、 \fBpopen\fP()  の出力ストリームは完全にバッファリングされることに注意しよう。
  86 .PP
  87 \fBpclose\fP()  関数は、(パイプに) 関連づけられたプロセスが終了するのを待ち、 \fBwait4\fP(2)
  88 によって返されたコマンドの終了状態を返す。
  89 .SH 返り値
  90 \fBpopen\fP()  関数は、 \fBfork\fP(2)  または \fBpipe\fP(2)  呼び出しが失敗した場合や、 メモリ割り当てができなかった場合、
  91 NULL を返す。
  92 .PP
  93 .\" These conditions actually give undefined results, so I commented
  94 .\" them out.
  95 .\" .I stream
  96 .\" is not associated with a "popen()ed" command, if
  97 .\".I stream
  98 .\" already "pclose()d", or if
  99 \fBpclose\fP()  関数は、 \fBwait4\fP(2)  がエラーを返したり、何か他のエラーが見つかった場合、 \-1 を返す。 その場合、
 100 \fIerrno\fP にエラーの原因を示す値が設定される。
 101 .SH エラー
 102 \fBpopen\fP()  関数は、メモリアロケーションに失敗しても \fIerrno\fP をセットしない。 \fBpopen\fP()  が中で呼び出す
 103 \fBfork\fP(2)  や \fBpipe\fP(2)  が失敗した場合には、 \fIerrno\fP が適切にセットされる。 引き数 \fItype\fP
 104 が無効であり、この状態が検知された場合には、 \fIerrno\fP が \fBEINVAL\fP にセットされる。
 105 .PP
 106 \fBpclose\fP()  が、子プロセスの状態を取得できなかった場合、 \fIerrno\fP が \fBECHILD\fP にセットされる。
 107 .SH 準拠
 108 POSIX.1\-2001.
 109
 110 \fItype\fP に指定できる \(aqe\(aq は Linux での拡張である。
 111 .SH バグ
 112 読み込みのために開かれたコマンドの標準入力は \fBpopen\fP(), を呼んだプロセスと一緒に、その読み取り位置を共有する。
 113 そのため、もとのプロセスがバッファリングされた読み取りを終了したら、 そのコマンドの入力位置は予想されたものには なっていないかもしれない。
 114 同様に、書き込みのために開かれたコマンドからの出力は、 もとのプロセスの出力と混ざり合うことになるかもしれない。 後者は \fBpopen\fP()  の前に
 115 \fBfflush\fP(3)  を呼び出すことによって回避可能である。
 116 .PP
 117 .\" .SH HISTORY
 118 .\" A
 119 .\" .BR popen ()
 120 .\" and a
 121 .\" .BR pclose ()
 122 .\" function appeared in Version 7 AT&T UNIX.
 123 シェルの実行の失敗は、 シェルがコマンドの実行に失敗したことや、 コマンドがすぐに終了してしまったことと、区別がつかない。 唯一のヒントは終了状態が
 124 127 になることである。
 125 .SH 関連項目
 126 \fBsh\fP(1), \fBfork\fP(2), \fBpipe\fP(2), \fBwait4\fP(2), \fBfclose\fP(3), \fBfflush\fP(3),
 127 \fBfopen\fP(3), \fBstdio\fP(3), \fBsystem\fP(3)
 128 .SH この文書について
 129 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
 130 である。プロジェクトの説明とバグ報告に関する情報は
 131 http://www.kernel.org/doc/man\-pages/ に書かれている。