perl5.005_03

1 files changed, 1493 insertions, 0 deletions

diff --git a/gnu/usr.bin/perl/README.os2 b/gnu/usr.bin/perl/README.os2
new file mode 100644
index 00000000000..667423c382a
--- /dev/null
+++ b/gnu/usr.bin/perl/README.os2
@@ -0,0 +1,1493 @@
+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.
+
+=head1 NAME
+
+perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
+
+=head1 SYNOPSIS
+
+One can read this document in the following formats:
+
+	man perlos2
+	view perl perlos2
+	explorer perlos2.html
+	info perlos2
+
+to list some (not all may be available simultaneously), or it may
+be read I<as is>: either as F<README.os2>, or F<pod/perlos2.pod>.
+
+To read the F<.INF> version of documentation (B<very> recommended)
+outside of OS/2, one needs an IBM's reader (may be available on IBM
+ftp sites (?)  (URL anyone?)) or shipped with PC DOS 7.0 and IBM's
+Visual Age C++ 3.5.
+
+A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package
+
+  ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip
+
+in F<?:\JUST_ADD\view.exe>. This gives one an access to EMX's 
+F<.INF> docs as well (text form is available in F</emx/doc> in 
+EMX's distribution).
+
+Note that if you have F<lynx.exe> installed, you can follow WWW links
+from this document in F<.INF> format. If you have EMX docs installed 
+correctly, you can follow library links (you need to have C<view emxbook>
+working by setting C<EMXBOOK> environment variable as it is described
+in EMX docs).
+
+=cut
+
+Contents
+ 
+ perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. 
+
+      NAME 
+      SYNOPSIS 
+      DESCRIPTION 
+         -  Target 
+         -  Other OSes 
+         -  Prerequisites 
+         -  Starting Perl programs under OS/2 (and DOS and...)
+         -  Starting OS/2 (and DOS) programs under Perl 
+      Frequently asked questions 
+         -  I cannot run external programs 
+         -  I cannot embed perl into my program, or use perl.dll from my program. 
+         -  `` and pipe-open do not work under DOS. 
+         -  Cannot start find.exe "pattern" file
+      INSTALLATION 
+         -  Automatic binary installation 
+         -  Manual binary installation 
+         -  Warning 
+      Accessing documentation 
+         -  OS/2 .INF file 
+         -  Plain text 
+         -  Manpages 
+         -  HTML 
+         -  GNU info files 
+         -  .PDF files 
+         -  LaTeX docs 
+      BUILD 
+         -  Prerequisites 
+         -  Getting perl source 
+         -  Application of the patches 
+         -  Hand-editing 
+         -  Making 
+         -  Testing 
+         -  Installing the built perl 
+         -  a.out-style build 
+      Build FAQ 
+         -  Some / became \ in pdksh. 
+         -  'errno' - unresolved external 
+         -  Problems with tr 
+         -  Some problem (forget which ;-) 
+         -  Library ... not found 
+         -  Segfault in make 
+      Specific (mis)features of EMX port 
+         -  setpriority, getpriority 
+         -  system() 
+         -  extproc on the first line
+         -  Additional modules: 
+         -  Prebuilt methods: 
+         -  Misfeatures 
+         -  Modifications 
+      Perl flavors 
+         -  perl.exe 
+         -  perl_.exe 
+         -  perl__.exe 
+         -  perl___.exe 
+         -  Why strange names? 
+         -  Why dynamic linking? 
+         -  Why chimera build? 
+      ENVIRONMENT 
+         -  PERLLIB_PREFIX 
+         -  PERL_BADLANG 
+         -  PERL_BADFREE 
+         -  PERL_SH_DIR 
+         -  TMP or TEMP 
+      Evolution 
+         -  Priorities 
+         -  DLL name mangling 
+         -  Threading 
+         -  Calls to external programs 
+         -  Memory allocation 
+      AUTHOR 
+      SEE ALSO 
+  
+=head1 DESCRIPTION
+
+=head2 Target
+
+The target is to make OS/2 the best supported platform for
+using/building/developing Perl and I<Perl applications>, as well as
+make Perl the best language to use under OS/2. The secondary target is
+to try to make this work under DOS and Win* as well (but not B<too> hard).
+
+The current state is quite close to this target. Known limitations:
+
+=over 5
+
+=item *
+
+Some *nix programs use fork() a lot, but currently fork() is not
+supported after I<use>ing dynamically loaded extensions.
+
+=item *
+
+You need a separate perl executable F<perl__.exe> (see L<perl__.exe>)
+to use PM code in your application (like the forthcoming Perl/Tk).
+
+=item *
+
+There is no simple way to access WPS objects. The only way I know
+is via C<OS2::REXX> extension (see L<OS2::REXX>), and we do not have access to
+convenience methods of Object-REXX. (Is it possible at all? I know
+of no Object-REXX API.)
+
+=back
+
+Please keep this list up-to-date by informing me about other items.
+
+=head2 Other OSes
+
+Since OS/2 port of perl uses a remarkable EMX environment, it can
+run (and build extensions, and - possibly - be build itself) under any
+environment which can run EMX. The current list is DOS,
+DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
+only one works, see L<"perl_.exe">.
+
+Note that not all features of Perl are available under these
+environments. This depends on the features the I<extender> - most
+probably RSX - decided to implement.
+
+Cf. L<Prerequisites>.
+
+=head2 Prerequisites
+
+=over 6
+
+=item EMX
+
+EMX runtime is required (may be substituted by RSX). Note that
+it is possible to make F<perl_.exe> to run under DOS without any
+external support by binding F<emx.exe>/F<rsx.exe> to it, see L<emxbind>. Note
+that under DOS for best results one should use RSX runtime, which
+has much more functions working (like C<fork>, C<popen> and so on). In
+fact RSX is required if there is no VCPI present. Note the
+RSX requires DPMI.
+
+Only the latest runtime is supported, currently C<0.9c>. Perl may run
+under earlier versions of EMX, but this is not tested.
+
+One can get different parts of EMX from, say
+
+  ftp://ftp.cdrom.com/pub/os2/emx09c/
+  ftp://hobbes.nmsu.edu/os2/unix/emx09c/
+
+The runtime component should have the name F<emxrt.zip>.
+
+B<NOTE>. It is enough to have F<emx.exe>/F<rsx.exe> on your path. One
+does not need to specify them explicitly (though this
+
+  emx perl_.exe -de 0
+
+will work as well.)
+
+=item RSX
+
+To run Perl on DPMI platforms one needs RSX runtime. This is
+needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see 
+L<"Other OSes">). RSX would not work with VCPI
+only, as EMX would, it requires DMPI.
+
+Having RSX and the latest F<sh.exe> one gets a fully functional
+B<*nix>-ish environment under DOS, say, C<fork>, C<``> and
+pipe-C<open> work. In fact, MakeMaker works (for static build), so one
+can have Perl development environment under DOS. 
+
+One can get RSX from, say
+
+  ftp://ftp.cdrom.com/pub/os2/emx09c/contrib
+  ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
+  ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/contrib
+
+Contact the author on C<rainer@mathematik.uni-bielefeld.de>.
+
+The latest F<sh.exe> with DOS hooks is available at
+
+  ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.zip
+
+=item HPFS
+
+Perl does not care about file systems, but to install the whole perl
+library intact one needs a file system which supports long file names.
+
+Note that if you do not plan to build the perl itself, it may be
+possible to fool EMX to truncate file names. This is not supported,
+read EMX docs to see how to do it.
+
+=item pdksh
+
+To start external programs with complicated command lines (like with
+pipes in between, and/or quoting of arguments), Perl uses an external
+shell. With EMX port such shell should be named <sh.exe>, and located
+either in the wired-in-during-compile locations (usually F<F:/bin>),
+or in configurable location (see L<"PERL_SH_DIR">).
+
+For best results use EMX pdksh. The soon-to-be-available standard
+binary (5.2.12?) runs under DOS (with L<RSX>) as well, meanwhile use
+the binary from
+
+  ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.zip
+
+=back
+
+=head2 Starting Perl programs under OS/2 (and DOS and...)
+
+Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the
+same way as on any other platform, by
+
+	perl foo.pl arg1 arg2 arg3
+
+If you want to specify perl options C<-my_opts> to the perl itself (as
+opposed to to your program), use
+
+	perl -my_opts foo.pl arg1 arg2 arg3
+
+Alternately, if you use OS/2-ish shell, like CMD or 4os2, put
+the following at the start of your perl script:
+
+	extproc perl -S -my_opts
+
+rename your program to F<foo.cmd>, and start it by typing
+
+	foo arg1 arg2 arg3
+
+Note that because of stupid OS/2 limitations the full path of the perl
+script is not available when you use C<extproc>, thus you are forced to
+use C<-S> perl switch, and your script should be on path. As a plus
+side, if you know a full path to your script, you may still start it
+with 
+
+	perl ../../blah/foo.cmd arg1 arg2 arg3
+
+(note that the argument C<-my_opts> is taken care of by the C<extproc> line
+in your script, see L<C<extproc> on the first line>).
+
+To understand what the above I<magic> does, read perl docs about C<-S>
+switch - see L<perlrun>, and cmdref about C<extproc>:
+
+	view perl perlrun
+	man perlrun
+	view cmdref extproc
+	help extproc
+
+or whatever method you prefer.
+
+There are also endless possibilities to use I<executable extensions> of
+4os2, I<associations> of WPS and so on... However, if you use
+*nixish shell (like F<sh.exe> supplied in the binary distribution),
+you need to follow the syntax specified in L<perlrun/"Switches">.
+
+Note that B<-S> switch enables a search with additional extensions 
+F<.cmd>, F<.btm>, F<.bat>, F<.pl> as well.
+
+=head2 Starting OS/2 (and DOS) programs under Perl
+
+This is what system() (see L<perlfunc/system>), C<``> (see
+L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>)
+are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you
+do).
+
+Note however that to use some of these operators you need to have a
+sh-syntax shell installed (see L<"Pdksh">, 
+L<"Frequently asked questions">), and perl should be able to find it
+(see L<"PERL_SH_DIR">).
+
+The only cases when the shell is not used is the multi-argument
+system() (see L<perlfunc/system>)/exec() (see L<perlfunc/exec>), and
+one-argument version thereof without redirection and shell
+meta-characters.
+
+=head1 Frequently asked questions
+
+=head2 I cannot run external programs
+
+=over 4
+
+=item
+
+Did you run your programs with C<-w> switch? See 
+L<Starting OS/2 (and DOS) programs under Perl>.
+
+=item
+
+Do you try to run I<internal> shell commands, like C<`copy a b`>
+(internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You
+need to specify your shell explicitly, like C<`cmd /c copy a b`>,
+since Perl cannot deduce which commands are internal to your shell.
+
+=back
+
+=head2 I cannot embed perl into my program, or use F<perl.dll> from my
+program. 
+
+=over 4
+
+=item Is your program EMX-compiled with C<-Zmt -Zcrtdll>?
+
+If not, you need to build a stand-alone DLL for perl. Contact me, I
+did it once. Sockets would not work, as a lot of other stuff.
+
+=item Did you use L<ExtUtils::Embed>?
+
+I had reports it does not work. Somebody would need to fix it.
+
+=back
+
+=head2 C<``> and pipe-C<open> do not work under DOS.
+
+This may a variant of just L<"I cannot run external programs">, or a
+deeper problem. Basically: you I<need> RSX (see L<"Prerequisites">)
+for these commands to work, and you may need a port of F<sh.exe> which
+understands command arguments. One of such ports is listed in
+L<"Prerequisites"> under RSX. Do not forget to set variable
+C<L<"PERL_SH_DIR">> as well.
+
+DPMI is required for RSX.
+
+=head2 Cannot start C<find.exe "pattern" file>
+
+Use one of
+
+  system 'cmd', '/c', 'find "pattern" file';
+  `cmd /c 'find "pattern" file'`
+
+This would start F<find.exe> via F<cmd.exe> via C<sh.exe> via
+C<perl.exe>, but this is a price to pay if you want to use
+non-conforming program. In fact F<find.exe> cannot be started at all
+using C library API only. Otherwise the following command-lines were
+equivalent:
+
+  find "pattern" file
+  find pattern file
+
+=head1 INSTALLATION
+
+=head2 Automatic binary installation
+
+The most convenient way of installing perl is via perl installer
+F<install.exe>. Just follow the instructions, and 99% of the
+installation blues would go away. 
+
+Note however, that you need to have F<unzip.exe> on your path, and
+EMX environment I<running>. The latter means that if you just
+installed EMX, and made all the needed changes to F<Config.sys>,
+you may need to reboot in between. Check EMX runtime by running
+
+	emxrev
+
+A folder is created on your desktop which contains some useful
+objects.
+
+B<Things not taken care of by automatic binary installation:>
+
+=over 15
+
+=item C<PERL_BADLANG>
+
+may be needed if you change your codepage I<after> perl installation,
+and the new value is not supported by EMX. See L<"PERL_BADLANG">.
+
+=item C<PERL_BADFREE>
+
+see L<"PERL_BADFREE">.
+
+=item F<Config.pm>
+
+This file resides somewhere deep in the location you installed your
+perl library, find it out by 
+
+  perl -MConfig -le "print $INC{'Config.pm'}"
+
+While most important values in this file I<are> updated by the binary
+installer, some of them may need to be hand-edited. I know no such
+data, please keep me informed if you find one.
+
+=back
+
+B<NOTE>. Because of a typo the binary installer of 5.00305
+would install a variable C<PERL_SHPATH> into F<Config.sys>. Please
+remove this variable and put C<L<PERL_SH_DIR>> instead.
+
+=head2 Manual binary installation
+
+As of version 5.00305, OS/2 perl binary distribution comes split
+into 11 components. Unfortunately, to enable configurable binary
+installation, the file paths in the zip files are not absolute, but
+relative to some directory.
+
+Note that the extraction with the stored paths is still necessary
+(default with unzip, specify C<-d> to pkunzip). However, you
+need to know where to extract the files. You need also to manually
+change entries in F<Config.sys> to reflect where did you put the
+files. Note that if you have some primitive unzipper (like
+pkunzip), you may get a lot of warnings/errors during
+unzipping. Upgrade to C<(w)unzip>.
+
+Below is the sample of what to do to reproduce the configuration on my
+machine:
+
+=over 3
+
+=item Perl VIO and PM executables (dynamically linked)
+
+  unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
+  unzip perl_exc.zip *.dll -d f:/emx.add/dll
+
+(have the directories with C<*.exe> on PATH, and C<*.dll> on
+LIBPATH);
+
+=item Perl_ VIO executable (statically linked)
+
+  unzip perl_aou.zip -d f:/emx.add/bin
+
+(have the directory on PATH);
+
+=item Executables for Perl utilities
+
+  unzip perl_utl.zip -d f:/emx.add/bin
+
+(have the directory on PATH);
+
+=item Main Perl library
+
+  unzip perl_mlb.zip -d f:/perllib/lib
+
+If this directory is preserved, you do not need to change
+anything. However, for perl to find it if it is changed, you need to
+C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
+
+=item Additional Perl modules
+
+  unzip perl_ste.zip -d f:/perllib/lib/site_perl
+
+If you do not change this directory, do nothing. Otherwise put this
+directory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB>
+variable. Do not use C<PERL5LIB> unless you have it set already. See
+L<perl/"ENVIRONMENT">. 
+
+=item Tools to compile Perl modules
+
+  unzip perl_blb.zip -d f:/perllib/lib
+
+If this directory is preserved, you do not need to change
+anything. However, for perl to find it if it is changed, you need to
+C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
+
+=item Manpages for Perl and utilities
+
+  unzip perl_man.zip -d f:/perllib/man
+
+This directory should better be on C<MANPATH>. You need to have a
+working man to access these files.
+
+=item Manpages for Perl modules
+
+  unzip perl_mam.zip -d f:/perllib/man
+
+This directory should better be on C<MANPATH>. You need to have a
+working man to access these files.
+
+=item Source for Perl documentation
+
+  unzip perl_pod.zip -d f:/perllib/lib
+
+This is used by by C<perldoc> program (see L<perldoc>), and may be used to
+generate HTML documentation usable by WWW browsers, and
+documentation in zillions of other formats: C<info>, C<LaTeX>,
+C<Acrobat>, C<FrameMaker> and so on.
+
+=item Perl manual in F<.INF> format
+
+  unzip perl_inf.zip -d d:/os2/book
+
+This directory should better be on C<BOOKSHELF>.
+
+=item Pdksh
+
+  unzip perl_sh.zip -d f:/bin
+
+This is used by perl to run external commands which explicitly
+require shell, like the commands using I<redirection> and I<shell
+metacharacters>. It is also used instead of explicit F</bin/sh>.
+
+Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
+the above location.
+
+B<Note.> It may be possible to use some other sh-compatible shell
+(I<not tested>).
+
+=back
+
+After you installed the components you needed and updated the
+F<Config.sys> correspondingly, you need to hand-edit
+F<Config.pm>. This file resides somewhere deep in the location you
+installed your perl library, find it out by
+
+  perl -MConfig -le "print $INC{'Config.pm'}"
+
+You need to correct all the entries which look like file paths (they
+currently start with C<f:/>).
+
+=head2 B<Warning>
+
+The automatic and manual perl installation leave precompiled paths
+inside perl executables. While these paths are overwriteable (see
+L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), one may get better results by
+binary editing of paths inside the executables/DLLs.
+
+=head1 Accessing documentation
+
+Depending on how you built/installed perl you may have (otherwise
+identical) Perl documentation in the following formats:
+
+=head2 OS/2 F<.INF> file
+
+Most probably the most convenient form. Under OS/2 view it as
+
+  view perl
+  view perl perlfunc
+  view perl less
+  view perl ExtUtils::MakeMaker
+
+(currently the last two may hit a wrong location, but this may improve
+soon). Under Win* see L<"SYNOPSIS">.
+
+If you want to build the docs yourself, and have I<OS/2 toolkit>, run
+
+	pod2ipf > perl.ipf
+
+in F</perllib/lib/pod> directory, then
+
+	ipfc /inf perl.ipf
+
+(Expect a lot of errors during the both steps.) Now move it on your
+BOOKSHELF path.
+
+=head2 Plain text
+
+If you have perl documentation in the source form, perl utilities
+installed, and GNU groff installed, you may use 
+
+	perldoc perlfunc
+	perldoc less
+	perldoc ExtUtils::MakeMaker
+
+to access the perl documentation in the text form (note that you may get
+better results using perl manpages).
+
+Alternately, try running pod2text on F<.pod> files.
+
+=head2 Manpages
+
+If you have man installed on your system, and you installed perl
+manpages, use something like this:
+
+	man perlfunc
+	man 3 less
+	man ExtUtils.MakeMaker
+
+to access documentation for different components of Perl. Start with
+
+	man perl
+
+Note that dot (F<.>) is used as a package separator for documentation
+for packages, and as usual, sometimes you need to give the section - C<3>
+above - to avoid shadowing by the I<less(1) manpage>.
+
+Make sure that the directory B<above> the directory with manpages is
+on our C<MANPATH>, like this
+
+  set MANPATH=c:/man;f:/perllib/man
+
+=head2 HTML
+
+If you have some WWW browser available, installed the Perl
+documentation in the source form, and Perl utilities, you can build
+HTML docs. Cd to directory with F<.pod> files, and do like this
+
+	cd f:/perllib/lib/pod
+	pod2html
+
+After this you can direct your browser the file F<perl.html> in this
+directory, and go ahead with reading docs, like this:
+
+	explore file:///f:/perllib/lib/pod/perl.html
+
+Alternatively you may be able to get these docs prebuilt from CPAN.
+
+=head2 GNU C<info> files
+
+Users of Emacs would appreciate it very much, especially with
+C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
+or, alternately, prebuilt info pages.
+
+=head2 F<.PDF> files
+
+for C<Acrobat> are available on CPAN (for slightly old version of
+perl).
+
+=head2 C<LaTeX> docs
+
+can be constructed using C<pod2latex>.
+
+=head1 BUILD
+
+Here we discuss how to build Perl under OS/2. There is an alternative
+(but maybe older) view on L<http://www.shadow.net/~troc/os2perl.html>.
+
+=head2 Prerequisites
+
+You need to have the latest EMX development environment, the full
+GNU tool suite (gawk renamed to awk, and GNU F<find.exe>
+earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to
+check use
+
+  find --version
+  sort --version
+
+). You need the latest version of F<pdksh> installed as F<sh.exe>.
+
+Possible locations to get this from are
+
+  ftp://hobbes.nmsu.edu/os2/unix/
+  ftp://ftp.cdrom.com/pub/os2/unix/
+  ftp://ftp.cdrom.com/pub/os2/dev32/
+  ftp://ftp.cdrom.com/pub/os2/emx09c/
+
+It is reported that the following archives contain enough utils to
+build perl: gnufutil.zip, gnusutil.zip, gnututil.zip, gnused.zip,
+gnupatch.zip, gnuawk.zip, gnumake.zip and ksh527rt.zip.  Note that
+all these utilities are known to be available from LEO:
+
+  ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu
+
+Make sure that no copies or perl are currently running.  Later steps
+of the build may fail since an older version of perl.dll loaded into
+memory may be found. 
+
+Also make sure that you have F</tmp> directory on the current drive,
+and F<.> directory in your C<LIBPATH>. One may try to correct the
+latter condition by
+
+  set BEGINLIBPATH .
+
+if you use something like F<CMD.EXE> or latest versions of F<4os2.exe>.
+
+Make sure your gcc is good for C<-Zomf> linking: run C<omflibs>
+script in F</emx/lib> directory.
+
+Check that you have link386 installed. It comes standard with OS/2,
+but may be not installed due to customization. If typing
+
+  link386
+
+shows you do not have it, do I<Selective install>, and choose C<Link
+object modules> in I<Optional system utilities/More>. If you get into
+link386, press C<Ctrl-C>.
+
+=head2 Getting perl source
+
+You need to fetch the latest perl source (including developers
+releases). With some probability it is located in 
+
+  http://www.perl.com/CPAN/src/5.0
+  http://www.perl.com/CPAN/src/5.0/unsupported
+
+If not, you may need to dig in the indices to find it in the directory
+of the current maintainer.
+
+Quick cycle of developers release may break the OS/2 build time to
+time, looking into 
+
+  http://www.perl.com/CPAN/ports/os2/ilyaz/
+
+may indicate the latest release which was publicly released by the
+maintainer. Note that the release may include some additional patches
+to apply to the current source of perl.
+
+Extract it like this
+
+  tar vzxf perl5.00409.tar.gz
+
+You may see a message about errors while extracting F<Configure>. This is
+because there is a conflict with a similarly-named file F<configure>.
+
+Change to the directory of extraction.
+
+=head2 Application of the patches
+
+You need to apply the patches in F<./os2/diff.*> and
+F<./os2/POSIX.mkfifo> like this:
+
+  gnupatch -p0 < os2\POSIX.mkfifo
+  gnupatch -p0 < os2\diff.configure
+
+You may also need to apply the patches supplied with the binary
+distribution of perl.
+
+Note also that the F<db.lib> and F<db.a> from the EMX distribution
+are not suitable for multi-threaded compile (note that currently perl
+is not multithread-safe, but is compiled as multithreaded for
+compatibility with XFree86-OS/2). Get a corrected one from
+
+  ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip
+
+=head2 Hand-editing
+
+You may look into the file F<./hints/os2.sh> and correct anything
+wrong you find there. I do not expect it is needed anywhere.
+
+=head2 Making
+
+  sh Configure -des -D prefix=f:/perllib
+
+C<prefix> means: where to install the resulting perl library. Giving
+correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
+see L<"PERLLIB_PREFIX">.
+
+I<Ignore the message about missing C<ln>, and about C<-c> option to
+tr>. In fact if you can trace where the latter spurious warning
+comes from, please inform me.
+
+Now
+
+  make
+
+At some moment the built may die, reporting a I<version mismatch> or
+I<unable to run F<perl>>. This means that most of the build has been
+finished, and it is the time to move the constructed F<perl.dll> to
+some I<absolute> location in LIBPATH. After this is done the build
+should finish without a lot of fuss. I<One can avoid the interruption
+if one has the correct prebuilt version of F<perl.dll> on LIBPATH, but
+probably this is not needed anymore, since F<miniperl.exe> is linked
+statically now.>
+
+Warnings which are safe to ignore: I<mkfifo() redefined> inside
+F<POSIX.c>.
+
+=head2 Testing
+
+Now run
+
+  make test
+
+Some tests (4..6) should fail. Some perl invocations should end in a
+segfault (system error C<SYS3175>). To get finer error reports, 
+
+  cd t
+  perl harness
+
+The report you get may look like
+
+  Failed Test  Status Wstat Total Fail  Failed  List of failed
+  ---------------------------------------------------------------
+  io/fs.t                      26   11  42.31%  2-5, 7-11, 18, 25
+  lib/io_pipe.t     3   768     6   ??       %  ??
+  lib/io_sock.t     3   768     5   ??       %  ??
+  op/stat.t                    56    5   8.93%  3-4, 20, 35, 39
+  Failed 4/140 test scripts, 97.14% okay. 27/2937 subtests failed, 99.08% okay.
+
+Note that using `make test' target two more tests may fail: C<op/exec:1>
+because of (mis)feature of pdksh, and C<lib/posix:15>, which checks
+that the buffers are not flushed on C<_exit> (this is a bug in the test
+which assumes that tty output is buffered).
+
+I submitted a patch to EMX which makes it possible to fork() with EMX 
+dynamic libraries loaded, which makes F<lib/io*> tests pass. This means
+that soon the number of failing tests may decrease yet more.
+
+However, the test F<lib/io_udp.t> is disabled, since it never terminates, I
+do not know why. Comments/fixes welcome.
+
+The reasons for failed tests are:
+
+=over 8
+
+=item F<io/fs.t>
+
+Checks I<file system> operations. Tests:
+
+=over 10
+
+=item 2-5, 7-11
+
+Check C<link()> and C<inode count> - nonesuch under OS/2.
+
+=item 18
+
+Checks C<atime> and C<mtime> of C<stat()> - I could not understand this test.
+
+=item 25
+
+Checks C<truncate()> on a filehandle just opened for write - I do not
+know why this should or should not work.
+
+=back
+
+=item F<lib/io_pipe.t>
+
+Checks C<IO::Pipe> module. Some feature of EMX - test fork()s with
+dynamic extension loaded - unsupported now.
+
+=item F<lib/io_sock.t>
+
+Checks C<IO::Socket> module. Some feature of EMX - test fork()s
+with dynamic extension loaded - unsupported now.
+
+=item F<op/stat.t>
+
+Checks C<stat()>. Tests:
+
+=over 4
+
+=item 3
+
+Checks C<inode count> - nonesuch under OS/2.
+
+=item 4
+
+Checks C<mtime> and C<ctime> of C<stat()> - I could not understand this test.
+
+=item 20
+
+Checks C<-x> - determined by the file extension only under OS/2.
+
+=item 35
+
+Needs F</usr/bin>.
+
+=item 39
+
+Checks C<-t> of F</dev/null>. Should not fail!
+
+=back
+
+=back
+
+In addition to errors, you should get a lot of warnings. 
+
+=over 4
+
+=item A lot of `bad free'
+
+in databases related to Berkeley DB. This is a confirmed bug of
+DB. You may disable this warnings, see L<"PERL_BADFREE">.
+
+=item Process terminated by SIGTERM/SIGINT
+
+This is a standard message issued by OS/2 applications. *nix
+applications die in silence. It is considered a feature. One can
+easily disable this by appropriate sighandlers. 
+
+However the test engine bleeds these message to screen in unexpected
+moments. Two messages of this kind I<should> be present during
+testing.
+
+=item F<*/sh.exe>: ln: not found
+
+=item C<ls>: /dev: No such file or directory
+
+The last two should be self-explanatory. The test suite discovers that
+the system it runs on is not I<that much> *nixish.
+
+=back
+
+A lot of `bad free'... in databases, bug in DB confirmed on other
+platforms. You may disable it by setting PERL_BADFREE environment variable
+to 1.
+
+=head2 Installing the built perl
+
+Run
+
+  make install
+
+It would put the generated files into needed locations. Manually put
+F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
+PATH, F<perl.dll> to a location on your LIBPATH.
+
+Run
+
+  make cmdscripts INSTALLCMDDIR=d:/ir/on/path
+
+to convert perl utilities to F<.cmd> files and put them on
+PATH. You need to put F<.EXE>-utilities on path manually. They are
+installed in C<$prefix/bin>, here C<$prefix> is what you gave to
+F<Configure>, see L<Making>.
+
+=head2 C<a.out>-style build
+
+Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
+
+  make perl_
+
+test and install by
+
+  make aout_test
+  make aout_install
+
+Manually put F<perl_.exe> to a location on your PATH.
+
+Since C<perl_> has the extensions prebuilt, it does not suffer from
+the I<dynamic extensions + fork()> syndrome, thus the failing tests
+look like
+
+  Failed Test  Status Wstat Total Fail  Failed  List of failed
+  ---------------------------------------------------------------
+  io/fs.t                      26   11  42.31%  2-5, 7-11, 18, 25
+  op/stat.t                    56    5   8.93%  3-4, 20, 35, 39
+  Failed 2/118 test scripts, 98.31% okay. 16/2445 subtests failed, 99.35% okay.
+
+B<Note.> The build process for C<perl_> I<does not know> about all the
+dependencies, so you should make sure that anything is up-to-date,
+say, by doing
+
+  make perl.dll
+
+first.
+
+=head1 Build FAQ
+
+=head2 Some C</> became C<\> in pdksh.
+
+You have a very old pdksh. See L<Prerequisites>.
+
+=head2 C<'errno'> - unresolved external
+
+You do not have MT-safe F<db.lib>. See L<Prerequisites>.
+
+=head2 Problems with tr
+
+reported with very old version of tr.
+
+=head2 Some problem (forget which ;-)
+
+You have an older version of F<perl.dll> on your LIBPATH, which
+broke the build of extensions.
+
+=head2 Library ... not found
+
+You did not run C<omflibs>. See L<Prerequisites>.
+
+=head2 Segfault in make
+
+You use an old version of GNU make. See L<Prerequisites>.
+
+=head1 Specific (mis)features of OS/2 port
+
+=head2 C<setpriority>, C<getpriority>
+
+Note that these functions are compatible with *nix, not with the older
+ports of '94 - 95. The priorities are absolute, go from 32 to -95,
+lower is quicker. 0 is the default priority.
+
+=head2 C<system()>
+
+Multi-argument form of C<system()> allows an additional numeric
+argument. The meaning of this argument is described in
+L<OS2::Process>.
+
+=head2 C<extproc> on the first line
+
+If the first chars of a script are C<"extproc ">, this line is treated
+as C<#!>-line, thus all the switches on this line are processed (twice
+if script was started via cmd.exe).
+
+=head2 Additional modules:
+
+L<OS2::Process>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. This
+modules provide access to additional numeric argument for C<system>,
+to DLLs having functions with REXX signature and to REXX runtime, to
+OS/2 databases in the F<.INI> format, and to Extended Attributes.
+
+Two additional extensions by Andreas Kaiser, C<OS2::UPM>, and
+C<OS2::FTP>, are included into my ftp directory, mirrored on CPAN.
+
+=head2 Prebuilt methods:
+
+=over 4
+
+=item C<File::Copy::syscopy>
+
+used by C<File::Copy::copy>, see L<File::Copy>.
+
+=item C<DynaLoader::mod2fname>
+
+used by C<DynaLoader> for DLL name mangling.
+
+=item  C<Cwd::current_drive()>
+
+Self explanatory.
+
+=item  C<Cwd::sys_chdir(name)>
+
+leaves drive as it is.
+
+=item  C<Cwd::change_drive(name)>
+
+
+=item  C<Cwd::sys_is_absolute(name)>
+
+means has drive letter and is_rooted.
+
+=item  C<Cwd::sys_is_rooted(name)>
+
+means has leading C<[/\\]> (maybe after a drive-letter:).
+
+=item  C<Cwd::sys_is_relative(name)>
+
+means changes with current dir.
+
+=item  C<Cwd::sys_cwd(name)>
+
+Interface to cwd from EMX. Used by C<Cwd::cwd>.
+
+=item  C<Cwd::sys_abspath(name, dir)>
+
+Really really odious function to implement. Returns absolute name of
+file which would have C<name> if CWD were C<dir>.  C<Dir> defaults to the
+current dir.
+
+=item  C<Cwd::extLibpath([type])
+
+Get current value of extended library search path. If C<type> is
+present and I<true>, works with END_LIBPATH, otherwise with
+C<BEGIN_LIBPATH>. 
+
+=item  C<Cwd::extLibpath_set( path [, type ] )>
+
+Set current value of extended library search path. If C<type> is
+present and I<true>, works with END_LIBPATH, otherwise with
+C<BEGIN_LIBPATH>. 
+
+=back
+
+(Note that some of these may be moved to different libraries -
+eventually).
+
+
+=head2 Misfeatures
+
+=over 4
+
+=item
+
+Since L<flock(3)> is present in EMX, but is not functional, it is 
+emulated by perl.  To disable the emulations, set environment variable
+C<USE_PERL_FLOCK=0>.
+
+=item
+
+Here is the list of things which may be "broken" on
+EMX (from EMX docs):
+
+=over
+
+=item *
+
+The functions L<recvmsg(3)>, L<sendmsg(3)>, and L<socketpair(3)> are not
+implemented.
+
+=item *
+
+L<sock_init(3)> is not required and not implemented.
+
+=item *
+
+L<flock(3)> is not yet implemented (dummy function).  (Perl has a workaround.)
+
+=item *
+
+L<kill(3)>:  Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
+
+=item *
+
+L<waitpid(3)>:
+
+      WUNTRACED
+	      Not implemented.
+      waitpid() is not implemented for negative values of PID.
+
+=back
+
+Note that C<kill -9> does not work with the current version of EMX.
+
+=item
+
+Since F<sh.exe> is used for globing (see L<perlfunc/glob>), the bugs
+of F<sh.exe> plague perl as well. 
+
+In particular, uppercase letters do not work in C<[...]>-patterns with
+the current pdksh.
+
+=back
+
+=head2 Modifications
+
+Perl modifies some standard C library calls in the following ways:
+
+=over 9
+
+=item C<popen>
+
+C<my_popen> uses F<sh.exe> if shell is required, cf. L<"PERL_SH_DIR">.
+
+=item C<tmpnam>
+
+is created using C<TMP> or C<TEMP> environment variable, via
+C<tempnam>.
+
+=item C<tmpfile>
+
+If the current directory is not writable, file is created using modified
+C<tmpnam>, so there may be a race condition.
+
+=item C<ctermid>
+
+a dummy implementation.
+
+=item C<stat>
+
+C<os2_stat> special-cases F</dev/tty> and F</dev/con>.
+
+=item C<flock>
+
+Since L<flock(3)> is present in EMX, but is not functional, it is 
+emulated by perl.  To disable the emulations, set environment variable
+C<USE_PERL_FLOCK=0>.
+
+=back
+
+=head1 Perl flavors
+
+Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
+same basket (though EMX environment tries hard to overcome this
+limitations, so the situation may somehow improve). There are 4
+executables for Perl provided by the distribution:
+
+=head2 F<perl.exe>
+
+The main workhorse. This is a chimera executable: it is compiled as an
+C<a.out>-style executable, but is linked with C<omf>-style dynamic
+library F<perl.dll>, and with dynamic CRT DLL. This executable is a
+VIO application.
+
+It can load perl dynamic extensions, and it can fork(). Unfortunately,
+with the current version of EMX it cannot fork() with dynamic
+extensions loaded (may be fixed by patches to EMX).
+
+B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.
+
+=head2 F<perl_.exe>
+
+This is a statically linked C<a.out>-style executable. It can fork(),
+but cannot load dynamic Perl extensions. The supplied executable has a
+lot of extensions prebuilt, thus there are situations when it can
+perform tasks not possible using F<perl.exe>, like fork()ing when
+having some standard extension loaded. This executable is a VIO
+application.
+
+B<Note.> A better behaviour could be obtained from C<perl.exe> if it
+were statically linked with standard I<Perl extensions>, but
+dynamically linked with the I<Perl DLL> and CRT DLL. Then it would
+be able to fork() with standard extensions, I<and> would be able to
+dynamically load arbitrary extensions. Some changes to Makefiles and
+hint files should be necessary to achieve this.
+
+I<This is also the only executable with does not require OS/2.> The
+friends locked into C<M$> world would appreciate the fact that this
+executable runs under DOS, Win0.3*, Win0.95 and WinNT with an
+appropriate extender. See L<"Other OSes">.
+
+=head2 F<perl__.exe>
+
+This is the same executable as F<perl___.exe>, but it is a PM
+application. 
+
+B<Note.> Usually STDIN, STDERR, and STDOUT of a PM
+application are redirected to C<nul>. However, it is possible to see
+them if you start C<perl__.exe> from a PM program which emulates a
+console window, like I<Shell mode> of Emacs or EPM. Thus it I<is
+possible> to use Perl debugger (see L<perldebug>) to debug your PM
+application.
+
+This flavor is required if you load extensions which use PM, like
+the forthcoming C<Perl/Tk>.
+
+=head2 F<perl___.exe>
+
+This is an C<omf>-style executable which is dynamically linked to
+F<perl.dll> and CRT DLL. I know no advantages of this executable
+over C<perl.exe>, but it cannot fork() at all. Well, one advantage is
+that the build process is not so convoluted as with C<perl.exe>.
+
+It is a VIO application.
+
+=head2 Why strange names?
+
+Since Perl processes the C<#!>-line (cf. 
+L<perlrun/DESCRIPTION>, L<perlrun/Switches>,
+L<perldiag/"Not a perl script">, 
+L<perldiag/"No Perl script found in input">), it should know when a
+program I<is a Perl>. There is some naming convention which allows
+Perl to distinguish correct lines from wrong ones. The above names are
+almost the only names allowed by this convention which do not contain
+digits (which have absolutely different semantics).
+
+=head2 Why dynamic linking?
+
+Well, having several executables dynamically linked to the same huge
+library has its advantages, but this would not substantiate the
+additional work to make it compile. The reason is stupid-but-quick
+"hard" dynamic linking used by OS/2.
+
+The address tables of DLLs are patched only once, when they are
+loaded. The addresses of entry points into DLLs are guaranteed to be
+the same for all programs which use the same DLL, which reduces the
+amount of runtime patching - once DLL is loaded, its code is
+read-only.
+
+While this allows some performance advantages, this makes life
+terrible for developers, since the above scheme makes it impossible
+for a DLL to be resolved to a symbol in the .EXE file, since this
+would need a DLL to have different relocations tables for the
+executables which use it.
+
+However, a Perl extension is forced to use some symbols from the perl
+executable, say to know how to find the arguments provided on the perl
+internal evaluation stack. The solution is that the main code of
+interpreter should be contained in a DLL, and the F<.EXE> file just loads
+this DLL into memory and supplies command-arguments.
+
+This I<greatly> increases the load time for the application (as well as
+the number of problems during compilation). Since interpreter is in a DLL,
+the CRT is basically forced to reside in a DLL as well (otherwise
+extensions would not be able to use CRT).
+
+=head2 Why chimera build?
+
+Current EMX environment does not allow DLLs compiled using Unixish
+C<a.out> format to export symbols for data. This forces C<omf>-style
+compile of F<perl.dll>.
+
+Current EMX environment does not allow F<.EXE> files compiled in
+C<omf> format to fork(). fork() is needed for exactly three Perl
+operations:
+
+=over 4
+
+=item explicit fork()
+
+in the script, and
+
+=item open FH, "|-"
+
+=item open FH, "-|"
+
+opening pipes to itself.
+
+=back
+
+While these operations are not questions of life and death, a lot of
+useful scripts use them. This forces C<a.out>-style compile of
+F<perl.exe>.
+
+
+=head1 ENVIRONMENT
+
+Here we list environment variables with are either OS/2- and DOS- and
+Win*-specific, or are more important under OS/2 than under other OSes.
+
+=head2 C<PERLLIB_PREFIX>
+
+Specific for EMX port. Should have the form
+
+  path1;path2
+
+or
+
+  path1 path2
+
+If the beginning of some prebuilt path matches F<path1>, it is
+substituted with F<path2>.
+
+Should be used if the perl library is moved from the default
+location in preference to C<PERL(5)LIB>, since this would not leave wrong
+entries in @INC.  Say, if the compiled version of perl looks for @INC
+in F<f:/perllib/lib>, and you want to install the library in
+F<h:/opt/gnu>, do
+
+  set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
+
+=head2 C<PERL_BADLANG>
+
+If 1, perl ignores setlocale() failing. May be useful with some
+strange I<locale>s.
+
+=head2 C<PERL_BADFREE>
+
+If 1, perl would not warn of in case of unwarranted free(). May be
+useful in conjunction with the module DB_File, since Berkeley DB
+memory handling code is buggy.
+
+=head2 C<PERL_SH_DIR>
+
+Specific for EMX port. Gives the directory part of the location for
+F<sh.exe>.
+
+=head2 C<USE_PERL_FLOCK>
+
+Specific for EMX port. Since L<flock(3)> is present in EMX, but is not 
+functional, it is emulated by perl.  To disable the emulations, set 
+environment variable C<USE_PERL_FLOCK=0>.
+
+=head2 C<TMP> or C<TEMP>
+
+Specific for EMX port. Used as storage place for temporary files, most
+notably C<-e> scripts.
+
+=head1 Evolution
+
+Here we list major changes which could make you by surprise.
+
+=head2 Priorities
+
+C<setpriority> and C<getpriority> are not compatible with earlier
+ports by Andreas Kaiser. See C<"setpriority, getpriority">.
+
+=head2 DLL name mangling
+
+With the release 5.003_01 the dynamically loadable libraries
+should be rebuilt. In particular, DLLs are now created with the names
+which contain a checksum, thus allowing workaround for OS/2 scheme of
+caching DLLs.
+
+=head2 Threading
+
+As of release 5.003_01 perl is linked to multithreaded CRT
+DLL. Perl itself is not multithread-safe, as is not perl
+malloc(). However, extensions may use multiple thread on their own
+risk. 
+
+Needed to compile C<Perl/Tk> for XFree86-OS/2 out-of-the-box.
+
+=head2 Calls to external programs
+
+Due to a popular demand the perl external program calling has been
+changed wrt Andreas Kaiser's port.  I<If> perl needs to call an
+external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
+whatever is the override, see L<"PERL_SH_DIR">.
+
+Thus means that you need to get some copy of a F<sh.exe> as well (I
+use one from pdksh). The drive F: above is set up automatically during
+the build to a correct value on the builder machine, but is
+overridable at runtime,
+
+B<Reasons:> a consensus on C<perl5-porters> was that perl should use
+one non-overridable shell per platform. The obvious choices for OS/2
+are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible
+with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. Thus assures almost
+100% compatibility with the scripts coming from *nix. As an added benefit 
+this works as well under DOS if you use DOS-enabled port of pdksh 
+(see L<"Prerequisites">).
+
+B<Disadvantages:> currently F<sh.exe> of pdksh calls external programs
+via fork()/exec(), and there is I<no> functioning exec() on
+OS/2. exec() is emulated by EMX by asyncroneous call while the caller
+waits for child completion (to pretend that the C<pid> did not change). This
+means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(),
+which may lead to some resources taken from the system (even if we do
+not count extra work needed for fork()ing).
+
+Note that this a lesser issue now when we do not spawn F<sh.exe>
+unless needed (metachars found).
+
+One can always start F<cmd.exe> explicitly via
+
+  system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
+
+If you need to use F<cmd.exe>, and do not want to hand-edit thousands of your
+scripts, the long-term solution proposed on p5-p is to have a directive
+
+  use OS2::Cmd;
+
+which will override system(), exec(), C<``>, and
+C<open(,'...|')>. With current perl you may override only system(),
+readpipe() - the explicit version of C<``>, and maybe exec(). The code
+will substitute the one-argument call to system() by
+C<CORE::system('cmd.exe', '/c', shift)>.
+
+If you have some working code for C<OS2::Cmd>, please send it to me,
+I will include it into distribution. I have no need for such a module, so
+cannot test it.
+
+=head2 Memory allocation
+
+Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound
+for speed, but perl is not, since its malloc is lightning-fast. 
+Unfortunately, it is also quite frivolous with memory usage as well.
+
+Since kitchen-top machines are usually low on memory, perl is compiled with
+all the possible memory-saving options. This probably makes perl's 
+malloc() as greedy with memory as the neighbor's malloc(), but still
+much quickier. Note that this is true only for a "typical" usage,
+it is possible that the perl malloc will be worse for some very special usage.
+
+Combination of perl's malloc() and rigid DLL name resolution creates
+a special problem with library functions which expect their return value to
+be free()d by system's free(). To facilitate extensions which need to call 
+such functions, system memory-allocation functions are still available with
+the prefix C<emx_> added. (Currently only DLL perl has this, it should 
+propagate to F<perl_.exe> shortly.)
+
+=cut
+
+OS/2 extensions
+~~~~~~~~~~~~~~~
+I include 3 extensions by Andreas Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP, 
+into my ftp directory, mirrored on CPAN. I made
+some minor changes needed to compile them by standard tools. I cannot 
+test UPM and FTP, so I will appreciate your feedback. Other extensions
+there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI
+files - and maybe some other extensions at the time you read it.
+
+Note that OS2 perl defines 2 pseudo-extension functions
+OS2::Copy::copy and DynaLoader::mod2fname (many more now, see
+L<Prebuilt methods>).
+
+The -R switch of older perl is deprecated. If you need to call a REXX code
+which needs access to variables, include the call into a REXX compartment
+created by 
+	REXX_call {...block...};
+
+Two new functions are supported by REXX code, 
+	REXX_eval 'string';
+	REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference;
+
+If you have some other extensions you want to share, send the code to
+me.  At least two are available: tied access to EA's, and tied access
+to system databases.
+
+=head1 AUTHOR
+
+Ilya Zakharevich, ilya@math.ohio-state.edu
+
+=head1 SEE ALSO
+
+perl(1).
+
+=cut
+