diff options
Diffstat (limited to 'chromium/third_party/cygwin/lib/perl5/5.10/pods/perlfaq8.pod')
| -rw-r--r-- | chromium/third_party/cygwin/lib/perl5/5.10/pods/perlfaq8.pod | 1331 |
1 files changed, 0 insertions, 1331 deletions
diff --git a/chromium/third_party/cygwin/lib/perl5/5.10/pods/perlfaq8.pod b/chromium/third_party/cygwin/lib/perl5/5.10/pods/perlfaq8.pod deleted file mode 100644 index 7def972a202..00000000000 --- a/chromium/third_party/cygwin/lib/perl5/5.10/pods/perlfaq8.pod +++ /dev/null @@ -1,1331 +0,0 @@ -=head1 NAME - -perlfaq8 - System Interaction ($Revision: 10183 $) - -=head1 DESCRIPTION - -This section of the Perl FAQ covers questions involving operating -system interaction. Topics include interprocess communication (IPC), -control over the user-interface (keyboard, screen and pointing -devices), and most anything else not related to data manipulation. - -Read the FAQs and documentation specific to the port of perl to your -operating system (eg, L<perlvms>, L<perlplan9>, ...). These should -contain more detailed information on the vagaries of your perl. - -=head2 How do I find out which operating system I'm running under? - -The $^O variable ($OSNAME if you use English) contains an indication of -the name of the operating system (not its release number) that your perl -binary was built for. - -=head2 How come exec() doesn't return? - -Because that's what it does: it replaces your currently running -program with a different one. If you want to keep going (as is -probably the case if you're asking this question) use system() -instead. - -=head2 How do I do fancy stuff with the keyboard/screen/mouse? - -How you access/control keyboards, screens, and pointing devices -("mice") is system-dependent. Try the following modules: - -=over 4 - -=item Keyboard - - Term::Cap Standard perl distribution - Term::ReadKey CPAN - Term::ReadLine::Gnu CPAN - Term::ReadLine::Perl CPAN - Term::Screen CPAN - -=item Screen - - Term::Cap Standard perl distribution - Curses CPAN - Term::ANSIColor CPAN - -=item Mouse - - Tk CPAN - -=back - -Some of these specific cases are shown as examples in other answers -in this section of the perlfaq. - -=head2 How do I print something out in color? - -In general, you don't, because you don't know whether -the recipient has a color-aware display device. If you -know that they have an ANSI terminal that understands -color, you can use the Term::ANSIColor module from CPAN: - - use Term::ANSIColor; - print color("red"), "Stop!\n", color("reset"); - print color("green"), "Go!\n", color("reset"); - -Or like this: - - use Term::ANSIColor qw(:constants); - print RED, "Stop!\n", RESET; - print GREEN, "Go!\n", RESET; - -=head2 How do I read just one key without waiting for a return key? - -Controlling input buffering is a remarkably system-dependent matter. -On many systems, you can just use the B<stty> command as shown in -L<perlfunc/getc>, but as you see, that's already getting you into -portability snags. - - 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"; - -The Term::ReadKey module from CPAN offers an easy-to-use interface that -should be more efficient than shelling out to B<stty> for each key. -It even includes limited support for Windows. - - use Term::ReadKey; - ReadMode('cbreak'); - $key = ReadKey(0); - ReadMode('normal'); - -However, using the code requires that you have a working C compiler -and can use it to build and install a CPAN module. Here's a solution -using the standard POSIX module, which is already on your systems -(assuming your system supports POSIX). - - use HotKey; - $key = readkey(); - -And here's the HotKey module, which hides the somewhat mystifying calls -to manipulate the POSIX termios structures. - - # 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; - -=head2 How do I check whether input is ready on the keyboard? - -The easiest way to do this is to read a key in nonblocking mode with the -Term::ReadKey module from CPAN, passing it an argument of -1 to indicate -not to block: - - 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 - -=head2 How do I clear the screen? - -If you only have do so infrequently, use C<system>: - - system("clear"); - -If you have to do this a lot, save the clear string -so you can print it 100 times without calling a program -100 times: - - $clear_string = `clear`; - print $clear_string; - -If you're planning on doing other screen manipulations, like cursor -positions, etc, you might wish to use Term::Cap module: - - use Term::Cap; - $terminal = Term::Cap->Tgetent( {OSPEED => 9600} ); - $clear_string = $terminal->Tputs('cl'); - -=head2 How do I get the screen size? - -If you have Term::ReadKey module installed from CPAN, -you can use it to fetch the width and height in characters -and in pixels: - - use Term::ReadKey; - ($wchar, $hchar, $wpixels, $hpixels) = GetTerminalSize(); - -This is more portable than the raw C<ioctl>, but not as -illustrative: - - 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"; - -=head2 How do I ask the user for a password? - -(This question has nothing to do with the web. See a different -FAQ for that.) - -There's an example of this in L<perlfunc/crypt>). First, you put the -terminal into "no echo" mode, then just read the password normally. -You may do this with an old-style ioctl() function, POSIX terminal -control (see L<POSIX> or its documentation the Camel Book), or a call -to the B<stty> program, with varying degrees of portability. - -You can also do this for most systems using the Term::ReadKey module -from CPAN, which is easier to use and in theory more portable. - - use Term::ReadKey; - - ReadMode('noecho'); - $password = ReadLine(0); - -=head2 How do I read and write the serial port? - -This depends on which operating system your program is running on. In -the case of Unix, the serial ports will be accessible through files in -/dev; on other systems, device names will doubtless differ. -Several problem areas common to all device interaction are the -following: - -=over 4 - -=item lockfiles - -Your system may use lockfiles to control multiple access. Make sure -you follow the correct protocol. Unpredictable behavior can result -from multiple processes reading from one device. - -=item open mode - -If you expect to use both read and write operations on the device, -you'll have to open it for update (see L<perlfunc/"open"> for -details). You may wish to open it without running the risk of -blocking by using sysopen() and C<O_RDWR|O_NDELAY|O_NOCTTY> from the -Fcntl module (part of the standard perl distribution). See -L<perlfunc/"sysopen"> for more on this approach. - -=item end of line - -Some devices will be expecting a "\r" at the end of each line rather -than a "\n". In some ports of perl, "\r" and "\n" are different from -their usual (Unix) ASCII values of "\012" and "\015". You may have to -give the numeric values you want directly, using octal ("\015"), hex -("0x0D"), or as a control-character specification ("\cM"). - - print DEV "atv1\012"; # wrong, for some devices - print DEV "atv1\015"; # right, for some devices - -Even though with normal text files a "\n" will do the trick, there is -still no unified scheme for terminating a line that is portable -between Unix, DOS/Win, and Macintosh, except to terminate I<ALL> line -ends with "\015\012", and strip what you don't need from the output. -This applies especially to socket I/O and autoflushing, discussed -next. - -=item flushing output - -If you expect characters to get to your device when you print() them, -you'll want to autoflush that filehandle. You can use select() -and the C<$|> variable to control autoflushing (see L<perlvar/$E<verbar>> -and L<perlfunc/select>, or L<perlfaq5>, "How do I flush/unbuffer an -output filehandle? Why must I do this?"): - - $oldh = select(DEV); - $| = 1; - select($oldh); - -You'll also see code that does this without a temporary variable, as in - - select((select(DEV), $| = 1)[0]); - -Or if you don't mind pulling in a few thousand lines -of code just because you're afraid of a little $| variable: - - use IO::Handle; - DEV->autoflush(1); - -As mentioned in the previous item, this still doesn't work when using -socket I/O between Unix and Macintosh. You'll need to hard code your -line terminators, in that case. - -=item non-blocking input - -If you are doing a blocking read() or sysread(), you'll have to -arrange for an alarm handler to provide a timeout (see -L<perlfunc/alarm>). If you have a non-blocking open, you'll likely -have a non-blocking read, which means you may have to use a 4-arg -select() to determine whether I/O is ready on that device (see -L<perlfunc/"select">. - -=back - -While trying to read from his caller-id box, the notorious Jamie Zawinski -C<< <jwz@netscape.com> >>, after much gnashing of teeth and fighting with sysread, -sysopen, POSIX's tcgetattr business, and various other functions that -go bump in the night, finally came up with this: - - 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"; - } - } - -=head2 How do I decode encrypted password files? - -You spend lots and lots of money on dedicated hardware, but this is -bound to get you talked about. - -Seriously, you can't if they are Unix password files--the Unix -password system employs one-way encryption. It's more like hashing -than encryption. The best you can do is check whether something else -hashes to the same string. You can't turn a hash back into the -original string. Programs like Crack can forcibly (and intelligently) -try to guess passwords, but don't (can't) guarantee quick success. - -If you're worried about users selecting bad passwords, you should -proactively check when they try to change their password (by modifying -passwd(1), for example). - -=head2 How do I start a process in the background? - -Several modules can start other processes that do not block -your Perl program. You can use IPC::Open3, Parallel::Jobs, -IPC::Run, and some of the POE modules. See CPAN for more -details. - -You could also use - - system("cmd &") - -or you could use fork as documented in L<perlfunc/"fork">, with -further examples in L<perlipc>. Some things to be aware of, if you're -on a Unix-like system: - -=over 4 - -=item STDIN, STDOUT, and STDERR are shared - -Both the main process and the backgrounded one (the "child" process) -share the same STDIN, STDOUT and STDERR filehandles. If both try to -access them at once, strange things can happen. You may want to close -or reopen these for the child. You can get around this with -C<open>ing a pipe (see L<perlfunc/"open">) but on some systems this -means that the child process cannot outlive the parent. - -=item Signals - -You'll have to catch the SIGCHLD signal, and possibly SIGPIPE too. -SIGCHLD is sent when the backgrounded process finishes. SIGPIPE is -sent when you write to a filehandle whose child process has closed (an -untrapped SIGPIPE can cause your program to silently die). This is -not an issue with C<system("cmd&")>. - -=item Zombies - -You have to be prepared to "reap" the child process when it finishes. - - $SIG{CHLD} = sub { wait }; - - $SIG{CHLD} = 'IGNORE'; - -You can also use a double fork. You immediately wait() for your -first child, and the init daemon will wait() for your grandchild once -it exits. - - unless ($pid = fork) { - unless (fork) { - exec "what you really wanna do"; - die "exec failed!"; - } - exit 0; - } - waitpid($pid, 0); - -See L<perlipc/"Signals"> for other examples of code to do this. -Zombies are not an issue with C<system("prog &")>. - -=back - -=head2 How do I trap control characters/signals? - -You don't actually "trap" a control character. Instead, that character -generates a signal which is sent to your terminal's currently -foregrounded process group, which you then trap in your process. -Signals are documented in L<perlipc/"Signals"> and the -section on "Signals" in the Camel. - -You can set the values of the %SIG hash to be the functions you want -to handle the signal. After perl catches the signal, it looks in %SIG -for a key with the same name as the signal, then calls the subroutine -value for that key. - - # 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"; - -Perl versions before 5.8 had in its C source code signal handlers which -would catch the signal and possibly run a Perl function that you had set -in %SIG. This violated the rules of signal handling at that level -causing perl to dump core. Since version 5.8.0, perl looks at %SIG -*after* the signal has been caught, rather than while it is being caught. -Previous versions of this answer were incorrect. - -=head2 How do I modify the shadow password file on a Unix system? - -If perl was installed correctly and your shadow library was written -properly, the getpw*() functions described in L<perlfunc> should in -theory provide (read-only) access to entries in the shadow password -file. To change the file, make a new shadow password file (the format -varies from system to system--see L<passwd> for specifics) and use -pwd_mkdb(8) to install it (see L<pwd_mkdb> for more details). - -=head2 How do I set the time and date? - -Assuming you're running under sufficient permissions, you should be -able to set the system-wide date and time by running the date(1) -program. (There is no way to set the time and date on a per-process -basis.) This mechanism will work for Unix, MS-DOS, Windows, and NT; -the VMS equivalent is C<set time>. - -However, if all you want to do is change your time zone, you can -probably get away with setting an environment variable: - - $ENV{TZ} = "MST7MDT"; # unixish - $ENV{'SYS$TIMEZONE_DIFFERENTIAL'}="-5" # vms - system "trn comp.lang.perl.misc"; - -=head2 How can I sleep() or alarm() for under a second? -X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select> - -If you want finer granularity than the 1 second that the C<sleep()> -function provides, the easiest way is to use the C<select()> function as -documented in L<perlfunc/"select">. Try the C<Time::HiRes> and -the C<BSD::Itimer> modules (available from CPAN, and starting from -Perl 5.8 C<Time::HiRes> is part of the standard distribution). - -=head2 How can I measure time under a second? -X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select> - -(contributed by brian d foy) - -The C<Time::HiRes> module (part of the standard distribution as of -Perl 5.8) measures time with the C<gettimeofday()> system call, which -returns the time in microseconds since the epoch. If you can't install -C<Time::HiRes> for older Perls and you are on a Unixish system, you -may be able to call C<gettimeofday(2)> directly. See -L<perlfunc/syscall>. - -=head2 How can I do an atexit() or setjmp()/longjmp()? (Exception handling) - -Release 5 of Perl added the END block, which can be used to simulate -atexit(). Each package's END block is called when the program or -thread ends (see L<perlmod> manpage for more details). - -For example, you can use this to make sure your filter program -managed to finish its output without filling up the disk: - - END { - close(STDOUT) || die "stdout close failed: $!"; - } - -The END block isn't called when untrapped signals kill the program, -though, so if you use END blocks you should also use - - use sigtrap qw(die normal-signals); - -Perl's exception-handling mechanism is its eval() operator. You can -use eval() as setjmp and die() as longjmp. For details of this, see -the section on signals, especially the time-out handler for a blocking -flock() in L<perlipc/"Signals"> or the section on "Signals" in -the Camel Book. - -If exception handling is all you're interested in, try the -exceptions.pl library (part of the standard perl distribution). - -If you want the atexit() syntax (and an rmexit() as well), try the -AtExit module available from CPAN. - -=head2 Why doesn't my sockets program work under System V (Solaris)? What does the error message "Protocol not supported" mean? - -Some Sys-V based systems, notably Solaris 2.X, redefined some of the -standard socket constants. Since these were constant across all -architectures, they were often hardwired into perl code. The proper -way to deal with this is to "use Socket" to get the correct values. - -Note that even though SunOS and Solaris are binary compatible, these -values are different. Go figure. - -=head2 How can I call my system's unique C functions from Perl? - -In most cases, you write an external module to do it--see the answer -to "Where can I learn about linking C with Perl? [h2xs, xsubpp]". -However, if the function is a system call, and your system supports -syscall(), you can use the syscall function (documented in -L<perlfunc>). - -Remember to check the modules that came with your distribution, and -CPAN as well--someone may already have written a module to do it. On -Windows, try Win32::API. On Macs, try Mac::Carbon. If no module -has an interface to the C function, you can inline a bit of C in your -Perl source with Inline::C. - -=head2 Where do I get the include files to do ioctl() or syscall()? - -Historically, these would be generated by the h2ph tool, part of the -standard perl distribution. This program converts cpp(1) directives -in C header files to files containing subroutine definitions, like -&SYS_getitimer, which you can use as arguments to your functions. -It doesn't work perfectly, but it usually gets most of the job done. -Simple files like F<errno.h>, F<syscall.h>, and F<socket.h> were fine, -but the hard ones like F<ioctl.h> nearly always need to hand-edited. -Here's how to install the *.ph files: - - 1. become super-user - 2. cd /usr/include - 3. h2ph *.h */*.h - -If your system supports dynamic loading, for reasons of portability and -sanity you probably ought to use h2xs (also part of the standard perl -distribution). This tool converts C header files to Perl extensions. -See L<perlxstut> for how to get started with h2xs. - -If your system doesn't support dynamic loading, you still probably -ought to use h2xs. See L<perlxstut> and L<ExtUtils::MakeMaker> for -more information (in brief, just use B<make perl> instead of a plain -B<make> to rebuild perl with a new static extension). - -=head2 Why do setuid perl scripts complain about kernel problems? - -Some operating systems have bugs in the kernel that make setuid -scripts inherently insecure. Perl gives you a number of options -(described in L<perlsec>) to work around such systems. - -=head2 How can I open a pipe both to and from a command? - -The IPC::Open2 module (part of the standard perl distribution) is an -easy-to-use approach that internally uses pipe(), fork(), and exec() to do -the job. Make sure you read the deadlock warnings in its documentation, -though (see L<IPC::Open2>). See -L<perlipc/"Bidirectional Communication with Another Process"> and -L<perlipc/"Bidirectional Communication with Yourself"> - -You may also use the IPC::Open3 module (part of the standard perl -distribution), but be warned that it has a different order of -arguments from IPC::Open2 (see L<IPC::Open3>). - -=head2 Why can't I get the output of a command with system()? - -You're confusing the purpose of system() and backticks (``). system() -runs a command and returns exit status information (as a 16 bit value: -the low 7 bits are the signal the process died from, if any, and -the high 8 bits are the actual exit value). Backticks (``) run a -command and return what it sent to STDOUT. - - $exit_status = system("mail-users"); - $output_string = `ls`; - -=head2 How can I capture STDERR from an external command? - -There are three basic ways of running external commands: - - system $cmd; # using system() - $output = `$cmd`; # using backticks (``) - open (PIPE, "cmd |"); # using open() - -With system(), both STDOUT and STDERR will go the same place as the -script's STDOUT and STDERR, unless the system() command redirects them. -Backticks and open() read B<only> the STDOUT of your command. - -You can also use the open3() function from IPC::Open3. Benjamin -Goldberg provides some sample code: - -To capture a program's STDOUT, but discard its 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); - -To capture a program's STDERR, but discard its 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); - -To capture a program's STDERR, and let its STDOUT go to our own STDERR: - - use IPC::Open3; - use Symbol qw(gensym); - my $pid = open3(gensym, ">&STDERR", \*PH, "cmd"); - while( <PH> ) { } - waitpid($pid, 0); - -To read both a command's STDOUT and its STDERR separately, you can -redirect them to temp files, let the command run, then read the temp -files: - - 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> ) {} - -But there's no real need for *both* to be tempfiles... the following -should work just as well, without deadlocking: - - 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> ) {} - -And it'll be faster, too, since we can begin processing the program's -stdout immediately, rather than waiting for the program to finish. - -With any of these, you can change file descriptors before the call: - - open(STDOUT, ">logfile"); - system("ls"); - -or you can use Bourne shell file-descriptor redirection: - - $output = `$cmd 2>some_file`; - open (PIPE, "cmd 2>some_file |"); - -You can also use file-descriptor redirection to make STDERR a -duplicate of STDOUT: - - $output = `$cmd 2>&1`; - open (PIPE, "cmd 2>&1 |"); - -Note that you I<cannot> simply open STDERR to be a dup of STDOUT -in your Perl program and avoid calling the shell to do the redirection. -This doesn't work: - - open(STDERR, ">&STDOUT"); - $alloutput = `cmd args`; # stderr still escapes - -This fails because the open() makes STDERR go to where STDOUT was -going at the time of the open(). The backticks then make STDOUT go to -a string, but don't change STDERR (which still goes to the old -STDOUT). - -Note that you I<must> use Bourne shell (sh(1)) redirection syntax in -backticks, not csh(1)! Details on why Perl's system() and backtick -and pipe opens all use the Bourne shell are in the -F<versus/csh.whynot> article in the "Far More Than You Ever Wanted To -Know" collection in http://www.cpan.org/misc/olddoc/FMTEYEWTK.tgz . To -capture a command's STDERR and STDOUT together: - - $output = `cmd 2>&1`; # either with backticks - $pid = open(PH, "cmd 2>&1 |"); # or with an open pipe - while (<PH>) { } # plus a read - -To capture a command's STDOUT but discard its STDERR: - - $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 - -To capture a command's STDERR but discard its STDOUT: - - $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 - -To exchange a command's STDOUT and STDERR in order to capture the STDERR -but leave its STDOUT to come out our old STDERR: - - $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 - -To read both a command's STDOUT and its STDERR separately, it's easiest -to redirect them separately to files, and then read from those files -when the program is done: - - system("program args 1>program.stdout 2>program.stderr"); - -Ordering is important in all these examples. That's because the shell -processes file descriptor redirections in strictly left to right order. - - system("prog args 1>tmpfile 2>&1"); - system("prog args 2>&1 1>tmpfile"); - -The first command sends both standard out and standard error to the -temporary file. The second command sends only the old standard output -there, and the old standard error shows up on the old standard out. - -=head2 Why doesn't open() return an error when a pipe open fails? - -If the second argument to a piped open() contains shell -metacharacters, perl fork()s, then exec()s a shell to decode the -metacharacters and eventually run the desired program. If the program -couldn't be run, it's the shell that gets the message, not Perl. All -your Perl program can find out is whether the shell itself could be -successfully started. You can still capture the shell's STDERR and -check it for error messages. See L<"How can I capture STDERR from an -external command?"> elsewhere in this document, or use the -IPC::Open3 module. - -If there are no shell metacharacters in the argument of open(), Perl -runs the command directly, without using the shell, and can correctly -report whether the command started. - -=head2 What's wrong with using backticks in a void context? - -Strictly speaking, nothing. Stylistically speaking, it's not a good -way to write maintainable code. Perl has several operators for -running external commands. Backticks are one; they collect the output -from the command for use in your program. The C<system> function is -another; it doesn't do this. - -Writing backticks in your program sends a clear message to the readers -of your code that you wanted to collect the output of the command. -Why send a clear message that isn't true? - -Consider this line: - - `cat /etc/termcap`; - -You forgot to check C<$?> to see whether the program even ran -correctly. Even if you wrote - - print `cat /etc/termcap`; - -this code could and probably should be written as - - system("cat /etc/termcap") == 0 - or die "cat program failed!"; - -which will echo the cat command's output as it is generated, instead -of waiting until the program has completed to print it out. It also -checks the return value. - -C<system> also provides direct control over whether shell wildcard -processing may take place, whereas backticks do not. - -=head2 How can I call backticks without shell processing? - -This is a bit tricky. You can't simply write the command -like this: - - @ok = `grep @opts '$search_string' @filenames`; - -As of Perl 5.8.0, you can use C<open()> with multiple arguments. -Just like the list forms of C<system()> and C<exec()>, no shell -escapes happen. - - open( GREP, "-|", 'grep', @opts, $search_string, @filenames ); - chomp(@ok = <GREP>); - close GREP; - -You can also: - - my @ok = (); - if (open(GREP, "-|")) { - while (<GREP>) { - chomp; - push(@ok, $_); - } - close GREP; - } else { - exec 'grep', @opts, $search_string, @filenames; - } - -Just as with C<system()>, no shell escapes happen when you C<exec()> a -list. Further examples of this can be found in L<perlipc/"Safe Pipe -Opens">. - -Note that if you're using Windows, no solution to this vexing issue is -even possible. Even if Perl were to emulate C<fork()>, you'd still be -stuck, because Windows does not have an argc/argv-style API. - -=head2 Why can't my script read from STDIN after I gave it EOF (^D on Unix, ^Z on MS-DOS)? - -Some stdio's set error and eof flags that need clearing. The -POSIX module defines clearerr() that you can use. That is the -technically correct way to do it. Here are some less reliable -workarounds: - -=over 4 - -=item 1 - -Try keeping around the seekpointer and go there, like this: - - $where = tell(LOG); - seek(LOG, $where, 0); - -=item 2 - -If that doesn't work, try seeking to a different part of the file and -then back. - -=item 3 - -If that doesn't work, try seeking to a different part of -the file, reading something, and then seeking back. - -=item 4 - -If that doesn't work, give up on your stdio package and use sysread. - -=back - -=head2 How can I convert my shell script to perl? - -Learn Perl and rewrite it. Seriously, there's no simple converter. -Things that are awkward to do in the shell are easy to do in Perl, and -this very awkwardness is what would make a shell->perl converter -nigh-on impossible to write. By rewriting it, you'll think about what -you're really trying to do, and hopefully will escape the shell's -pipeline datastream paradigm, which while convenient for some matters, -causes many inefficiencies. - -=head2 Can I use perl to run a telnet or ftp session? - -Try the Net::FTP, TCP::Client, and Net::Telnet modules (available from -CPAN). http://www.cpan.org/scripts/netstuff/telnet.emul.shar -will also help for emulating the telnet protocol, but Net::Telnet is -quite probably easier to use.. - -If all you want to do is pretend to be telnet but don't need -the initial telnet handshaking, then the standard dual-process -approach will suffice: - - 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; - -=head2 How can I write expect in Perl? - -Once upon a time, there was a library called chat2.pl (part of the -standard perl distribution), which never really got finished. If you -find it somewhere, I<don't use it>. These days, your best bet is to -look at the Expect module available from CPAN, which also requires two -other modules from CPAN, IO::Pty and IO::Stty. - -=head2 Is there a way to hide perl's command line from programs such as "ps"? - -First of all note that if you're doing this for security reasons (to -avoid people seeing passwords, for example) then you should rewrite -your program so that critical information is never given as an -argument. Hiding the arguments won't make your program completely -secure. - -To actually alter the visible command line, you can assign to the -variable $0 as documented in L<perlvar>. This won't work on all -operating systems, though. Daemon programs like sendmail place their -state there, as in: - - $0 = "orcus [accepting connections]"; - -=head2 I {changed directory, modified my environment} in a perl script. How come the change disappeared when I exited the script? How do I get my changes to be visible? - -=over 4 - -=item Unix - -In the strictest sense, it can't be done--the script executes as a -different process from the shell it was started from. Changes to a -process are not reflected in its parent--only in any children -created after the change. There is shell magic that may allow you to -fake it by eval()ing the script's output in your shell; check out the -comp.unix.questions FAQ for details. - -=back - -=head2 How do I close a process's filehandle without waiting for it to complete? - -Assuming your system supports such things, just send an appropriate signal -to the process (see L<perlfunc/"kill">). It's common to first send a TERM -signal, wait a little bit, and then send a KILL signal to finish it off. - -=head2 How do I fork a daemon process? - -If by daemon process you mean one that's detached (disassociated from -its tty), then the following process is reported to work on most -Unixish systems. Non-Unix users should check their Your_OS::Process -module for other solutions. - -=over 4 - -=item * - -Open /dev/tty and use the TIOCNOTTY ioctl on it. See L<tty> -for details. Or better yet, you can just use the POSIX::setsid() -function, so you don't have to worry about process groups. - -=item * - -Change directory to / - -=item * - -Reopen STDIN, STDOUT, and STDERR so they're not connected to the old -tty. - -=item * - -Background yourself like this: - - fork && exit; - -=back - -The Proc::Daemon module, available from CPAN, provides a function to -perform these actions for you. - -=head2 How do I find out if I'm running interactively or not? - -Good question. Sometimes C<-t STDIN> and C<-t STDOUT> can give clues, -sometimes not. - - if (-t STDIN && -t STDOUT) { - print "Now what? "; - } - -On POSIX systems, you can test whether your own process group matches -the current process group of your controlling terminal as follows: - - use POSIX qw/getpgrp tcgetpgrp/; - - # Some POSIX systems, such as Linux, can be - # without a /dev/tty at boot time. - if (!open(TTY, "/dev/tty")) { - print "no tty\n"; - } else { - $tpgrp = tcgetpgrp(fileno(*TTY)); - $pgrp = getpgrp(); - if ($tpgrp == $pgrp) { - print "foreground\n"; - } else { - print "background\n"; - } - } - -=head2 How do I timeout a slow event? - -Use the alarm() function, probably in conjunction with a signal -handler, as documented in L<perlipc/"Signals"> and the section on -"Signals" in the Camel. You may instead use the more flexible -Sys::AlarmCall module available from CPAN. - -The alarm() function is not implemented on all versions of Windows. -Check the documentation for your specific version of Perl. - -=head2 How do I set CPU limits? -X<BSD::Resource> X<limit> X<CPU> - -(contributed by Xho) - -Use the C<BSD::Resource> module from CPAN. As an example: - - use BSD::Resource; - setrlimit(RLIMIT_CPU,10,20) or die $!; - -This sets the soft and hard limits to 10 and 20 seconds, respectively. -After 10 seconds of time spent running on the CPU (not "wall" time), -the process will be sent a signal (XCPU on some systems) which, if not -trapped, will cause the process to terminate. If that signal is -trapped, then after 10 more seconds (20 seconds in total) the process -will be killed with a non-trappable signal. - -See the C<BSD::Resource> and your systems documentation for the gory -details. - -=head2 How do I avoid zombies on a Unix system? - -Use the reaper code from L<perlipc/"Signals"> to call wait() when a -SIGCHLD is received, or else use the double-fork technique described -in L<perlfaq8/"How do I start a process in the background?">. - -=head2 How do I use an SQL database? - -The DBI module provides an abstract interface to most database -servers and types, including Oracle, DB2, Sybase, mysql, Postgresql, -ODBC, and flat files. The DBI module accesses each database type -through a database driver, or DBD. You can see a complete list of -available drivers on CPAN: http://www.cpan.org/modules/by-module/DBD/ . -You can read more about DBI on http://dbi.perl.org . - -Other modules provide more specific access: Win32::ODBC, Alzabo, iodbc, -and others found on CPAN Search: http://search.cpan.org . - -=head2 How do I make a system() exit on control-C? - -You can't. You need to imitate the system() call (see L<perlipc> for -sample code) and then have a signal handler for the INT signal that -passes the signal on to the subprocess. Or you can check for it: - - $rc = system($cmd); - if ($rc & 127) { die "signal death" } - -=head2 How do I open a file without blocking? - -If you're lucky enough to be using a system that supports -non-blocking reads (most Unixish systems do), you need only to use the -O_NDELAY or O_NONBLOCK flag from the Fcntl module in conjunction with -sysopen(): - - use Fcntl; - sysopen(FH, "/foo/somefile", O_WRONLY|O_NDELAY|O_CREAT, 0644) - or die "can't open /foo/somefile: $!": - -=head2 How do I tell the difference between errors from the shell and perl? - -(answer contributed by brian d foy) - -When you run a Perl script, something else is running the script for you, -and that something else may output error messages. The script might -emit its own warnings and error messages. Most of the time you cannot -tell who said what. - -You probably cannot fix the thing that runs perl, but you can change how -perl outputs its warnings by defining a custom warning and die functions. - -Consider this script, which has an error you may not notice immediately. - - #!/usr/locl/bin/perl - - print "Hello World\n"; - -I get an error when I run this from my shell (which happens to be -bash). That may look like perl forgot it has a print() function, -but my shebang line is not the path to perl, so the shell runs the -script, and I get the error. - - $ ./test - ./test: line 3: print: command not found - -A quick and dirty fix involves a little bit of code, but this may be all -you need to figure out the problem. - - #!/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__ - -The perl message comes out with "Perl" in front. The BEGIN block -works at compile time so all of the compilation errors and warnings -get the "Perl:" prefix too. - - 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. - -If I don't see that "Perl:", it's not from perl. - -You could also just know all the perl errors, and although there are -some people who may know all of them, you probably don't. However, they -all should be in the perldiag manpage. If you don't find the error in -there, it probably isn't a perl error. - -Looking up every message is not the easiest way, so let perl to do it -for you. Use the diagnostics pragma with turns perl's normal messages -into longer discussions on the topic. - - use diagnostics; - -If you don't get a paragraph or two of expanded discussion, it -might not be perl's message. - -=head2 How do I install a module from CPAN? - -The easiest way is to have a module also named CPAN do it for you. -This module comes with perl version 5.004 and later. - - $ perl -MCPAN -e shell - - cpan shell -- CPAN exploration and modules installation (v1.59_54) - ReadLine support enabled - - cpan> install Some::Module - -To manually install the CPAN module, or any well-behaved CPAN module -for that matter, follow these steps: - -=over 4 - -=item 1 - -Unpack the source into a temporary area. - -=item 2 - - perl Makefile.PL - -=item 3 - - make - -=item 4 - - make test - -=item 5 - - make install - -=back - -If your version of perl is compiled without dynamic loading, then you -just need to replace step 3 (B<make>) with B<make perl> and you will -get a new F<perl> binary with your extension linked in. - -See L<ExtUtils::MakeMaker> for more details on building extensions. -See also the next question, "What's the difference between require -and use?". - -=head2 What's the difference between require and use? - -Perl offers several different ways to include code from one file into -another. Here are the deltas between the various inclusion constructs: - - 1) do $file is like eval `cat $file`, except the former - 1.1: searches @INC and updates %INC. - 1.2: bequeaths an *unrelated* lexical scope on the eval'ed code. - - 2) require $file is like do $file, except the former - 2.1: checks for redundant loading, skipping already loaded files. - 2.2: raises an exception on failure to find, compile, or execute $file. - - 3) require Module is like require "Module.pm", except the former - 3.1: translates each "::" into your system's directory separator. - 3.2: primes the parser to disambiguate class Module as an indirect object. - - 4) use Module is like require Module, except the former - 4.1: loads the module at compile time, not run-time. - 4.2: imports symbols and semantics from that package to the current one. - -In general, you usually want C<use> and a proper Perl module. - -=head2 How do I keep my own module/library directory? - -When you build modules, tell Perl where to install the modules. - -For C<Makefile.PL>-based distributions, use the PREFIX and LIB options -when generating Makefiles: - - perl Makefile.PL PREFIX=/mydir/perl LIB=/mydir/perl/lib - -You can set this in your CPAN.pm configuration so modules automatically install -in your private library directory when you use the CPAN.pm shell: - - % cpan - cpan> o conf makepl_arg PREFIX=/mydir/perl,LIB=/mydir/perl/lib - cpan> o conf commit - -For C<Build.PL>-based distributions, use the --install_base option: - - perl Build.PL --install_base /mydir/perl - -You can configure CPAN.pm to automatically use this option too: - - % cpan - cpan> o conf mbuild_arg --install_base /mydir/perl - cpan> o conf commit - -=head2 How do I add the directory my program lives in to the module/library search path? - -(contributed by brian d foy) - -If you know the directory already, you can add it to C<@INC> as you would -for any other directory. You might <use lib> if you know the directory -at compile time: - - use lib $directory; - -The trick in this task is to find the directory. Before your script does -anything else (such as a C<chdir>), you can get the current working -directory with the C<Cwd> module, which comes with Perl: - - BEGIN { - use Cwd; - our $directory = cwd; - } - - use lib $directory; - -You can do a similar thing with the value of C<$0>, which holds the -script name. That might hold a relative path, but C<rel2abs> can turn -it into an absolute path. Once you have the - - BEGIN { - use File::Spec::Functions qw(rel2abs); - use File::Basename qw(dirname); - - my $path = rel2abs( $0 ); - our $directory = dirname( $path ); - } - - use lib $directory; - -The C<FindBin> module, which comes with Perl, might work. It searches -through C<$ENV{PATH}> (so your script has to be in one of those -directories). You can then use that directory (in C<$FindBin::Bin>) -to locate nearby directories you want to add: - - use FindBin; - use lib "$FindBin::Bin/../lib"; - -=head2 How do I add a directory to my include path (@INC) at runtime? - -Here are the suggested ways of modifying your include path, including -environment variables, run-time switches, and in-code statements: - -=over 4 - -=item the PERLLIB environment variable - - $ export PERLLIB=/path/to/my/dir - $ perl program.pl - -=item the PERL5LIB environment variable - - $ export PERL5LIB=/path/to/my/dir - $ perl program.pl - -=item the perl -Idir command line flag - - $ perl -I/path/to/my/dir program.pl - -=item the use lib pragma: - - use lib "$ENV{HOME}/myown_perllib"; - -=back - -The last is particularly useful because it knows about machine -dependent architectures. The lib.pm pragmatic module was first -included with the 5.002 release of Perl. - -=head2 What is socket.ph and where do I get it? - -It's a Perl 4 style file defining values for system networking -constants. Sometimes it is built using h2ph when Perl is installed, -but other times it is not. Modern programs C<use Socket;> instead. - -=head1 REVISION - -Revision: $Revision: 10183 $ - -Date: $Date: 2007-11-07 09:35:12 +0100 (Wed, 07 Nov 2007) $ - -See L<perlfaq> for source control details and availability. - -=head1 AUTHOR AND COPYRIGHT - -Copyright (c) 1997-2007 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. |