perlfaq8 - システムとの相互作用
FAQ のこのセクションでは、オペレーティングシステムとの対話に関する質問を 扱っています。 これにはプロセス間(IPC)、ユーザーインターフェース (キーボード、スクリーン、ポインティングデバイス)の制御、 その他データ操作に関連しないほとんどの事柄を含みます。
あなたの使っているオペレーティングシステム向けの移植について特有のことは、 それに関する FAQ とドキュメント(perlvms, perlplan9 など)を 読んでください。 そこには、あなたの使う perl についてのより詳しい情報があります。
$^O
という変数(use Engish
をしていれば $OSNAME
)は、あなたの使っている perl の実行ファイルがビルドされたオペレーションシステムの名前 (リリース番号ではありません)の情報を持っています。
(brian d foy によって寄贈されました)
exec
関数の仕事は、あなたのプロセスを他のコマンドに切り替えて、 決して帰ってこないことです。 もしこれがあなたのしたいことでないなら、exec
を使わないでください。 :)
もし外部コマンドを実行して、かつ Perl プロセスを実行したままにしたい場合は、 パイプ付きの open
, fork
, system
のいずれかを見てください。
キーボード、画面、ポインティングデバイス(“マウス”)にアクセスしたり それを制御することはシステム依存です。 以下のモジュールを試してみてください:
Term::Cap Standard perl distribution
Term::ReadKey CPAN
Term::ReadLine::Gnu CPAN
Term::ReadLine::Perl CPAN
Term::Screen CPAN
Term::Cap Standard perl distribution
Curses CPAN
Term::ANSIColor CPAN
Tk CPAN
これらの一部の特殊なケースは、このセクションの他の回答の例として 示されています。
一般的にはできません。 なぜなら、あなたはディスプレイデバイスに関するレシピについて 何も知らないからです。 もしあなたがカラーの扱える ANSI ターミナルについて知っているのなら、 CPAN にある Term::ANSIColor
モジュールを使うことができます。
use Term::ANSIColor;
print color("red"), "Stop!\n", color("reset");
print color("green"), "Go!\n", color("reset");
あるいは次のようにも書けます:
use Term::ANSIColor qw(:constants);
print RED, "Stop!\n", RESET;
print GREEN, "Go!\n", RESET;
入力バッファを制御するのは非常にシステムに依存したやりかたです。 多くのシステムでは、"getc" in perlfunc にあるように stty コマンドを使うことができますが、今書いた通り 移植性の問題があるのです。
open(TTY, "+</dev/tty") or die "no tty: $!";
system "stty cbreak </dev/tty >/dev/tty 2>&1";
$key = getc(TTY); # perhaps this works
# OR ELSE
sysread(TTY, $key, 1); # probably this does
system "stty -cbreak </dev/tty >/dev/tty 2>&1";
CPAN にある Term::ReadKey
モジュールは、stty をキー毎にシェルに 送るよりもより効果的に行ってくれて使うのが簡単なインターフェースを 提供します。 このモジュールは限定的ながら Windows にも対応しています。
use Term::ReadKey;
ReadMode('cbreak');
$key = ReadKey(0);
ReadMode('normal');
しかし、このコードを使うには C コンパイラを使えることが条件であり、かつ CPAN モジュールのビルドとインストールができなければなりません。 以下の例は、標準の POSIX
モジュールを使った解決策で、 あなたの使っているシステムが POSIX をサポートしていれば 即使えるものです。
use HotKey;
$key = readkey();
そして以下の例は、HotKey
モジュールを使ったものです。 この HotKey モジュールは POSIX の termio 構造体の操作を包み隠します。
# HotKey.pm
package HotKey;
@ISA = qw(Exporter);
@EXPORT = qw(cbreak cooked readkey);
use strict;
use POSIX qw(:termios_h);
my ($term, $oterm, $echo, $noecho, $fd_stdin);
$fd_stdin = fileno(STDIN);
$term = POSIX::Termios->new();
$term->getattr($fd_stdin);
$oterm = $term->getlflag();
$echo = ECHO | ECHOK | ICANON;
$noecho = $oterm & ~$echo;
sub cbreak {
$term->setlflag($noecho); # ok, so i don't want echo either
$term->setcc(VTIME, 1);
$term->setattr($fd_stdin, TCSANOW);
}
sub cooked {
$term->setlflag($oterm);
$term->setcc(VTIME, 0);
$term->setattr($fd_stdin, TCSANOW);
}
sub readkey {
my $key = '';
cbreak();
sysread(STDIN, $key, 1);
cooked();
return $key;
}
END { cooked() }
1;
最も簡単な方法は、CPAN にある Term::ReadKey
に対して (ブロックを行わないという意味である)-1 を引数に渡して 使用することによって非ブロックモードでキーを読み取るという方法です。
use Term::ReadKey;
ReadMode('cbreak');
if (defined ($char = ReadKey(-1)) ) {
# input was waiting and it was $char
} else {
# no input was waiting
}
ReadMode('normal'); # restore normal tty settings
(brian d foy によって寄贈されました)
画面をクリアするには、端末に画面をクリアするように伝える特殊な シーケンスを表示するだけです。 このシーケンスが分かれば、画面をクリアしたいときにこれを出力します。
この特殊なシーケンスを得るためには Term::ANSIScreen
モジュールが 使えます。 cls
関数 (あるいは :screen
タグ) をインポートします:
use Term::ANSIScreen qw(cls);
my $clear_screen = cls();
print $clear_screen;
端末制御のための低レベルな詳細を扱いたいなら、 Term::Cap
から特殊シーケンスを得られます。 Tputs
メソッドは、与えられた能力のための文字列を返します:
use Term::Cap;
$terminal = Term::Cap->Tgetent( { OSPEED => 9600 } );
$clear_string = $terminal->Tputs('cl');
print $clear_screen;
Windows では、Win32::Console
モジュールが使えます。 影響を与えたい出力ファイルハンドルのオブジェクトを作った後、 Cls
メソッドを呼び出します:
Win32::Console;
$OUT = Win32::Console->new(STD_OUTPUT_HANDLE);
my $clear_string = $OUT->Cls;
print $clear_screen;
もしこの処理を行うコマンドラインプログラムがあるなら、そのプログラムが 出力するものを得るために逆クォートで呼び出して、後でそれを使うことも できます:
$clear_string = `clear`;
print $clear_string;
CPAN にある Term::ReadKey
モジュールをインストールしているのなら、 文字やピクセルでの幅と高さを得ることができます:
use Term::ReadKey;
($wchar, $hchar, $wpixels, $hpixels) = GetTerminalSize();
以下の例は生の ioctl
よりも移植性がありますが、 あまりわかりやすい例ではありません:
require 'sys/ioctl.ph';
die "no TIOCGWINSZ " unless defined &TIOCGWINSZ;
open(TTY, "+</dev/tty") or die "No tty: $!";
unless (ioctl(TTY, &TIOCGWINSZ, $winsize='')) {
die sprintf "$0: ioctl TIOCGWINSZ (%08x: $!)\n", &TIOCGWINSZ;
}
($row, $col, $xpixel, $ypixel) = unpack('S4', $winsize);
print "(row,col) = ($row,$col)";
print " (xpixel,ypixel) = ($xpixel,$ypixel)" if $xpixel || $ypixel;
print "\n";
(この質問は web とは関係ありません。 それに関しては 別の FAQ を参照してください。)
この例が "crypt" in perlfunc にあります。 第一に、端末を“no echo”モードにし、それから通常通りにパスワードを 読み込みます。 これを、古いスタイルの ioctl()
関数を使ってできますし、あるいは POSIX の端末制御(POSIX と、らくだ本を参照してください)を使うことも、 stty プログラムを呼び出すことも可能です(ただしこれは移植性は劣ります)。
あるいはほとんどのシステムで、CPAN にある Term::ReadKey
を使って 行うこともできます。 これは使うのが簡単で、理論的にはより移植性があります。
use Term::ReadKey;
ReadMode('noecho');
$password = ReadLine(0);
これはプログラムを実行するオペレーティングシステムに依存します。 UNIX の場合、シリアルポートは /dev にあるファイルを通じてアクセスが 可能です。 他のシステムでは、デバイス名は異なったものであることでしょう。 全てのデバイス操作に共通の問題点として以下のものが挙げられます:
あなたの使っているシステムは、多重アクセスを制御するためにロック ファイルを使用しているかもしれません。 正しい手順に従うようにしてください。 予測のつかない振る舞いは一つのデバイスに対する複数のプロセスの読み出しが 原因かもしれません。
一つのデバイスに対して、読み込みと書き出しの両方の操作ができることを 期待しているのなら、それを更新モード(詳しくは "open" in perlfunc を 参照)でオープンする必要があるでしょう。 sysopen()
と Fcntl
モジュールにある O_RDWR|O_NDELAY|O_NOCTTY
とを使って ブロッキングする危険性なしにオープンを実行したいと考えるかもしれません。 このアプローチに関する詳細は "sysopen" in perlfunc を参照してください。
幾つかのデバイスでは、行の終端に "\n" ではなく "\r" を期待しています。 perl の移植の一部では、"\r" と "\n" は通常の(UNIX の) ASCII 値である "\015" と "\012" とは異なったものになっています。 八進表記 ("\015") や十六進表記("0x0D")、 あるいは制御文字指定 ("\cM") を使って 直接数値を与える必要があるかもしれません。
print DEV "atv1\012"; # 一部のデバイスにとっては間違い
print DEV "atv1\015"; # 一部のデバイスにとっては正しい
通常のテキストファイルでさえも、"\n" はいたずらを行う可能性があります。 全ての行 を "\015\012" で終わらせ、出力から必要のないものを 取り除くということを除いては、UNIX、DOS/Win、Macintosh との間で 互換性のある行の終端方法は未だに統一されていません。 これは特にソケットの入出力や自動フラッシュで適用されます。 これについては次に述べます。
デバイスに print()
した時にそのキャラクタが反映されるようにしたいのなら、 そのハンドルを自動フラッシュするようにしたいでしょう。 自動フラッシュを制御するのに、$|
という変数と、select()
を 使うことができます("$|" in perlvarと"select" in perlfunc または perlfaq5 の "How do I flush/unbuffer an output filehandle? Why must I do this?" を参照してください)。
$oldh = select(DEV);
$| = 1;
select($oldh);
以下のように、これを一時変数を使わないで行うコードを見るかもしれません:
select((select(DEV), $| = 1)[0]);
$|
というような変数に戸惑いを感じていて、数千行のプログラムを 引っ張りこむことを気にしないのなら以下のようにできます:
use IO::Handle;
DEV->autoflush(1);
先のアイテムで述べたように、これでもまだ UNIX と Macintosh の間で ソケット I/O を使った場合にはうまく動作しません。 その場合には、行の終端をハードコーディングする必要があるでしょう。
ブロッキング read()
やブロッキング sysread()
を行うのであれば、 タイムアウトを実現するためにalarmハンドラーをアレンジする必要があるでしょう ("alarm" in perlfunc を参照)。 もしノンブロッキング open を持っているのであれば、デバイスが入出力完了の 状態であるかどうかを決定するために四つの引数を取る select()
を使う必要が あるであろうノンブロッキング read も同様に持っていることでしょう ("select" in perlfuncを参照)。
caller-id ボックスから読み出すことに挑戦したことで有名な Jamie Zawinski <jwd@netscape.com>
は、 sysread
や sysopen
、POSIX の tcgetattr
その他さまざまな関数を扱い 悪戦苦闘しながら、最終的には以下のようものを作りました:
sub open_modem {
use IPC::Open2;
my $stty = `/bin/stty -g`;
open2( \*MODEM_IN, \*MODEM_OUT, "cu -l$modem_device -s2400 2>&1");
# starting cu hoses /dev/tty's stty settings, even when it has
# been opened on a pipe...
system("/bin/stty $stty");
$_ = <MODEM_IN>;
chomp;
if ( !m/^Connected/ ) {
print STDERR "$0: cu printed `$_' instead of `Connected'\n";
}
}
特別なハードウェアに非常に多額のお金を掛けてください; しかしこれはあなたが何について話しているかによります。
まじめな話をすると、UNIX のパスワードに対してのものならできません -- UNIX のパスワードシステムは一方向の暗号化を採用しています。 それは暗号化というよりはむしろハッシュ化といえるものです。 あなたがチェックできる最善の方法は、同じ文字列に対する ハッシュかどうかを調べることです。 Crack のようなプログラムは考えられるパスワードを力づくで(そして知的に) 試しますが、即座に成功するものを生成することはしません(できません)。
もしあなたが、ユーザーが悪いパスワードを選択してしまうことを 心配しているのであれば、ユーザーが(たとえば passwd(1) を使って)自分の パスワードを変更しようとしたときに積極的にチェックをすべきでしょう。
(brian d foy によって寄贈されました)
バックグラウンドでコードを実行するための単一の方法というのはないので、 あなたのプログラムが他のアスクに移動する前に終わるのを待つ必要は ありません。 プロセス管理は使用するオペレーティングシステムに依存していて、 多くのテクニックは perlipc にあります。
IPC::Open2
, IPC::Open3
, IPC::Run
, Parallel::Jobs
, Parallel::ForkManager
, POE
, Proc::Background
, Win32::Process
といった CPAN モジュールが助けになるでしょう。 その他にも使えるかもしれない多くのモジュールがありますので、 これらの名前空間をチェックしてみてください。
Unix 風のシステムを使っているなら、コマンドの最後に &
を置くことで システムコールから切り離すことができるかもしれません:
system("cmd &")
perlfunc に記述されているように、fork
を使うこともできます (しかしこれは多くのモジュールがやってくれるのと同じことです)。
主プロセスとバックグラウンドプロセス(子プロセス)で同じ STDIN, STDOUT, STDERR のファイルハンドルが共有されます。 両方のプロセスが同時にアクセスしようとすると、 おかしな事が発生するかもしれません。 子プロセス用のこれらのハンドルを、クローズしたり再オープンしたり したくなるかもしれません。 これは、パイプを open
することで行えますが、 一部のシステムにおいてはこれは子プロセスが親プロセスよりも 長生きすることはできないということになります。
SIGCHLD シグナルを捕捉する必要があり、可能なら SIGPIPE も 捕捉する必要があるでしょう。 SIGCHLD はバックグラウンドプロセスが終了したときに送られます。 SIGPIPE は既にクローズされている子プロセスを所有するファイルハンドルに 書き込みを行ったときに送られます(トラップされていない SIGPIPE は、 あなたのプログラムを黙って終わらせてしまうかもしれません)。 これは system("cmd&")
を使ったときには起こりません。
子プロセスが終了したときにそれを“刈り取る”(reap) 準備をする必要があります。
$SIG{CHLD} = sub { wait };
$SIG{CHLD} = 'IGNORE';
2 重 fork も使えます。 あなたは直ちに最初の子に対して wait()
し、init デーモンは孫が終了するのを wait()
します。
unless ($pid = fork) {
unless (fork) {
exec "what you really wanna do";
die "exec failed!";
}
exit 0;
}
waitpid($pid, 0);
これを行うサンプルは "Signals" in perlipc を参照してください。 ゾンビは system("prog &")
を使ったときには発生しません。
実際には制御文字を“トラップ”できません。 その代わりに、その文字が生成して 端末のフォアグラウンドプロセスに送られることになる シグナルがトラップできます。 シグナルは "Signals" in perlipc とらくだ本の "Signal" の章に 説明があります。
%SIG
ハッシュにシグナルを扱いたい関数をセットできます。 perl がシグナルを捕捉した後、perl はシグナルと同じ名前をキーとして %SIG
を 見て、そのキーの値であるサブルーチンを呼び出します。
# as an anonymous subroutine
$SIG{INT} = sub { syswrite(STDERR, "ouch\n", 5 ) };
# or a reference to a function
$SIG{INT} = \&ouch;
# or the name of the function as a string
$SIG{INT} = "ouch";
バージョン 5.8 より前の Perl には、シグナルを受け取って、可能なら %SIG
にセットされている Perl の関数を実行する C ソースコードのシグナルハンドラが ありました。 これはこのレベルでのシグナルハンドリングのルールに違反していて、perl の コアダンプを引き起こしていました。 バージョン 5.8.0 から、perl はシグナルを捕捉している間ではなく、シグナルを 捕捉した 後に %SIG
を見ます。 この答えの以前のバージョンは間違っていました。
perl が正しくインストールされていて、かつ、シャドウライブラリが きちんとインストールされていれば、perlfunc で説明されている getpw*()
関数がシャドウパスワードファイルに対する(リードオンリーの) アクセスを提供しています。 ファイルを変更するには、新たなシャドウパスワードファイルを作成して (フォーマットはシステム毎に異なります--詳しくは passwd を参照してください)、pwd_mkdb(8)
を使ってそれをインストールします (詳細は pwd_mkdb を参照のこと)。
あなたが十分な権限を持っているとすれば、date(1)
プログラムを実行すれば システム全体の日付や時刻を設定できるはずです (プロセス毎に日付や時刻を設定する方法はありません)。 この機構は、UNIX、MS-DOS、Windows、NT でうまくいくでしょう。 VMS には等価な set time
があります。
あなたのやりたいことがタイムゾーンの変更であるのなら、 環境変数を変更することでそれができるでしょう。
$ENV{TZ} = "MST7MDT"; # Unixish
$ENV{'SYS$TIMEZONE_DIFFERENTIAL'}="-5" # vms
system "trn comp.lang.perl.misc";
sleep()
関数が一秒未満の単位での動作をサポートすることを求めているのなら、 "select" in perlfunc にあるように、select()
を使うのが最も単純な方法です。 Time::Hires
と BSD::Itimer
モジュール(CPAN から利用可能ですし、 Perl 5.8 からは Time::HiRes
は標準配布の一部です)も 試してみてください。
(brian d foy によって寄贈されました)
(Perl 5.8 から標準配布の一部である) Time::HiRes
モジュールは、 紀元からのマイクロ秒を返す gettimeofday()
システムコールを使って時間を 計測します。 もし古い Perl を使っていて Time::HiRes
をインストールできず、 Unixish を使っているなら、gettimeofday(2)
を直接使えます。 "syscall" in perlfunc を参照してください。
atexit()
をシミュレートするのに END
ブロックが使えます。 それぞれのパッケージの END
ブロックは、プログラムやスレッドの終了時に 呼び出されます。 END
ブロックに関するさらなる詳細については perlmod を 参照してください。
例を挙げると、あなたのフィルタープログラムが出力を確実に ディスクに送るようにするためには以下のようにできます:
END {
close(STDOUT) || die "stdout close failed: $!";
}
END
ブロックは、トラップされないシグナルが プログラムを強制終了させた場合には呼び出されません。 したがって、END
ブロックを使う場合には同時に以下のようにするべきです:
use sigtrap qw(die normal-signals);
Perl の例外処理機構は eval()
演算子です。 setjmp
として eval()
を、longjmp
として die()
を使うことができます。 これに関する詳細は、シグナルに関するセクション、 特に "Signals" in perlipc にあるブロッキング flock()
のための タイムアウトハンドラーと、 Programming Perl の "Signal" の章を参照してください。
例外処理そのものに興味があるのなら、Try::Tiny
のような、例外を 扱うための多くの CPAN モジュールの一つを使ってください。
atexit()
構文(と、rmexit()
) が欲しいのなら、CPAN にある AtExit
モジュールを試してみてください。
一部の System 5 ベースのシステム、特に Solaris 2.x では標準のソケット定数の 幾つかが再定義されています。 これらの定数は全てのアーキテクチャに渡るものであったので、 しばしば perl コードにハードコーディングされています。 これに対処する適切な方法は正しい値を得るために "use Socket" とすることです。
SunOS と Solaris とではバイナリ互換性があるにも関らず、 これらの値が異なるということに注意してください。 不思議なことです。
ほとんどの場合、その方法は外部モジュールを作るというものです -- "Where can I learn about linking C with Perl? [h2xs, xsubpp]" の回答を参照してください。 ただし、その関数がシステムコールでありあなたの使っているシステムが syscall()
をサポートしているのであれば、 syscall
関数(perlfunc に説明があります)を使うことができます。
一緒に配布されたモジュールや CPAN にあるモジュールをチェックすることを 忘れないでください--誰かが求めるモジュールを既に作っているかもしれません。 Windows では、Win32::API
を試してください。 Mac では、Mac::Carbon
を試してください。 C 関数へのインターフェースを持つモジュールがなければ、 Inline::C
を使って Perl のソースコードにちょっとした C のコードを インライン化できます。
伝統的に、これらのファイルは標準配布に含まれる h2ph
というツールによって 生成されるものです。 このプログラムは C のヘッダーファイルにある cpp(1)
指示子を &SYS_getitimer
のような、関数に対する引数として使うことのできる サブルーチン定義を含むファイルに変換するものです。 これは完璧なものではありませんが、ほとんどの場合には十分な仕事を行います。 errno.h, syscall.h, socket.h のような単純なファイルはよいのですが、 ioctl.h のように難しいものはほとんど常に手で編集する必要があります。 以下の手順は、*.ph ファイルをインストールするためのものです。
1. become super-user
2. cd /usr/include
3. h2ph *.h */*.h
あなたの使っているシステムが動的ローディングをサポートしているのであれば、 移植性と健全性(sanity)のために、h2xs
を使うべきでしょう (これも標準の perl 配布キットに含まれています)。 このツールは、C のヘッダーファイルを Perl のエクステンションに変換します。 h2xs
の使い方は perlxstut を参照してください。
あなたの使っているシステムが動的ローディングをサポートしていない 場合であっても、やはり h2xs
を使うべきでしょう。 より詳しい情報は perlxstut と ExtUtils::MakeMaker を参照してください (簡単に言うと、新しい静的エクステションを伴った perl を再ビルドするのに 通常の make を使うのではなく、make perl を使うだけです)。
幾つかのオペレーティングシステムは、setuid スクリプトを本質的に 安全でなくするようなカーネルのバグを抱えています。 Perl は、そういったシステムに対処して動作させるための幾つかのオプションを 持っています(perlsec に説明があります)。
IPC::Open2
モジュール(標準の perl の配布に含まれています)は内部的に pipe()
, fork()
, exec()
を使った使いやすい手法です。 ただし、ドキュメントにあるデッドロックの警告をよく読んでください (IPC::Open2を参照)。 "Bidirectional Communication with Another Process" in perlipc と "Bidirectional Communication with Yourself" in perlipc も参照してください。
IPC::Open3
モジュール(標準配布パッケージに含まれています)も使えますが、 これは IPC::Open2
とは引数の順序が違うということに注意してください (IPC::Open3 を参照してください)。
system()
の目的と逆クォートの目的を混同しているのでしょう。 system()
はコマンドを実行して、終了ステータス情報(16bit 値として: 下位 7bit は(もしあれば)終了したプロセスからのシグナルで、上位 8bit は 実際の終了ステータス)を返します。 逆クォートはコマンドを実行し、そのコマンドが STDOUT に送ったものを返します。
$exit_status = system("mail-users");
$output_string = `ls`;
外部コマンドを実行する基本的なやり方が三つあります:
system $cmd; # using system()
$output = `$cmd`; # using backticks (``)
open (PIPE, "cmd |"); # using open()
system()
を使った場合の STDOUT と STDERR は、system()
コマンドが リダイレクトを行っていない限りはそれぞれスクリプトが使っていた STDOUT と STDERR へ出力されます。 逆クォートと open()
はコマンドの STDOUT だけを 読み込みます。
IPC::Open3
の open3()
関数も使えます。 Benjamin Goldberg がいくつかのサンプルコードを提供しています:
あるプログラムの STDOUT は捕捉したいが、STDERR は捨てたい場合:
use IPC::Open3;
use File::Spec;
use Symbol qw(gensym);
open(NULL, ">", File::Spec->devnull);
my $pid = open3(gensym, \*PH, ">&NULL", "cmd");
while( <PH> ) { }
waitpid($pid, 0);
あるプログラムの STDERR は捕捉したいが、STDOUT は捨てたい場合:
use IPC::Open3;
use File::Spec;
use Symbol qw(gensym);
open(NULL, ">", File::Spec->devnull);
my $pid = open3(gensym, ">&NULL", \*PH, "cmd");
while( <PH> ) { }
waitpid($pid, 0);
プログラムの STDERR を捕捉してその STDOUT を自身の STDERR に送るには:
use IPC::Open3;
use Symbol qw(gensym);
my $pid = open3(gensym, ">&STDERR", \*PH, "cmd");
while( <PH> ) { }
waitpid($pid, 0);
あるコマンドの STDOUT と STDERR を別々に読み込みたい場合、それをテンポラリ ファイルにリダイレクトして、コマンドを実行して、テンポラリファイルから 読み込みます:
use IPC::Open3;
use Symbol qw(gensym);
use IO::File;
local *CATCHOUT = IO::File->new_tmpfile;
local *CATCHERR = IO::File->new_tmpfile;
my $pid = open3(gensym, ">&CATCHOUT", ">&CATCHERR", "cmd");
waitpid($pid, 0);
seek $_, 0, 0 for \*CATCHOUT, \*CATCHERR;
while( <CATCHOUT> ) {}
while( <CATCHERR> ) {}
しかし、実際には 両方を テンポラリファイルにするする必要はありません…。 以下のものもデッドロックなしにうまく動きます:
use IPC::Open3;
use Symbol qw(gensym);
use IO::File;
local *CATCHERR = IO::File->new_tmpfile;
my $pid = open3(gensym, \*CATCHOUT, ">&CATCHERR", "cmd");
while( <CATCHOUT> ) {}
waitpid($pid, 0);
seek CATCHERR, 0, 0;
while( <CATCHERR> ) {}
そして、これはプログラムの終了を待つのではなく、プログラムの標準出力を直ちに 処理するので、より速いはずです。
これらのどれでも、呼び出しの前にファイル記述子を変更できます:
open(STDOUT, ">logfile");
system("ls");
Bourne シェルのファイル記述子リダイレクションを使うこともできます:
$output = `$cmd 2>some_file`;
open (PIPE, "cmd 2>some_file |");
同様に、STDERR を STDOUT の複製にするためにファイル記述子 リダイレクションを使うこともできます。
$output = `$cmd 2>&1`;
open (PIPE, "cmd 2>&1 |");
STDOUT の複製のために、Perl プログラムの中で単純に STDERR を オープンすることは できない ということと、リダイレクトのための シェルの呼び出しを避けることはできないということに注意してください。 以下の例はうまくいきません:
open(STDERR, ">&STDOUT");
$alloutput = `cmd args`; # stderr still escapes
これは open()
が、STDERR を(open()
が呼び出された時点で)STDOUT が 使っていた場所に対応するようにするので失敗します。 その後で逆クォートは STDOUT(に出力された内容)を文字列にしますが、 STDERR を変更することはしません(これは以前の STDOUT が指していたところです)。
backticlsの中では、csh(1)
のリダイレクト構文ではなく、Bourne shell (sh(1)
) のリダイレクト構文を 使わなければならない ということに 注意してください! なぜ Perl の system()
、逆クォート、パイプオープンの全てで Bourne シェルの ものを使うかは http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz にある "Far More Than You Ever Wanted To Know" の versus/csh.whynot という記事で 説明されています。 あるコマンドの標準出力と標準エラー出力を両方とも捉えるには:
$output = `cmd 2>&1`; # either with backticks
$pid = open(PH, "cmd 2>&1 |"); # or with an open pipe
while (<PH>) { } # plus a read
あるコマンドの標準出力を捉え、標準エラー出力を捨てるには:
$output = `cmd 2>/dev/null`; # either with backticks
$pid = open(PH, "cmd 2>/dev/null |"); # or with an open pipe
while (<PH>) { } # plus a read
あるコマンドの標準エラー出力を捉え、標準出力を捨てるには:
$output = `cmd 2>&1 1>/dev/null`; # either with backticks
$pid = open(PH, "cmd 2>&1 1>/dev/null |"); # or with an open pipe
while (<PH>) { } # plus a read
あるコマンドの標準エラー出力を捉えるために 標準出力と標準エラー出力を入れ替えるが、標準出力に 古い標準エラー出力に出るようにするには:
$output = `cmd 3>&1 1>&2 2>&3 3>&-`; # either with backticks
$pid = open(PH, "cmd 3>&1 1>&2 2>&3 3>&-|");# or with an open pipe
while (<PH>) { } # plus a read
標準出力と標準エラー出力の両方を分けて読み出すには、 別々のファイルにリダイレクトしてしまって、 その後でそのファイルをプログラムから読むというのが最も簡単な方法です:
system("program args 1>program.stdout 2>program.stderr");
これらの例では順序が重要です。 なぜなら、シェルがリダイレクトのためのファイル記述子を処理する順序は 正確に左から右へという順になっているからです。
system("prog args 1>tmpfile 2>&1");
system("prog args 2>&1 1>tmpfile");
最初のコマンドは標準出力と標準エラー出力の両方を一時ファイルに送ります。 二番目のコマンドは古い標準出力だけをファイルへと送り、古い標準エラー出力は 古い標準出力へと送り出します。
パイプされた open()
の第二引数にシェルのメタ文字が含まれている場合、 perl は fork()
し、メタ文字をデコードするためにシェルを exec()
し、 最終的に必要なプログラムを実行します。 このプログラムが実行できない場合、メッセージを得るのはシェルであって、 Perl ではありません。 あなたの Perl プログラムがわかることはシェル自身が正しく開始されたかどうか だけです。 エラーメッセージのためにシェルの STDERR を捕捉してチェックするという方法は あります。 この文書の別の場所にある "How can I capture STDERR from an external command?" を参照するか、IPC::Open3
モジュールを使ってください。
open()
の引数にシェルのメタ文字がないなら、Perl はコマンドをシェルを使わずに 直接実行し、コマンドが開始したかどうかを正しく報告できます。
厳密に言えばありません。 形式的に言えば、保守しやすいコードを書くための良い方法ではありません。 Perl は外部コマンドを実行するためのいくつかの演算子があります。 逆クォートはその一つです; これはコマンドからの出力を、自身のプログラムで 使うために収集します。 system
関数はもう一つのものです; これはコマンドからの出力を収集しません。
プログラム中に逆クォートを書くことで、そのコマンドの出力を使いたいという はっきりしたメッセージをあなたのコードの読者に送ります。 なぜ正しくないはっきりしたメッセージを送るのですか?
以下のような行を考えてみましょう:
`cat /etc/termcap`;
プログラムが正しく実行されたかどうかを確認するために $?
を見るのを忘れています。
print `cat /etc/termcap`;
このコードは、以下のように書くべきでしょう
system("cat /etc/termcap") == 0
or die "cat program failed!";
これは、プログラムが出力を終えるのを待つのではなく、cat コマンドの出力が 生成される毎にエコーします。 これはまたその戻り値のチェックも行います。
system() はまた、シェルのワイルドカード処理を行えるかどうかを直接 制御しますが、逆クォートはそういった制御は行いません。
ちょっとトリッキーになります。 単純に以下のようにはコマンドを書けません:
@ok = `grep @opts '$search_string' @filenames`;
Perl 5.8.0 から、複数の引数の open()
を使えます。 リスト形式の system()
や exec()
と同様に、シェルエスケープは 起きません。
open( GREP, "-|", 'grep', @opts, $search_string, @filenames );
chomp(@ok = <GREP>);
close GREP;
以下のようにもできます:
my @ok = ();
if (open(GREP, "-|")) {
while (<GREP>) {
chomp;
push(@ok, $_);
}
close GREP;
} else {
exec 'grep', @opts, $search_string, @filenames;
}
system()
を使ったときと同じく、シェルエスケープは exec()
のリストに 対して行われません。 さらなる例が "Safe Pipe Opens" in perlipc にあります。
もしあなたが Windows を使っているのなら、この悩ましい問題を 解決する方法は全くありません。 たとえ Perl が fork()
をエミュレートしたとしても、まだうまくいきません; なぜならマイクロソフトは argc/argv 形式の API を提供していないからです。
これは、デフォルトである perlio ではなく、stdio を使ってコンパイルされた perl でのみ起こります。 一部の(おそらく全ての?) stdio ではエラーフラグと eof フラグがセットされ、 それをクリアする必要があるからです。 POSIX モジュールはこのために使える clearerr() を定義しています。 これは、フラグをクリアするための技術的に正しい方法です。 以下の方法はこれよりは信頼性にかけるやり方です:
以下の例のように、シークポインタを保存しておいてそこへ移動します:
$where = tell(LOG);
seek(LOG, $where, 0);
上のやりかたがだめなら、一度ファイルの別の部分にシークして、それから 元の場所にシークするようにします。
これでもだめなら、ファイルの別の部分にシークして何かを読み出し、それから 元の場所にシークするようにします。
これでだめなら stdio パッケージで行うことはあきらめて、sysread を使います。
Perl を学び、自分で書き直しましょう。 まじめな話、単純なコンバータというものはありません。 シェルで行うには不格好になるようなことも Perl では簡単に行うことができ、 そして、このとても不格好なことがシェル→ perl コンバーターを作製することを ほとんど不可能なことにしているのです。 自分で書き換えをすることで、あなたは自分が本当に試すべきことについて 考えるようになり、シェルの(便利なときもあるものの多くの非効率を持ち込む) パイプラインデータストリームパラダイムから逃れることができるでしょう。
Net::FTP
, TCP::Client
, Net::Telnet
といったモジュール(CPAN で入手可能です)を 試してみてください。 http://www.cpan.org/scripts/netstuff/telnet.emul.shar も telnet プロトコルを エミュレートする助けになるでしょうが、Net::Telnet
は使うのがとても簡単です。
あなたのやりたいことが telnet のふりをすることであっても初期化時の telnet のハンドシェイクを必要としないのであれば、 標準的な dual-process アプローチで十分でしょう。
use IO::Socket; # new in 5.004
$handle = IO::Socket::INET->new('www.perl.com:80')
or die "can't connect to port 80 on www.perl.com: $!";
$handle->autoflush(1);
if (fork()) { # XXX: undef means failure
select($handle);
print while <STDIN>; # everything from stdin to socket
} else {
print while <$handle>; # everything from socket to stdout
}
close $handle;
exit;
昔々、chat2.pl と呼ばれたライブラリがありました(これは標準の perl 配布キットに含まれます)。 もしこれをどこかで見つけても使ってはいけません。 今日では、CPAN にある IO::Pty
や IO::Stty
といった ライブラリを探すのが最善でしょう。
まず初めに、あなたが(たとえば他人がパスワードを除くのを避けるためなどの) セキュリティ上の理由でそれを行おうとしてるのであれば、 重要な情報が引数として与えられることがないようにプログラムを 書き直すべきだということに注意してください。 引数を隠すことは、あなたのプログラムを完全に安全なものにすることは ありません。
外部から見えるコマンドラインを実際に書き換えるために、perlvar で 説明されているように $0 という変数に代入することができます。 ただし、これはすべてのオペレーティングシステムで実行できるというものでは ありません。 sendmail のようなデーモンプログラムは以下の例のように状態を設定します:
$0 = "orcus [accepting connections]";
もっとも厳密な意味で言うと、それはできません--スクリプトはそれを 起動したシェルとは異なるプロセスで実行されるのです。 あるプロセスに対する変更はその親に反映されることはありません --変更した後で生成された子プロセスに対してのみ反映されます。 あなたの使っているシェルにおいてスクリプトの出力を eval()
することによって、 お望みのことをしたように見せかけるシェルマジック (shell magic)があります。 詳しくは comp.unix.questions FAQを調べてください。
あなたの使っているシステムがそういった機能をサポートしていると仮定すると、 そのプロセスに対して適切なシグナルを送るだけです ("kill" in perlfunc を参照してください)。 最初にTERMシグナルを送り、ちょっとだけ待って、 終了させるために KILL シグナルを送るというのが一般的なものです。
あなたのいうデーモンプロセスが detach されている(tty と 結び付けられていない)ものであれば、以下の手順がほとんどの UNIX 的な システムで動作するということが報告されています。 非 UNIX ユーザーは Your_OS::Process モジュールで他の解決策を あたるべきでしょう。
/dev/tty をオープンし、それに TIOCNOTTY ioctl を使います。 詳しくは tty を参照してください。 そのほかもっと良いのは、POSIX::setsid()
関数を使うことです。 これによってプロセスグループに関して思い煩う必要がなくなります。
/ へディレクトリを変更します。
STDIN、STDOUT、STDERR を再オープンします。 これでこれらのハンドルは以前の tty とは結び付けらていない状態になります。
以下のようにしてバックグラウンドにします:
fork && exit;
CPAN で入手できる Proc::Daemon
モジュールはこれらの操作を 行ってくれる関数を提供しています。
(brian d foy によって寄贈されました)
これは答えるのが難しい質問で、最良の答えは単なる推測です。
本当に知りたいことは何でしょう? 単にファイルハンドルの一つが端末と接続しているかどうかを知りたいなら、 -t
ファイルテストを試すことができます:
if( -t STDOUT ) {
print "I'm connected to a terminal!\n";
}
しかし、その先に実際の人間がいることを想定するなら、うまく いかないかもしれません。 Expect
では、他のプログラムは人間である振りをします。 プログラムはチューリングテストに通過しそうになるかもしれません。
IO::Interactive
モジュールが答えとして最良のものです。 この is_interactive
関数は出力ファイルハンドルを返します; このファイルハンドルは、モジュールがセッションが対話的であると考えた 場合には、標準出力を示します。 さもなければ、ファイルハンドルは、単に出力が捨てられる空のハンドルです:
use IO::Interactive;
print { is_interactive } "I might go to standard output!\n";
これままだ実際の人間がプロンプトに答えたり出力を読んだりするのが 実際の人間であることを保証しません。
あなたの配布での自動化テストの扱う方法を知りたいなら、環境を チェックしてください。 例えば、CPAN Testers は AUTOMATED_TESTING
の値を設定します:
unless( $ENV{AUTOMATED_TESTING} ) {
print "Hello interactive tester!\n";
}
"Signals" in perlipc やらくだ本の "Signal" の章で説明されているように、 alarm()
関数と、おそらくはシグナルハンドラーを組み合わせて使います。 この代わりに、CPAN にあるより柔軟性のある Sys::AlarmCall
モジュールを使うこともできます。
alarm()
関数は Windows の全てのバージョンで実装されているわけではありません。 あなたの特定のバージョンの Perl のドキュメントをチェックしてください。
(Xho によって寄贈されました)
CPAN にある BSD::Resource
モジュールを使います。 例として:
use BSD::Resource;
setrlimit(RLIMIT_CPU,10,20) or die $!;
これはソフト制限とハード制限をそれぞれ 10 秒と 20 秒にセットします。 CPU が 10 秒の時間を消費後("wall" 時間ではありません)、プロセスはシグナル (システムによっては XCPU)を送り、トラップされなければ、これによりプロセスは 終了します。 シグナルがトラップされると、さらに 10 秒(合計 20 秒)経過後、プロセスは ブロック不可シグナルで kill されます。
詳細については BSD::Resource
とあなたのシステムのドキュメントを 参照してください。
SIGCHLD を受け取ったときに wait()
を呼び出すように "Signals" in perlipc に ある刈り取り機プログラム (reaper code) を使うか、 "How do I start a process in the background?" in perlfaq8 で 説明されている double-fork テクニックを使います。
DBI
モジュールはほとんどのデータベースサーバと型に対する抽象 インターフェースを提供します; これには Oracle, DB2, Sybase, mysql, Postgresql, ODBC, フラットファイルを含みます。 DBI モジュールは、DBD と呼ばれるデータベースドライバを通して各データベース 型にアクセスします。 利用可能なドライバの完全な一覧は CPAN (http://www.cpan.org/modules/by-module/DBD/) にあります。 DBI に関するさらなる情報は http://dbi.perl.org にあります。
その他のモジュールはより具体的なアクセスを提供します: Win32::ODBC
, Alzabo
, iodbc
などは CPAN Search (http://search.cpan.org) で 見つけられます。
できません。 system()
呼び出しを模倣する必要があり(perlipc のサンプルコードを 参照してください)、サブプロセスでのシグナルを送る INT シグナルのためのシグナルハンドラーを持つ必要があります。 あるいは、以下のようにしてチェックすることもできます:
$rc = system($cmd);
if ($rc & 127) { die "signal death" }
幸運にもあなたの使っているシステムがノンブロッキング読み出し (ほとんどの Unix 的システムはサポートしています)をサポートしているのであれば、 Fcntl
モジュールの O_NDELAY
や O_NONBLOCK
というフラグを sysopen()
と一緒に使うだけです。
use Fcntl;
sysopen(FH, "/foo/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644)
or die "can't open /foo/somefile: $!":
(答えは brian d foy によって寄贈されました)
あなたが Perl スクリプトを実行すると、他の誰かがあなたのためにスクリプトを 動かします; そしてその他の誰かがエラーメッセージを出すことがあります。 スクリプトも自身の警告やエラーメッセージを出すかもしれません。 ほとんどの場合、それを言っているのが誰かは教えてもらえません。
あなたが perl を実行しているものを修正することはおそらくできませんが、 独自の警告と die の関数を定義することで、perl がどのように警告を 出力するかを変えることはできます。
すぐには気付かないかもしれない誤りを含むこのスクリプトを考えてみてください。
#!/usr/locl/bin/perl
print "Hello World\n";
これを私のシェル(たまたま bash でした)で実行するとエラーが表示されます。 これは perl が print()
関数を忘れてしまったかのように見えますが、 #! 行の perl へのパスが間違っているので、シェルがこのスクリプトを実行し、 エラーが表示されます。
$ ./test
./test: line 3: print: command not found
素早く汚い修正には少しコードが必要ですが、おそらく問題を見つけ出すのに 必要なものが全てあるでしょう。
#!/usr/bin/perl -w
BEGIN {
$SIG{__WARN__} = sub{ print STDERR "Perl: ", @_; };
$SIG{__DIE__} = sub{ print STDERR "Perl: ", @_; exit 1};
}
$a = 1 + undef;
$x / 0;
__END__
perl のメッセージは先頭に "Perl" を付けて出力されます。 BEGIN
ブロックはコンパイル時に動作するので、全てのコンパイル時のエラーと 警告にも "Perl:" の接頭辞がつきます。
Perl: Useless use of division (/) in void context at ./test line 9.
Perl: Name "main::a" used only once: possible typo at ./test line 8.
Perl: Name "main::x" used only once: possible typo at ./test line 9.
Perl: Use of uninitialized value in addition (+) at ./test line 8.
Perl: Use of uninitialized value in division (/) at ./test line 9.
Perl: Illegal division by zero at ./test line 9.
Perl: Illegal division by zero at -e line 3.
"Perl:" という文字がなければ、perl が出しているものではありません。
単に全ての perl のエラーを知るという方法もありますが、(全てのエラーを 知っている人もいるかもしれませんが)おそらくあなたは知らないでしょう。 しかし、これら全ては perldiag マニュアルページにあるはずです。 もしエラーがここになければ、それはおそらく perl のエラーではありません。
全てのメッセージを探すというのは最も簡単な方法ではないので、その作業は perl にさせます。 perl の通常のメッセージを、より長い説明に変更する diagnostics プラグマを 使います。
use diagnostics;
段落一つか二つの追加の議論が表示されなければ、それは perl のメッセージでは ないでしょう。
(brian d foy によって寄贈されました)
最も単純な方法は、Perl と同梱されている cpan
コマンドを使って、この仕事を してくれる CPAN モジュールを入手することです。 インストールするモジュールの一覧を与えます:
$ cpan IO::Interactive Getopt::Whatever
CPANPLUS
が好みなら、やはり簡単です:
$ cpanp i IO::Interactive Getopt::Whatever
If you want to install a distribution from the current directory, you can tell CPAN.pm
to install .
(the full stop):
$ cpan .
その他に出来ることについてはこれらのコマンドの文書を参照してください。
全ての依存を自分で解決して、配布を自分自身でインストールしてみたい場合は、 二つのビルド方法のどちらかに従います。
Makefile.PL を使う配布では:
$ perl Makefile.PL
$ make test install
Build.PL を使う配布では:
$ perl Build.PL
$ ./Build test
$ ./Build install
一部の配布ではライブラリはその他のサードパーティのコードへのリンクが 必要であったり、ビルドとインストールの手順がもっと複雑な場合もあります。 見付かった README や INSTALL ファイルをチェックしてください。
(brian d foy によって寄贈されました)
Perl は require
文を実行時に実行します。 一旦 Perl がロードされ、コンパイルされ、ファイルが実行されると、 他に何もしません。 use
文は require
と同じことをコンパイル時に行いますが、 Perl はまたロードされたパッケージの import
メソッドを呼び出します。 以下の二つは同じです:
use MODULE qw(import list);
BEGIN {
require MODULE;
MODULE->import(import list);
}
しかし、明示的に空のインポートリストを使うことで、import
を 抑制できます。 これらはどちらもやはりコンパイル時に起こります:
use MODULE ();
BEGIN {
require MODULE;
}
use
は import
メソッドの呼び出しも行うので、 MODULE
の実際の値は裸の単語でなければなりません。 これは、use
は名前でファイルをロード出来ませんが、 require
ではできます:
require "$ENV{HOME}/lib/Foo.pm"; # no @INC searching!
さらなる詳細については perlfunc の use
の項目を参照してください。
モジュールを作成するときに、Perl にモジュールをインストールする場所を 指定します。
自分自身が使うためにモジュールをインストールしたいなら、一番簡単な方法は、 CPAN からダウンロードできる local::lib
でしょう。 これは様々なインストール設定を行い、プログラム中で同じ設定を使います。
もっと柔軟性がほしいなら、CPAN クライアントを特定の状況に合わせて 設定する必要があります。
Makefile.PL
-ベースの配布では、Makefile の生成時に INSTALL_BASE オプションを使ってください:
perl Makefile.PL INSTALL_BASE=/mydir/perl
CPAN.pm シェルを使ったときに、自動的にモジュールを自分のプライベートな ディレクトリにインストールさせるように、CPAN.pm の設定を変更できます:
% cpan
cpan> o conf makepl_arg INSTALL_BASE=/mydir/perl
cpan> o conf commit
Build.PL
-ベースの配布では、--install_base オプションを使ってください:
perl Build.PL --install_base /mydir/perl
自動的にこのオプションを使うために、CPAN.pm を設定することも出来ます:
% cpan
cpan> o conf mbuild_arg "--install_base /mydir/perl"
cpan> o conf commit
INSTALL_BASE はこれらのツールにモジュールを /mydir/perl/lib/perl5 に 置くように伝えます。 新しくインストールしたモジュールを実行する方法についての詳細は "How do I add a directory to my include path (@INC) at runtime?" を 参照してください。
しかし、INSTALL_BASE には一つの問題点があります; なぜなら、より古いバージョンの ExtUtils::MakeMaker
が推奨していた PREFIX および LIB とは異なった動作をするからです。 INSTALL_BASE は、複数のバージョンの Perl や異なったアーキテクチャに 対して同じディレクトリにモジュールをインストールすることには 対応していません。 もし本当にそれが必要でそうするなら、古い PREFIX と LIB の設定を 考慮するべきです。 さらなる詳細については ExtUtils::Makemaker
の文書を参照してください。
(brian d foy によって寄贈されました)
すでにディレクトリが分かっている場合は、それを @INC
に追加できます。 コンパイル時に分かっている場合は、<use lib> が使えます:
use lib $directory;
このタスクの秘訣は、ディレクトリを探すことです。 あなたのスクリプトが(chdir
などで)他の場所へ行く前に、Perl に 同梱されている Cwd
モジュールを使って、カレントワーキングディレクトリを 取得できます:
BEGIN {
use Cwd;
our $directory = cwd;
}
use lib $directory;
似たようなことは、スクリプト名を記録している $0
でもできます。 これは相対パスかもしれませんが、rel2abs
はこれを絶対パスに変更できます。 以下のようにすると
BEGIN {
use File::Spec::Functions qw(rel2abs);
use File::Basename qw(dirname);
my $path = rel2abs( $0 );
our $directory = dirname( $path );
}
use lib $directory;
Perl に同梱されている FindBin
モジュールが働くでしょう。 これは現在実行しているスクリプトのディレクトリを見つけて $Bin
に 設定し、正しいライブラリパスを構築するために使えるようにします:
use FindBin qw($Bin);
同じことをするのに local::lib
も使えます。 local::lib
の設定を使ってモジュールをインストールしてから、プログラムで そのモジュールを使います:
use local::lib; # sets up a local lib at ~/perl5
さらなる詳細については local::lib
の文書を参照してください。
環境変数、実行時スイッチ、コード内の文などを使って、インクルードパスを 変更するためのお薦めの方法を挙げておきます:
PERLLIB
環境変数 $ export PERLLIB=/path/to/my/dir
$ perl program.pl
PERL5LIB
環境変数 $ export PERL5LIB=/path/to/my/dir
$ perl program.pl
perl -Idir
コマンドラインフラグ $ perl -I/path/to/my/dir program.pl
lib
プラグマ use lib "$ENV{HOME}/myown_perllib";
local::lib
module: use local::lib;
use local::lib "~/myown_perllib";
最後のものが特に便利です。 なぜなら、これはマシン依存のアーキテクチャを知っているからです。 プラグマ的モジュール(pragmatic module) lib.pm
は Perl 5.002 で 最初に導入されました。
それは Perl 4 スタイルのファイルで、ネットワーク使用のための 値を定義しているものです。 これは Perl がインストールされたときに h2ph
を使って作成されることも ありますが、そうでないときもあります。 最近のやり方では use Socket
を代わりに使用します。
Copyright (c) 1997-2010 Tom Christiansen, Nathan Torkington, and other authors as noted. All rights reserved.
This documentation is free; you can redistribute it and/or modify it under the same terms as Perl itself.
Irrespective of its distribution, all code examples in this file are hereby placed into the public domain. You are permitted and encouraged to use this code in your own programs for fun or for profit as you see fit. A simple comment in the code giving credit would be courteous but is not required.