From: Jarkko Hietaniemi Date: Mon, 1 Jan 2001 18:10:58 +0000 (+0000) Subject: Podify README.mpeix (a new version from the web), X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=ab648d5eb0a7286231b7140c37b59641898641f5;p=p5sagit%2Fp5-mst-13.2.git Podify README.mpeix (a new version from the web), add a dummy NAME to Carp::Heavy, regen toc. p4raw-id: //depot/perl@8291 --- diff --git a/README.mpeix b/README.mpeix index 9e0b51d..7976db5 100644 --- a/README.mpeix +++ b/README.mpeix @@ -1,260 +1,675 @@ -Perl/iX for HP 3000 MPE +If you read this file _as_is_, just ignore the funny characters you +see. It is written in the POD format (see perlpod manpage) which is +specially designed to be readable as is. -http://www.cccd.edu/~markb/perlix.html -Perl language for MPE -Last updated July 15, 1998 @ 2030 UTC +=head1 NAME - ------------------------------------------------------------------------ +README.mpeix - Perl/iX for HP e3000 MPE + +=head1 SYNOPSIS -What's New + http://www.bixby.org/mark/perlix.html + Perl language for MPE + Last updated June 2, 2000 @ 0400 UTC + +=head1 NOTE - * July 15, 1998 - o Changed startperl to #!/PERL/PUB/perl so that Perl will recognize - scripts more easily and efficiently. - * July 8, 1998 - o Updated to version 5.004_70 (internal developer release) which is - now MPE-ready. The next public freeware release of Perl should - compile "straight out of the box" on MPE. Note that this version - of Perl/iX was strictly internal to me and never publicly - released. Note that BIND/iX is now required (well, the include - files and libbind.a) if you wish to compile Perl/iX. - * November 6, 1997 - o Updated to version 5.004_04. No changes in MPE-specific - functionality. +This is a podified version of the above-mentioned web page, +podified by Jarkko Hietaniemi 2001-Jan-01. - ------------------------------------------------------------------------ +=head1 What's New -Welcome +June 1, 2000 + +=over 4 -This is the official home page for the HP 3000 MPE port of the Perl -scripting language which gives you all of the power of C, awk, sed, and sh -in a single language. Check here for the latest news, implemented -functionality, known bugs, to-do list, etc. Status reports about major -milestones will also be posted to the HP3000-L mailing list and its -associated gatewayed newsgroup comp.sys.hp.mpe. +=item * -I'm doing this port because I can't live without Perl on the HPUX machines -that I administer for the Coast Community College District, and I want to -have the same power available to me on MPE. +Rebuilt to be compatible with mod_perl. If you plan on using +mod_perl, you MUST download and install this version of Perl/iX! + +=item * -Please send your comments, questions, and bug reports directly to me, Mark -Bixby, by e-mailing to markb@cccd.edu. Or just post them to HP3000-L. You -can also telephone me at +1 714 438-4647 Monday-Friday 0815-1745 PDT -(1615-0145 UTC). +bincompat5005="undef": sorry, but you will have to recompile any +binary 5.005 extensions that you may be using (if any; there is no +5.005 code in what you download from bixby.org) +uselargefiles="undef": not available in MPE for POSIX files yet. + +=item * -The platform I'm using to do this port is an HP 3000 969KS200 running -MPE/iX 5.5 and using the gcc 2.8 compiler from -http://www.interex.org/sources/freeware.html. +Now bundled with various add-on packages: -The combined porting wisdom from all of my ports can be found in my MPE/iX -Porting Guide. +=over 8 - ------------------------------------------------------------------------ +=item * -System Requirements +libnet (http://www.gbarr.demon.co.uk/libnet/FAQ.html) - * MPE/iX 5.5 or later. This version of Perl/iX does NOT run on MPE/iX - 5.0 or earlier, nor does it run on "classic" MPE/V machines. - * The Perl binary requires that you must have converted your NMRL - libraries in /lib/lib*.a and /usr/lib/lib*.a to NMXL libraries - /lib/lib*.sl and /usr/lib/lib*.sl via the LIBSHP3K script that comes - with the GNUCORE portion of the FREEWARE tape. - * If you wish to recompile Perl, you must install both GNUCORE and - GNUGCC from the FREEWARE tape. - * Perl/iX will be happier if you install the MPEKX76A additional POSIX - filename characters patch, but this is optional. - * If you will be compiling Perl/iX yourself, you will also need the - /BIND/PUB/include and /BIND/PUB/lib portions of BIND/iX. +=item * - ------------------------------------------------------------------------ +libwww-perl (LWP) which lets Perl programs behave like web browsers: + + 1. #!/PERL/PUB/perl + 2. use LWP::Simple; + 3. $doc = get('http://www.bixby.org/mark/perlix.html'); # reads the + web page into variable $doc + +(http://www.bixby.org/mark/perlix.html) -Demos +=item * -Here is a brief selection of some sample Perl/iX uses: +mod_perl (just the perl portion; the actual DSO will be released +soon with Apache/iX 1.3.12 from bixby.org). This module allows you to +write high performance persistent Perl CGI scripts and all sorts of +cool things. (http://perl.apache.org/) + +and much much more hiding under /PERL/PUB/.cpan/ + +=item * - * A web feedback CGI form that lets a web browser user enter some data - and send e-mail to the person responsible for reading the feedback - comments. The CGI is written in Perl and requires Sendmail/iX. +The CPAN module now works for automatic downloading and +installing of add-on packages: - ------------------------------------------------------------------------ + 1. export FTP_PASSIVE=1 + 2. perl -MCPAN -e shell + 3. Ignore any terminal I/O related complaints! + +(http://theoryx5.uwinnipeg.ca/CPAN/data/perl/CPAN.html) -How to Obtain Perl/iX +=back - 1. Download Perl using either FTP.ARPA.SYS or some other client - 2. Extract the installation script - 3. Edit the installation script - 4. Run the installation script +=back + +May 20, 2000 + +=over 4 + +=item * + +Updated to version 5.6.0. Builds straight out of the box on MPE/iX. + +=item * + +Perl's getpwnam() function which had regressed to being +unimplemented on MPE is now implemented once again. + +=back + +September 17, 1999 + +=over 4 + +=item * + +Migrated from cccd.edu to bixby.org. + +=back + +=head1 Welcome + +This is the official home page for the HP e3000 MPE/iX +(http://www.businessservers.hp.com/) port of the Perl scripting +language (http://www.perl.com/) which gives you all of the power of C, +awk, sed, and sh in a single language. Check here for the latest news, +implemented functionality, known bugs, to-do list, etc. Status reports +about major milestones will also be posted to the HP3000-L mailing list +(http://www.lsoft.com/scripts/wl.exe?SL1=HP3000-L&H=RAVEN.UTC.EDU) and +its associated gatewayed newsgroup comp.sys.hp.mpe. + +I'm doing this port because I can't live without Perl on the Unix +machines that I administer, and I want to have the same power +available to me on MPE. + +Please send your comments, questions, and bug reports directly to me, +Mark Bixby (http://www.bixby.org/mark/), by e-mailing to +mark@bixby.org. Or just post them to HP3000-L. + +The platform I'm using to do this port is an HP 3000 957RX running +MPE/iX 6.0 and using the GNU gcc C compiler +(http://jazz.external.hp.com/src/gnu/gnuframe.html). + +The combined porting wisdom from all of my ports can be found in my +MPE/iX Porting Guide (http://www.bixby.org/mark/porting.html). + +IMPORTANT NOTICE: Yes, I do work for the HP CSY R&D lab, but ALL of +the software you download from bixby.org is my personal freeware that +is NOT supported by HP. + +=head1 System Requirements + +=over 4 + +=item * + +MPE/iX 5.5 or later. This version of Perl/iX does NOT run on +MPE/iX 5.0 or earlier, nor does it run on "classic" MPE/V machines. + +=item * + +If you wish to recompile Perl, you must install both GNUCORE and +GNUGCC from jazz (http://jazz.external.hp.com/src/gnu/gnuframe.html). + +=item * + +Perl/iX will be happier on MPE/iX 5.5 if you install the MPEKX40B +extended POSIX filename characters patch, but this is optional. + +=item * + +Patch LBCJXT6A is required on MPE/iX 5.5 machines in order to +prevent Perl/iX from dying with an unresolved external reference +to _getenv_libc. + +=item * + +If you will be compiling Perl/iX yourself, you will also need +Syslog/iX (http://www.bixby.org/mark/syslogix.html) and the +/BIND/PUB/include and /BIND/PUB/lib portions of BIND/iX +(http://www.bixby.org/mark/bindix.html). + +=back + +=head1 How to Obtain Perl/iX + +=over 4 + +=item 1. + +Download Perl using either FTP.ARPA.SYS or some other client + +=item 2. + +Extract the installation script + +=item 3. + +Edit the installation script + +=item 4. + +Run the installation script + +=item 5. + +Convert your *.a system archive libraries to *.sl shared libraries + +=back Download Perl using FTP.ARPA.SYS from your HP 3000 (the preferred method)..... - -:HELLO MANAGER.SYS -:XEQ FTP.ARPA.SYS -open ftp.cccd.edu -anonymous -your@email.address -bytestream -cd /pub/mpe -get perl5.005.tar.Z /tmp/perl.tar.Z -exit + + :HELLO MANAGER.SYS + :XEQ FTP.ARPA.SYS + open ftp.bixby.org + anonymous + your@email.address + bytestream + cd /pub/mpe + get perl-5.6.0-mpe.tar.Z /tmp/perl.tar.Z;disc=2147483647 + exit .....Or download using some other generic web or ftp client (the alternate method) - + Download the following files (make sure that you use "binary mode" or whatever client feature that is 8-bit clean): - * Perl from http://www.cccd.edu/ftp/pub/mpe/perl5.005.tar.Z or - ftp://ftp.cccd.edu/pub/mpe/perl5.005.tar.Z +=over 4 + +=item * + +Perl from + + http://www.bixby.org/ftp/pub/mpe/perl-5.6.0-mpe.tar.Z + +or + + ftp://ftp.bixby.org/pub/mpe/perl-5.6.0-mpe.tar.Z + +=item * Upload those files to your HP 3000 in an 8-bit clean bytestream manner to: - * /tmp/perl.tar.Z + /tmp/perl.tar.Z + +=item * Then extract the installation script (after both download methods) + + :CHDIR /tmp + :XEQ TAR.HPBIN.SYS 'xvfopz /tmp/perl.tar.Z INSTALL' -:CHDIR /tmp -:XEQ TAR.HPBIN.SYS 'xvfopz /tmp/perl.tar.Z INSTALL' +=item * Edit the installation script + +Examine the accounting structure creation commands and modify if +necessary (adding additional capabilities, choosing a non-system +volume set, etc). -Examine the accounting structure creation commands and modify if necessary -(adding additional capabilities, choosing a non-system volume set, etc). + :XEQ VI.HPBIN.SYS /tmp/INSTALL -:XEQ VI.HPBIN.SYS /tmp/INSTALL - -Run the installation script +=item * +Run the installation script. + The accounting structure will be created and then all files will be extracted from the archive. -:XEQ SH.HPBIN.SYS /tmp/INSTALL - - ------------------------------------------------------------------------ - -Distribution Contents Highlights - -README - The file you're reading now. -INSTALL - Perl/iX Installation script. -PERL - Perl NMPRG executable. A version-numbered backup copy also exists. - You might wish to "ln -s /PERL/PUB/PERL /usr/local/bin/perl". -lib/ - Perl libraries, both core and add-on. -man/ - Perl man page documentation. -public_html/feedback.cgi - Sample feedback CGI form written in Perl. -src/perl5.005 - Source code. - - ------------------------------------------------------------------------ - -How to Compile Perl/iX - - 1. cd src/perl5.005 - 2. Read the INSTALL file for the official instructions - 3. ./Configure - 4. make - 5. ./mpeix/relink - 6. make test (expect 31 out of 5899 subtests to fail, mostly due to MPE - not supporting hard links and handling exit() return codes improperly) - 7. make install - 8. Optionally create symbolic links that point to the Perl executable, - i.e. ln -s /usr/local/bin/perl /PERL/PUB/PERL + :XEQ SH.HPBIN.SYS /tmp/INSTALL + +=item * + +Convert your *.a system archive libraries to *.sl shared libraries + +You only have to do this ONCE on your MPE/iX 5.5 machine in order to +convert /lib/lib*.a and /usr/lib/lib*.a libraries to their *.sl +equivalents. This step should not be necessary on MPE/iX 6.0 or later +machines because the 6.0 or later update process does it for you. + + :XEQ SH.HPBIN.SYS /PERL/PUB/LIBSHP3K + +=back + +=head1 Distribution Contents Highlights + +=over 4 + +=item README + +The file you're reading now. + +=item INSTALL + +Perl/iX Installation script. + +=item LIBSHP3K + +Script to convert *.a system archive libraries to *.sl shared libraries. + +=item PERL + +Perl NMPRG executable. A version-numbered backup copy also +exists. You might wish to "ln -s /PERL/PUB/PERL /usr/local/bin/perl". + +=item .cpan/ + +Much add-on source code downloaded with the CPAN module. + +=item lib/ + +Perl libraries, both core and add-on. + +=item man/ + +Perl man page documentation. + +=item public_html/feedback.cgi + +Sample feedback CGI form written in Perl. + +=item src/perl-5.6.0-mpe + +Source code. + +=back + +=head1 How to Compile Perl/iX + +=over 4 + +=item 1. + +cd src/perl-5.6.0-mpe + +=item 2. + +Read the INSTALL file for the official instructions + +=item 3. + +./Configure -d + +=item 4. + +make + +=item 5. + +./mpeix/relink + +=item 6. + +make test (expect approximately 15 out of 11306 subtests to fail, +mostly due to MPE not supporting hard links, UDP socket problems, +and handling exit() return codes improperly) + +=item 7. + +make install + +=item 8. + +Optionally create symbolic links that point to the Perl +executable, i.e. ln -s /PERL/PUB/PERL /usr/local/bin/perl + +=back The summary test results from "cd t; ./perl -I../lib harness": -Failed Test Status Wstat Total Fail Failed List of failed -------------------------------------------------------------------------------- -io/fs.t 26 8 30.77% 2-5, 7-9, 11 -io/pipe.t 12 2 16.67% 11-12 -lib/posix.t 18 1 5.56% 12 -op/die_exit.t 16 16 100.00% 1-16 -op/exec.t 8 2 25.00% 5-6 -op/stat.t 58 2 3.45% 3, 35 -Failed 6/183 test scripts, 96.72% okay. 31/5899 subtests failed, 99.47% okay. - - ------------------------------------------------------------------------ - -Getting Started with Perl/iX - -Create your Perl script files with "#!/PERL/PUB/perl" (or an equivalent -symbolic link) as the first line. Use the chmod command to make sure that -your script has execute permission. Run your script! - -If you want to use Perl to write web server CGI scripts, obtain and install -CGI.pm. Build CGI.pm and all other add-on modules below /PERL/PUB/src/. - -Be sure to take a look at the CPAN module list. A wide variety of free Perl -software is available. - - ------------------------------------------------------------------------ - -MPE/iX Implementation Considerations - -There some minor functionality issues to be aware of when comparing Perl -for Unix (Perl/UX) to Perl/iX: - - * MPE gcc/ld doesn't properly support linking NMPRG executables against - NMXL dynamic libraries, so you must manually run mpeix/relink after - each re-build of Perl. - * Perl/iX File::Copy will use MPE's /bin/cp command to copy files by - name in order to preserve file attributes like file code. - * MPE (and thus Perl/iX) lacks support for setgrent(), endgrent(), - setpwent(), endpwent(). - * MPE (and thus Perl/iX) lacks support for hard links. - * MPE requires GETPRIVMODE() in order to bind() to ports less than - 1024. Perl/iX will call GETPRIVMODE() automatically on your behalf if - you attempt to bind() to these low-numbered ports. Note that the - Perl/iX executable and the PERL account do not normally have CAP=PM, - so if you will be bind()-ing to these privileged ports, you will - manually need to add PM capability as appropriate. - * MPE requires that you bind() to an IP address of zero. Perl/iX - automatically replaces the IP address that you pass to bind() with a - zero. - * If you use Perl/iX fcntl() against a socket it will fail, because MPE - requires that you use sfcntl() instead. Perl/iX does not presently - support sfcntl(). - * MPE requires GETPRIVMODE() in order to setuid(). There are too many - calls to setuid() within Perl/iX, so I have not attempted an automatic - GETPRIVMODE() solution similar to bind(). - - ------------------------------------------------------------------------ - -Known Bugs Under Investigation - - * None - - ------------------------------------------------------------------------ - -To-Do List - - * Make setuid()/setgid() support work. - * Make sure that fcntl() against a socket descriptor is redirected to - sfcntl(). - * Add support for Berkeley DB once I've finished porting Berkeley DB. - * Write an MPE XS extension library containing miscellaneous important - MPE functions like GETPRIVMODE(), GETUSERMODE(), and sfcntl(). - - ------------------------------------------------------------------------ - -Change History - - * October 16, 1997 - o Added Demos section to the Perl/iX home page so you can see some - sample Perl applications running on my 3000. - * October 3, 1997 - o Added System Requirements section to the Perl/iX home page just - so the prerequisites stand out more. Various other home page - tweaks. - * October 2, 1997 - o Initial public release. - * September 1997 - o Porting begins. - - ------------------------------------------------------------------------ - -Mark Bixby, markb@cccd.edu + Failed Test Status Wstat Total Fail Failed List of failed + --------------------------------------------------------------------------- + io/fs.t 29 8 27.59% 2-5, 7-9, 11 + io/openpid.t 10 1 10.00% 7 + lib/io_sock.t 14 1 7.14% 13 + lib/io_udp.t 7 2 28.57% 3, 5 + lib/posix.t 27 1 3.70% 12 + op/lex_assign.t 187 1 0.53% 13 + op/stat.t 58 1 1.72% 3 + 15 tests and 94 subtests skipped. + Failed 7/236 test scripts, 97.03% okay. 15/11306 subtests failed, 99.87% okay. + +=head1 Getting Started with Perl/iX + +Create your Perl script files with "#!/PERL/PUB/perl" (or an +equivalent symbolic link) as the first line. Use the chmod command to +make sure that your script has execute permission. Run your script! + +Be sure to take a look at the CPAN module list +(http://www.cpan.org/CPAN.html). A wide variety of free Perl software +is available. You can automatically download these packages by using +the CPAN module (http://theoryx5.uwinnipeg.ca/CPAN/data/perl/CPAN.html). + +=head1 MPE/iX Implementation Considerations + +There some minor functionality issues to be aware of when comparing +Perl for Unix (Perl/UX) to Perl/iX: + +=over 4 + +=item * + +MPE gcc/ld doesn't properly support linking NMPRG executables against +NMXL dynamic libraries, so you must manually run mpeix/relink after +each re-build of Perl. + +=item * + +Perl/iX File::Copy will use MPE's /bin/cp command to copy files by +name in order to preserve file attributes like file code. + +=item * + +MPE (and thus Perl/iX) lacks support for setgrent(), endgrent(), +setpwent(), endpwent(). + +=item * + +MPE (and thus Perl/iX) lacks support for hard links. + +=item * + +MPE requires GETPRIVMODE() in order to bind() to ports less than 1024. +Perl/iX will call GETPRIVMODE() automatically on your behalf if you +attempt to bind() to these low-numbered ports. Note that the Perl/iX +executable and the PERL account do not normally have CAP=PM, so if you +will be bind()-ing to these privileged ports, you will manually need +to add PM capability as appropriate. + +=item * + +MPE requires that you bind() to an IP address of zero. Perl/iX +automatically replaces the IP address that you pass to bind() with +a zero. + +=item * + +If you use Perl/iX fcntl() against a socket it will fail, because MPE +requires that you use sfcntl() instead. Perl/iX does not presently +support sfcntl(). + +=item * + +MPE requires GETPRIVMODE() in order to setuid(). There are too many +calls to setuid() within Perl/iX, so I have not attempted an automatic +GETPRIVMODE() solution similar to bind(). + +=back + +=head1 Known Bugs Under Investigation + +None. + +=head1 To-Do List + +=over 4 + +=item * + +Make setuid()/setgid() support work. + +=item * + +Make sure that fcntl() against a socket descriptor is redirected to sfcntl(). + +=item * + +Add support for Berkeley DB once I've finished porting Berkeley DB. + +=item * + +Write an MPE XS extension library containing miscellaneous important +MPE functions like GETPRIVMODE(), GETUSERMODE(), and sfcntl(). + +=back + +=head1 Change History + +May 6, 1999 + +=over 4 + +=item * + +Patch LBCJXT6A is required on MPE/iX 5.5 machines in order to prevent +Perl/iX from dying with an unresolved external reference to _getenv_libc. + +=back + +April 7, 1999 + +=over 4 + +=item * + +Updated to version 5.005_03. + +=item * + +The official source distribution once again compiles "straight out +of the box" for MPE. + +=item * + +The current incarnation of the 5.5 POSIX filename extended +characters patch is now MPEKX40B. + +=item * + +The LIBSHP3K *.a -> *.sl library conversion script is now included +as /PERL/PUB/LIBSHP3K. + +=back + +November 20, 1998 + +=over 4 + +=item * + +Updated to version 5.005_02. + +=item * + +Fixed a DynaLoader bug that was unable to load symbols from relative +path name libraries. + +=item * + +Fixed a .xs compilation bug where the mpeixish.sh include file wasn't +being installed into the proper directory. + +=item * + +All bugfixes will be submitted back to the official Perl developers. + +=item * + +The current incarnation of the POSIX filename extended characters +patch is now MPEKXJ3A. + +=back + +August 14, 1998 + +=over 4 + +=item * + +The previous POSIX filename extended characters patch MPEKX44C has +been superseded by MPEKXB5A. + +=back + +August 7, 1998 + +=over 4 + +=item * + +The previous POSIX filename extended characters patch MPEKX76A has +been superseded by MPEKX44C. + +=over 4 + +=back + +July 28, 1998 + +=item * + +Updated to version 5.005_01. + +=back + +July 23, 1998 + +=over 4 + +=item * + +Updated to version 5.005 (production release). The public +freeware sources are now 100% MPE-ready "straight out of the box". + +=back + +July 17, 1998 + +=over 4 + +=item * + +Updated to version 5.005b1 (public beta release). The public +freeware sources are now 99.9% MPE-ready. By installing and +testing this beta on your own HP3000, you will be helping to +insure that the final release of 5.005 will be 100% MPE-ready and +100% bug free. + +=item * + +My MPE binary release is now extracted using my standard INSTALL script. + +=back + +July 15, 1998 + +=over 4 + +=item * + +Changed startperl to #!/PERL/PUB/perl so that Perl will recognize +scripts more easily and efficiently. + +=back + +July 8, 1998 + +=over 4 + +=item * + +Updated to version 5.004_70 (internal developer release) which is now +MPE-ready. The next public freeware release of Perl should compile +"straight out of the box" on MPE. Note that this version of Perl/iX +was strictly internal to me and never publicly released. Note that +[21]BIND/iX is now required (well, the include files and libbind.a) if +you wish to compile Perl/iX. + +=back + +November 6, 1997 + +=over 4 + +=item * + +Updated to version 5.004_04. No changes in MPE-specific functionality. + +=back + +October 16, 1997 + +=over 4 + +=item * + +Added Demos section to the Perl/iX home page so you can see some +sample Perl applications running on my 3000. + +=back + +October 3, 1997 + +=over 4 + +=item * + +Added System Requirements section to the Perl/iX home page just so the +prerequisites stand out more. Various other home page tweaks. + +=back + +October 2, 1997 + +=over 4 + +=item * + +Initial public release. + +=back + +September 1997 + +=over 4 + +=item * + +Porting begins. + +=back + +=head1 Author + +Mark Bixby, mark@bixby.org + diff --git a/lib/Carp/Heavy.pm b/lib/Carp/Heavy.pm index dac9c75..b551560 100644 --- a/lib/Carp/Heavy.pm +++ b/lib/Carp/Heavy.pm @@ -1,6 +1,12 @@ # Carp::Heavy uses some variables in common with Carp. package Carp; +=head1 NAME + +Carp heavy machinery - no user serviceable parts inside + +=cut + # use strict; # not yet # On one line so MakeMaker will see it. diff --git a/pod/buildtoc.PL b/pod/buildtoc.PL index ba15e44..f2dba95 100644 --- a/pod/buildtoc.PL +++ b/pod/buildtoc.PL @@ -157,6 +157,7 @@ if (-d "pod") { perlepoc perlhpux perlmachten + perlmpeix perlos2 perlos390 perlposix-bc @@ -174,6 +175,7 @@ if (-d "pod") { perlepoc perlhpux perlmachten + perlmpeix perlos2 perlos390 perlposix-bc diff --git a/pod/perl.pod b/pod/perl.pod index 0d2c1c3..4e08cc8 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -111,6 +111,7 @@ For ease of access, the Perl manual has been split up into several sections: perlepoc Perl notes for EPOC perlhpux Perl notes for HP-UX perlmachten Perl notes for Power MachTen + perlmpeix Perl notes for MPE/iX perlos2 Perl notes for OS/2 perlos390 Perl notes for OS/390 perlposix-bc Perl notes for POSIX-BC diff --git a/pod/perltoc.pod b/pod/perltoc.pod index 8927211..c0750e8 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -19,16 +19,6 @@ through to locate the proper section you're looking for. =item DESCRIPTION -modularity and reusability using innumerable modules, embeddable and -extensible, roll-your-own magic variables (including multiple simultaneous -DBM implementations), subroutines can now be overridden, autoloaded, and -prototyped, arbitrarily nested data structures and anonymous functions, -object-oriented programming, compilability into C code or Perl bytecode, -support for light-weight processes (threads), support for -internationalization, localization, and Unicode, lexical scoping, regular -expression enhancements, enhanced debugger and interactive Perl -environment, with integrated editor support, POSIX 1003.1 compliant library - =item AVAILABILITY =item ENVIRONMENT @@ -320,7 +310,7 @@ DIAGNOSTICS, BUGS, NOTES =item perlfaq - frequently asked questions about Perl ($Date: 1999/05/23 20:38:02 $) -DESCRIPTION +DESCRIPTION, Where to get this document, How to contribute =back @@ -511,10 +501,6 @@ regular expressions =item When to Still Use local() -1. You need to give a global variable a temporary value, especially $_, 2. -You need to create a local file or directory handle or a local function, 3. -You want to temporarily change just one element of an array or hash - =item Pass by Reference =item Prototypes @@ -778,13 +764,6 @@ more elaborate constructs =item Using character classes -\d is a digit and represents [0-9], \s is a whitespace character and -represents [\ \t\r\n\f], \w is a word character (alphanumeric or _) and -represents [0-9a-zA-Z_], \D is a negated \d; it represents any character -but a digit [^0-9], \S is a negated \s; it represents any non-whitespace -character [^\s], \W is a negated \w; it represents any non-word character -[^\w], The period '.' matches any character but "\n" - =item Matching this or that =item Grouping things and hierarchical matching @@ -1262,90 +1241,16 @@ ${^WIDE_SYSTEM_CALLS}, $EXECUTABLE_NAME, $^X, $ARGV, @ARGV, @INC, @_, %INC, =item Using character classes -\d is a digit and represents [0-9], \s is a whitespace character and -represents [\ \t\r\n\f], \w is a word character (alphanumeric or _) and -represents [0-9a-zA-Z_], \D is a negated \d; it represents any character -but a digit [^0-9], \S is a negated \s; it represents any non-whitespace -character [^\s], \W is a negated \w; it represents any non-word character -[^\w], The period '.' matches any character but "\n", no modifiers (//): -Default behavior. C<'.'> matches any character except C<"\n">. C<^> -matches only at the beginning of the string and C<$> matches only at the -end or before a newline at the end, s modifier (//s): Treat string as a -single long line. C<'.'> matches any character, even C<"\n">. C<^> -matches only at the beginning of the string and C<$> matches only at the -end or before a newline at the end, m modifier (//m): Treat string as a set -of multiple lines. C<'.'> matches any character except C<"\n">. C<^> and -C<$> are able to match at the start or end of I line within the -string, both s and m modifiers (//sm): Treat string as a single long line, -but detect multiple lines. C<'.'> matches any character, even C<"\n">. -C<^> and C<$>, however, are able to match at the start or end of I -line within the string - =item Matching this or that =item Grouping things and hierarchical matching -0 Start with the first letter in the string 'a', 1 Try the first -alternative in the first group 'abd', 2 Match 'a' followed by 'b'. So far -so good, 3 'd' in the regexp doesn't match 'c' in the string - a dead end. -So backtrack two characters and pick the second alternative in the first -group 'abc', 4 Match 'a' followed by 'b' followed by 'c'. We are on a roll -and have satisfied the first group. Set $1 to 'abc', 5 Move on to the -second group and pick the first alternative 'df', 6 Match the 'd', 7 'f' in -the regexp doesn't match 'e' in the string, so a dead end. Backtrack one -character and pick the second alternative in the second group 'd', 8 'd' -matches. The second grouping is satisfied, so set $2 to 'd', 9 We are at -the end of the regexp, so we are done! We have matched 'abcd' out of the -string "abcde" - =item Extracting matches =item Matching repetitions -C = match 'a' 1 or 0 times, C = match 'a' 0 or more times, i.e., -any number of times, C = match 'a' 1 or more times, i.e., at least -once, C = match at least C times, but not more than C times, -C = match at least C or more times, C = match exactly C -times, Principle 0: Taken as a whole, any regexp will be matched at the -earliest possible position in the string, Principle 1: In an alternation -C, the leftmost alternative that allows a match for the whole -regexp will be the one used, Principle 2: The maximal matching quantifiers -C, C<*>, C<+> and C<{n,m}> will in general match as much of the string -as possible while still allowing the whole regexp to match, Principle 3: If -there are two or more elements in a regexp, the leftmost greedy quantifier, -if any, will match as much of the string as possible while still allowing -the whole regexp to match. The next leftmost greedy quantifier, if any, -will try to match as much of the string remaining available to it as -possible, while still allowing the whole regexp to match. And so on, until -all the regexp elements are satisfied, C = match 'a' 0 or 1 times. Try -0 first, then 1, C = match 'a' 0 or more times, i.e., any number of -times, but as few times as possible, C = match 'a' 1 or more times, -i.e., at least once, but as few times as possible, C = match at -least C times, not more than C times, as few times as possible, -C = match at least C times, but as few times as possible, -C = match exactly C times. Because we match exactly C times, -C is equivalent to C and is just there for notational -consistency, Principle 3: If there are two or more elements in a regexp, -the leftmost greedy (non-greedy) quantifier, if any, will match as much -(little) of the string as possible while still allowing the whole regexp to -match. The next leftmost greedy (non-greedy) quantifier, if any, will try -to match as much (little) of the string remaining available to it as -possible, while still allowing the whole regexp to match. And so on, until -all the regexp elements are satisfied, 0 Start with the first letter in the -string 't', 1 The first quantifier '.*' starts out by matching the whole -string 'the cat in the hat', 2 'a' in the regexp element 'at' doesn't match -the end of the string. Backtrack one character, 3 'a' in the regexp -element 'at' still doesn't match the last letter of the string 't', so -backtrack one more character, 4 Now we can match the 'a' and the 't', 5 -Move on to the third element '.*'. Since we are at the end of the string -and '.*' can match 0 times, assign it the empty string, 6 We are done! - =item Building a regexp -specifying the task in detail,, breaking down the problem into smaller -parts,, translating the small parts into regexps,, combining the regexps,, -and optimizing the final combined regexp - =item Using regular expressions in Perl =back @@ -2251,15 +2156,6 @@ localization) =item SECURITY -B (C, C, C, C and C):, -B (with C<\l>, C<\L>, C<\u> or C<\U>), -B (C):, B (C):, -B (printf() and write()):, B (lc(), lcfirst(), uc(), ucfirst()):, B (localeconv(), strcoll(), strftime(), strxfrm()):, B (isalnum(), isalpha(), isdigit(), isgraph(), -islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit()): - =item ENVIRONMENT PERL_BADLANG, LC_ALL, LANGUAGE, LC_CTYPE, LC_COLLATE, LC_MONETARY, @@ -2546,20 +2442,8 @@ User::pwent =item CPAN -Language Extensions and Documentation Tools, Development Support, Operating -System Interfaces, Networking, Device Control (modems) and InterProcess -Communication, Data Types and Data Type Utilities, Database Interfaces, -User Interfaces, Interfaces to / Emulations of Other Programming Languages, -File Names, File Systems and File Locking (see also File Handles), String -Processing, Language Text Processing, Parsing, and Searching, Option, -Argument, Parameter, and Configuration File Processing, -Internationalization and Locale, Authentication, Security, and Encryption, -World Wide Web, HTML, HTTP, CGI, MIME, Server and Daemon Utilities, -Archiving and Compression, Images, Pixmap and Bitmap Manipulation, Drawing, -and Graphing, Mail and Usenet News, Control Flow Utilities (callbacks and -exceptions etc), File Handle and Input/Output Stream Utilities, -Miscellaneous Modules, Africa, Asia, Australasia, Central America, Europe, -North America, South America +Africa, Asia, Australasia, Central America, Europe, North America, South +America =item Modules: Creation, Use, and Abuse @@ -2588,12 +2472,6 @@ to ::, Converts die(...) to croak(...), Several other minor changes =item Guidelines for Reusing Application Code -Complete applications rarely belong in the Perl Module Library, Many -applications contain some Perl code that could be reused, Break-out the -reusable code into one or more separate module files, Take the opportunity -to reconsider and redesign the interfaces, In some cases the 'application' -can then be reduced to a small - =back =item NOTE @@ -2959,11 +2837,7 @@ the tag =item How can I remove duplicate elements from a list or array? -a) If @in is sorted, and you want @out to be sorted: (this assumes all true -values in the array), b) If you don't know whether @in is sorted:, c) Like -(b), but @in contains only small integers:, d) A way to do (b) without any -loops or greps:, e) Like (d), but @in contains only small positive -integers: +a), b), c), d), e) =item How can I tell whether a list or array contains a certain element? @@ -3545,14 +3419,6 @@ Perl?>, B, B =item ROADMAP -Compiling your C program, Adding a Perl interpreter to your C program, -Calling a Perl subroutine from your C program, Evaluating a Perl statement -from your C program, Performing Perl pattern matches and substitutions from -your C program, Fiddling with the Perl stack from your C program, -Maintaining a persistent interpreter, Maintaining multiple interpreter -instances, Using Perl modules, which themselves use C libraries, from your -C program, Embedding Perl under Win32 - =item Compiling your C program =item Adding a Perl interpreter to your C program @@ -4719,15 +4585,6 @@ I =item Performance Enhancements -sort() has been changed to use mergesort internally as opposed to the -earlier quicksort. For very small lists this may result in slightly slower -sorting times, but in general the speedup should be at least 20%. -Additional bonuses are that the worst case behaviour of sort() is now -better (in computer science terms it now runs in time O(N log N), as -opposed to quicksort's Theta(N**2) worst-case run time behaviour), and that -sort() is now stable (meaning that elements with identical keys will stay -ordered as they were before the sort) - =item Installation and Configuration Improvements =over 4 @@ -4738,9 +4595,6 @@ ordered as they were before the sort) =item Selected Bug Fixes -sort() arguments are now compiled in the right wantarray context (they were -accidentally using the context of the sort() itself) - =over 4 =item Platform Specific Changes and Fixes @@ -5111,8 +4965,7 @@ Format of $English::PERL_VERSION is different, Literals of the form C<1.2.3> parse differently, Possibly changed pseudo-random number generator, Hashing function for hash keys has changed, C fails on read only values, Close-on-exec bit may be set on pipe and socket handles, -Writing C<"$$1"> to mean C<"${$}1"> is unsupported, delete(), values() and -C<\(%h)> operate on aliases to values, not copies, vec(EXPR,OFFSET,BITS) +Writing C<"$$1"> to mean C<"${$}1"> is unsupported, vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS, Text of some diagnostic output has changed, C<%@> has been removed, Parenthesized not() behaves like a list operator, Semantics of bareword prototype C<(*)> have changed, Semantics of bit @@ -5194,10 +5047,6 @@ to mean "${$}" is deprecated =item C Source Compatibility -Core sources now require ANSI C compiler, All Perl global variables must -now be referenced with an explicit prefix, Enabling threads has source -compatibility issues - =item Binary Compatibility =item Security fixes may affect compatibility @@ -5335,9 +5184,9 @@ Eval-group not allowed at run time, Explicit blessing to '' (assuming package main), Illegal hex digit ignored, No such array field, No such field "%s" in variable %s of type %s, Out of memory during ridiculously large request, Range iterator outside integer range, Recursive inheritance -detected while looking for method '%s' in package '%s', Reference found -where even-sized list expected, Undefined value assigned to typeglob, Use -of reserved word "%s" is deprecated, perl: warning: Setting locale failed +detected while looking for method '%s' %s, Reference found where even-sized +list expected, Undefined value assigned to typeglob, Use of reserved word +"%s" is deprecated, perl: warning: Setting locale failed =item Obsolete Diagnostics @@ -5534,14 +5383,14 @@ possible typo, Null picture in formline, Offset outside string, Out of memory!, Out of memory during request for %s, panic: frexp, Possible attempt to put comments in qw() list, Possible attempt to separate words with commas, Scalar value @%s{%s} better written as $%s{%s}, Stub found -while resolving method `%s' overloading `%s' in package `%s', Too late for -"B<-T>" option, untie attempted while %d inner references still exist, -Unrecognized character %s, Unsupported function fork, Use of "$$" to -mean "${$}" is deprecated, Value of %s can be "0"; test with -defined(), Variable "%s" may be unavailable, Variable "%s" will not stay -shared, Warning: something's wrong, Ill-formed logical name |%s| in -prime_env_iter, Got an error from DosAllocMem, Malformed PERLLIB_PREFIX, -PERL_SH_DIR too long, Process terminated by SIG%s +while resolving method `%s' overloading `%s' in %s, Too late for "B<-T>" +option, untie attempted while %d inner references still exist, Unrecognized +character %s, Unsupported function fork, Use of "$$" to mean +"${$}" is deprecated, Value of %s can be "0"; test with defined(), +Variable "%s" may be unavailable, Variable "%s" will not stay shared, +Warning: something's wrong, Ill-formed logical name |%s| in prime_env_iter, +Got an error from DosAllocMem, Malformed PERLLIB_PREFIX, PERL_SH_DIR too +long, Process terminated by SIG%s =item BUGS @@ -5741,6 +5590,50 @@ Source, Compiled Module Source, Perl Modules/Scripts =back +=head2 perldos - Perl under DOS, W31, W95. + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Prerequisites + +DJGPP, Pthreads + +=item Shortcomings of Perl under DOS + +=item Building + +=item Testing + +=item Installation + +=back + +=item BUILDING AND INSTALLING MODULES + +=over 4 + +=item Prerequisites + +=item Unpacking CPAN Modules + +=item Building Non-XS Modules + +=item Building XS Modules + +=back + +=item AUTHOR + +=item SEE ALSO + +=back + =head2 perlepoc, README.epoc - Perl for EPOC =over 4 @@ -5847,6 +5740,30 @@ op/lexassign.t, pragma/warnings.t =back +=head2 perlmpeix, README.mpeix - Perl/iX for HP e3000 MPE + +=head1 SYNOPSIS + +=over 4 + +=item What's New + +=item System Requirements + +=item How to Obtain Perl/iX + +=item Distribution Contents Highlights + +README, public_html/feedback.cgi, 4, 6 + +=item Getting Started with Perl/iX + +=item MPE/iX Implementation Considerations + +=item Change History + +=back + =head2 perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. =over 4 @@ -6357,6 +6274,48 @@ LIST, waitpid PID,FLAGS =back +=head2 perlwin32 - Perl under Win32 + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Setting Up + +Make, Command Shell, Borland C++, Microsoft Visual C++, Mingw32 with GCC + +=item Building + +=item Testing + +=item Installation + +=item Usage Hints + +Environment Variables, File Globbing, Using perl from the command line, +Building Extensions, Command-line Wildcard Expansion, Win32 Specific +Extensions, Running Perl Scripts, Miscellaneous Things + +=back + +=item BUGS AND CAVEATS + +=item AUTHORS + +Gary Ng E71564.1743@CompuServe.COME, Gurusamy Sarathy +Egsar@activestate.comE, Nick Ing-Simmons +Enick@ing-simmons.netE + +=item SEE ALSO + +=item HISTORY + +=back + =head1 PRAGMA DOCUMENTATION =head2 attrs - set/get attributes of a subroutine (deprecated) @@ -6849,6 +6808,19 @@ C, C, C =back +=head2 unicode::distinct - Perl pragma to strictly distinguish UTF8 data +and non-UTF data. + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item SEE ALSO + +=back + =head2 utf8 - Perl pragma to enable/disable UTF-8 in source code =over 4 @@ -7471,10 +7443,6 @@ output. =back =item CALLING CGI.PM ROUTINES -1. Use another name for the argument, if one is available. For example, --value is an alias for -values, 2. Change the capitalization, e.g. -Values, -3. Put quotes around the argument name, e.g. '-values' - =item CREATING A NEW QUERY OBJECT (OBJECT-ORIENTED STYLE): =item CREATING A NEW QUERY OBJECT FROM AN INPUT FILE @@ -7621,8 +7589,7 @@ B =item CREATING A CLICKABLE IMAGE BUTTON -B, 3. The third option (-align, optional) is an alignment -type, and may be TOP, BOTTOM or MIDDLE +B =item CREATING A JAVASCRIPT ACTION BUTTON @@ -7652,16 +7619,15 @@ the
tag =item FETCHING ENVIRONMENT VARIABLES B, B, B, B, -B, B, B Return the script -name as a partial URL, for self-refering scripts, B, B, B, B, B, +B, B, B, B, +B, B, B, B, B, B, B, B, B, B, B =item USING NPH SCRIPTS In the B statement, By calling the B method:, By using B<-nph> -parameters in the B and B statements: +parameters =item Server Push @@ -7984,20 +7950,7 @@ http firewall, ftp firewall, One way visibility, SOCKS, IP Masquerade =item FAQ -1) I installed a new version of module X but CPAN keeps saying, I -have the old version installed, 2) So why is UNINST=1 not the default?, 3) -I want to clean up my mess, and install a new perl along with all -modules I have. How do I go about it?, 4) When I install bundles or -multiple modules with one command there is too much output to keep -track of, 5) I am not root, how can I install a module in a personal -directory?, 6) How to get a package, unwrap it, and make a change before - building it?, 7) I installed a Bundle and had a couple of fails. When I - retried, everything resolved nicely. Can this be fixed to work -on first try?, 8) In our intranet we have many modules for internal use. -How can I integrate these modules with CPAN.pm but without uploading - the modules to CPAN?, 9) When I run CPAN's shell, I get error msg -about line 1 to 4, setting meta input/output via the /etc/inputrc -file, 10) Some authors have strange characters in their names +1), 2), 3), 4), 5), 6), 7), 8), 9), 10) =item BUGS @@ -8048,6 +8001,8 @@ module =back +=head2 Carp::Heavy, Carp heavy machinery - no user serviceable parts inside + =head2 Class::Struct - declare struct-like datatypes as Perl classes =over 4 @@ -10146,6 +10101,10 @@ $fh->print, $fh->printf, $fh->getline, $fh->getlines =over 4 +=item SYNOPSIS + + use Filter::Util::Call ; + =item DESCRIPTION =over 4 @@ -12476,6 +12435,23 @@ specification "%s", %s:%d: Unknown command paragraph "%s", Unknown escape: =back +=head2 Pod::Text::Overstrike - Convert POD data to formatted overstrike +text + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item BUGS + +=item SEE ALSO + +=item AUTHOR + +=back + =head2 Pod::Text::Termcap, Pod::Text::Color - Convert POD data to ASCII text with format escapes @@ -12931,12 +12907,6 @@ arrays =item EXAMPLES -0 a simple word, 1 multiple spaces are skipped because of our $delim, 2 use -of quotes to include a space in a word, 3 use of a backslash to include a -space in a word, 4 use of a backslash to remove the special meaning of a -double-quote, 5 another simple word (note the lack of effect of the -backslashed double-quote) - =item AUTHORS =back @@ -13292,8 +13262,7 @@ Win32::GetChipName(), Win32::GetCwd(), Win32::GetFullPathName(FILENAME), Win32::GetLastError(), Win32::GetLongPathName(PATHNAME), Win32::GetNextAvailDrive(), Win32::GetOSVersion(), Win32::GetShortPathName(PATHNAME), Win32::GetProcAddress(INSTANCE, -PROCNAME), Win32::GetTickCount(), Win32::InitiateSystemShutdown(MACHINE, -MESSAGE, TIMEOUT, FORCECLOSE, REBOOT), Win32::IsWinNT(), Win32::IsWin95(), +PROCNAME), Win32::GetTickCount(), Win32::IsWinNT(), Win32::IsWin95(), Win32::LoadLibrary(LIBNAME), Win32::LoginName(), Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID, SIDTYPE), Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE),