This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
chop/chomp modify readonly values
[perl5.git] / README.os2
index c0a1960..409c774 100644 (file)
@@ -31,6 +31,12 @@ 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).
 
 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
 =cut
 
 Contents
@@ -106,6 +112,7 @@ Contents
          -  Threading 
          -  Calls to external programs 
          -  Memory allocation 
          -  Threading 
          -  Calls to external programs 
          -  Memory allocation 
+         -  Threads
       AUTHOR 
       SEE ALSO 
   
       AUTHOR 
       SEE ALSO 
   
@@ -176,8 +183,8 @@ under earlier versions of EMX, but this is not tested.
 
 One can get different parts of EMX from, say
 
 
 One can get different parts of EMX from, say
 
-  ftp://ftp.cdrom.com/pub/os2/emx0.9c/
-  ftp://hobbes.nmsu.edu/os2/unix/gnu/
+  ftp://ftp.cdrom.com/pub/os2/emx09c/
+  ftp://hobbes.nmsu.edu/os2/unix/emx09c/
 
 The runtime component should have the name F<emxrt.zip>.
 
 
 The runtime component should have the name F<emxrt.zip>.
 
@@ -202,14 +209,15 @@ can have Perl development environment under DOS.
 
 One can get RSX from, say
 
 
 One can get RSX from, say
 
-  ftp://ftp.cdrom.com/pub/os2/emx0.9c/contrib
+  ftp://ftp.cdrom.com/pub/os2/emx09c/contrib
   ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
   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
 
 
 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.exe
+  ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.zip
 
 =item HPFS
 
 
 =item HPFS
 
@@ -232,7 +240,7 @@ 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
 
 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.exe
+  ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.zip
 
 =back
 
 
 =back
 
@@ -283,6 +291,9 @@ There are also endless possibilities to use I<executable extensions> of
 *nixish shell (like F<sh.exe> supplied in the binary distribution),
 you need to follow the syntax specified in L<perlrun/"Switches">.
 
 *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
 =head2 Starting OS/2 (and DOS) programs under Perl
 
 This is what system() (see L<perlfunc/system>), C<``> (see
@@ -295,10 +306,86 @@ sh-syntax shell installed (see L<"Pdksh">,
 L<"Frequently asked questions">), and perl should be able to find it
 (see L<"PERL_SH_DIR">).
 
 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.
+The cases when the shell is used are:
+
+=over
+
+=item 1
+
+One-argument system() (see L<perlfunc/system>), exec() (see L<perlfunc/exec>)
+with redirection or shell meta-characters;
+
+=item 2
+
+Pipe-open (see L<perlfunc/open>) with the command which contains redirection 
+or shell meta-characters;
+
+=item 3
+
+Backticks C<``> (see L<perlop/"I/O Operators">) with the command which contains
+redirection or shell meta-characters;
+
+=item 4
+
+If the executable called by system()/exec()/pipe-open()/C<``> is a script
+with the "magic" C<#!> line or C<extproc> line which specifies shell;
+
+=item 5
+
+If the executable called by system()/exec()/pipe-open()/C<``> is a script
+without "magic" line, and C<$ENV{EXECSHELL}> is set to shell;
+
+=item 6
+
+If the executable called by system()/exec()/pipe-open()/C<``> is not
+found;
+
+=item 7
+
+For globbing (see L<perlfunc/glob>, L<perlop/"I/O Operators">).
+
+=back
+
+For the sake of speed for a common case, in the above algorithms 
+backslashes in the command name are not considered as shell metacharacters.
+
+Perl starts scripts which begin with cookies
+C<extproc> or C<#!> directly, without an intervention of shell.  Perl uses the
+same algorithm to find the executable as F<pdksh>: if the path
+on C<#!> line does not work, and contains C</>, then the executable
+is searched in F<.> and on C<PATH>.  To find arguments for these scripts
+Perl uses a different algorithm than F<pdksh>: up to 3 arguments are 
+recognized, and trailing whitespace is stripped.
+
+If a script
+does not contain such a cooky, then to avoid calling F<sh.exe>, Perl uses
+the same algorithm as F<pdksh>: if C<$ENV{EXECSHELL}> is set, the
+script is given as the first argument to this command, if not set, then
+C<$ENV{COMSPEC} /c> is used (or a hardwired guess if C<$ENV{COMSPEC}> is
+not set).
+
+If starting scripts directly, Perl will use exactly the same algorithm as for 
+the search of script given by B<-S> command-line option: it will look in
+the current directory, then on components of C<$ENV{PATH}> using the 
+following order of appended extensions: no extension, F<.cmd>, F<.btm>, 
+F<.bat>, F<.pl>.
+
+Note that Perl will start to look for scripts only if OS/2 cannot start the
+specified application, thus C<system 'blah'> will not look for a script if 
+there is an executable file F<blah.exe> I<anywhere> on C<PATH>.  
+
+Note also that executable files on OS/2 can have an arbitrary extension, 
+but F<.exe> will be automatically appended if no dot is present in the name.  
+The workaround as as simple as that:  since F<blah.> and F<blah> denote the 
+same file, to start an executable residing in file F<n:/bin/blah> (no 
+extension) give an argument C<n:/bin/blah.> to system().
+
+The last note is that currently it is not straightforward to start PM 
+programs from VIO (=text-mode) Perl process and visa versa.  Either ensure
+that shell will be used, as in C<system 'cmd /c epm'>, or start it using
+optional arguments to system() documented in C<OS2::Process> module.  This
+is considered a bug and should be fixed soon.
+
 
 =head1 Frequently asked questions
 
 
 =head1 Frequently asked questions
 
@@ -650,13 +737,22 @@ check use
 
 ). You need the latest version of F<pdksh> installed as F<sh.exe>.
 
 
 ). You need the latest version of F<pdksh> installed as F<sh.exe>.
 
+Check that you have B<BSD> libraries and headers installed, and - 
+optionally - Berkeley DB headers and libraries, and crypt.
+
 Possible locations to get this from are
 
 Possible locations to get this from are
 
-  ftp://hobbes.nmsu.edu/os2/unix/gnu/
+  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/unix/
   ftp://ftp.cdrom.com/pub/os2/dev32/
-  ftp://ftp.cdrom.com/pub/os2/emx0.9c/
+  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
 
 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
@@ -729,6 +825,22 @@ compatibility with XFree86-OS/2). Get a corrected one from
 
   ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip
 
 
   ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip
 
+To make C<-p> filetest work, one may also need to apply the following patch
+to EMX headers:
+
+  --- /emx/include/sys/stat.h.orig     Thu May 23 13:48:16 1996
+  +++ /emx/include/sys/stat.h  Sun Jul 12 14:11:32 1998
+  @@ -53,7 +53,7 @@ struct stat
+   #endif
+   #if !defined (S_IFMT)
+  -#define S_IFMT   0160000  /* Mask for file type */
+  +#define S_IFMT   0170000  /* Mask for file type */
+   #define S_IFIFO  0010000  /* Pipe */
+   #define S_IFCHR  0020000  /* Character device */
+   #define S_IFDIR  0040000  /* Directory */
+
+
 =head2 Hand-editing
 
 You may look into the file F<./hints/os2.sh> and correct anything
 =head2 Hand-editing
 
 You may look into the file F<./hints/os2.sh> and correct anything
@@ -764,55 +876,73 @@ F<POSIX.c>.
 
 =head2 Testing
 
 
 =head2 Testing
 
+If you haven't yet moved perl.dll onto LIBPATH, do it now (alternatively, if
+you have a previous perl installation you'd rather not disrupt until this one
+is installed, copy perl.dll to the t directory).
+
 Now run
 
   make test
 
 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, 
+All tests should succeed (with some of them skipped).  Note that on one
+of the systems I see intermittent failures of F<io/pipe.t> subtest 9.
+Any help to track what happens with this test is appreciated.
 
 
-  cd t
-  perl harness
+Some tests may generate extra messages similar to
 
 
-The report you get may look like
+=over 4
 
 
-  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.
+=item A lot of C<bad free>
 
 
-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).
+in database tests related to Berkeley DB. This is a confirmed bug of
+DB. You may disable this warnings, see L<"PERL_BADFREE">.
 
 
-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.
+There is not much we can do with it (but apparently it does not cause 
+any real error with data).
+
+=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.
 
 
-However, the test F<lib/io_udp.t> is disabled, since it never terminates, I
-do not know why. Comments/fixes welcome.
+=back
 
 
-The reasons for failed tests are:
+Two F<lib/io_*> tests may generate popups (system error C<SYS3175>), 
+but should succeed anyway.  This is due to a bug of EMX related to 
+fork()ing with dynamically loaded libraries.
 
 
-=over 8
+I submitted a patch to EMX which makes it possible to fork() with EMX 
+dynamic libraries loaded, which makes F<lib/io*> tests pass without
+skipping offended tests. This means that soon the number of skipped tests
+may decrease yet more.
+
+To get finer test reports, call
 
 
-=item F<io/fs.t>
+  perl t/harness
 
 
-Checks I<file system> operations. Tests:
+The report with F<io/pipe.t> failing may look like this:
+
+  Failed Test  Status Wstat Total Fail  Failed  List of failed
+  ------------------------------------------------------------
+  io/pipe.t                    12    1   8.33%  9
+  7 tests skipped, plus 56 subtests skipped.
+  Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay.
 
 
-=over 10
+The reasons for most important skipped tests are:
 
 
-=item 2-5, 7-11
+=over 8
 
 
-Check C<link()> and C<inode count> - nonesuch under OS/2.
+=item F<op/fs.t>
 
 =item 18
 
 
 =item 18
 
-Checks C<atime> and C<mtime> of C<stat()> - I could not understand this test.
+Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
+provides only 2sec time granularity (for compatibility with FAT?).
 
 =item 25
 
 
 =item 25
 
@@ -837,64 +967,24 @@ Checks C<stat()>. Tests:
 
 =over 4
 
 
 =over 4
 
-=item 3
-
-Checks C<inode count> - nonesuch under OS/2.
-
 =item 4
 
 =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!
+Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
+provides only 2sec time granularity (for compatibility with FAT?).
 
 =back
 
 
 =back
 
-=back
+=item F<lib/io_udp.t>
 
 
-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.
+It never terminates, apparently some bug in storing the last socket from
+which we obtained a message.
 
 =back
 
 
 =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
 
 =head2 Installing the built perl
 
+If you haven't yet moved perl.dll onto LIBPATH, do it now.
+
 Run
 
   make install
 Run
 
   make install
@@ -953,9 +1043,9 @@ You have a very old pdksh. See L<Prerequisites>.
 
 You do not have MT-safe F<db.lib>. See L<Prerequisites>.
 
 
 You do not have MT-safe F<db.lib>. See L<Prerequisites>.
 
-=head2 Problems with tr
+=head2 Problems with tr or sed
 
 
-reported with very old version of tr.
+reported with very old version of tr and sed.
 
 =head2 Some problem (forget which ;-)
 
 
 =head2 Some problem (forget which ;-)
 
@@ -992,8 +1082,9 @@ if script was started via cmd.exe).
 
 =head2 Additional modules:
 
 
 =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>,
+L<OS2::Process>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. These
+modules provide access to additional numeric argument for C<system>
+and to the list of the running processes,
 to DLLs having functions with REXX signature and to REXX runtime, to
 OS/2 databases in the F<.INI> format, and to Extended Attributes.
 
 to DLLs having functions with REXX signature and to REXX runtime, to
 OS/2 databases in the F<.INI> format, and to Extended Attributes.
 
@@ -1006,7 +1097,7 @@ C<OS2::FTP>, are included into my ftp directory, mirrored on CPAN.
 
 =item C<File::Copy::syscopy>
 
 
 =item C<File::Copy::syscopy>
 
-used by C<File::Copy::copy>, see L<File::Copy/copy>.
+used by C<File::Copy::copy>, see L<File::Copy>.
 
 =item C<DynaLoader::mod2fname>
 
 
 =item C<DynaLoader::mod2fname>
 
@@ -1069,21 +1160,44 @@ eventually).
 
 =item
 
 
 =item
 
-Since <flock> is present in EMX, but is not functional, the same is
-true for perl. Here is the list of things which may be "broken" on
+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):
 
 EMX (from EMX docs):
 
-  - The functions recvmsg(), sendmsg(), and socketpair() are not
-    implemented.
-  - sock_init() is not required and not implemented.
-  - flock() is not yet implemented (dummy function).
-  - kill:
-      Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
-  - waitpid:
+=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.
 
       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
 Note that C<kill -9> does not work with the current version of EMX.
 
 =item
@@ -1124,6 +1238,12 @@ a dummy implementation.
 
 C<os2_stat> special-cases F</dev/tty> and F</dev/con>.
 
 
 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
 =back
 
 =head1 Perl flavors
@@ -1281,7 +1401,11 @@ 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
 
 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>. 
+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>
 
 
 =head2 C<PERL_BADLANG>
 
@@ -1299,6 +1423,12 @@ memory handling code is buggy.
 Specific for EMX port. Gives the directory part of the location for
 F<sh.exe>.
 
 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
 =head2 C<TMP> or C<TEMP>
 
 Specific for EMX port. Used as storage place for temporary files, most
@@ -1323,7 +1453,7 @@ caching DLLs.
 =head2 Threading
 
 As of release 5.003_01 perl is linked to multithreaded CRT
 =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
+DLL.  If perl itself is not compiled multithread-enabled, so will not be perl
 malloc(). However, extensions may use multiple thread on their own
 risk. 
 
 malloc(). However, extensions may use multiple thread on their own
 risk. 
 
@@ -1337,7 +1467,7 @@ 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
 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
+use one from pdksh). The drive F<F:> above is set up automatically during
 the build to a correct value on the builder machine, but is
 overridable at runtime,
 
 the build to a correct value on the builder machine, but is
 overridable at runtime,
 
@@ -1379,17 +1509,25 @@ 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.
 
 I will include it into distribution. I have no need for such a module, so
 cannot test it.
 
+For the details of the current situation with calling external programs,
+see L<Starting OS/2 (and DOS) programs under Perl>.
+
+=over
+
+=item
+
+External scripts may be called by name.  Perl will try the same extensions
+as when processing B<-S> command-line switch.
+
+=back
+
 =head2 Memory allocation
 
 Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound
 =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.
+for speed, but perl is not, since its malloc is lightning-fast.
+Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quickier
+than EMX one.  I do not have convincing data about memory footpring, but
+a (pretty random) benchmark showed that Perl one is 5% better.
 
 Combination of perl's malloc() and rigid DLL name resolution creates
 a special problem with library functions which expect their return value to
 
 Combination of perl's malloc() and rigid DLL name resolution creates
 a special problem with library functions which expect their return value to
@@ -1398,6 +1536,31 @@ 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.)
 
 the prefix C<emx_> added. (Currently only DLL perl has this, it should 
 propagate to F<perl_.exe> shortly.)
 
+=head2 Threads
+
+One can build perl with thread support enabled by providing C<-D usethreads>
+option to F<Configure>.  Currently OS/2 support of threads is very 
+preliminary.
+
+Most notable problems: 
+
+=over
+
+=item C<COND_WAIT> 
+
+may have a race condition.  Needs a reimplementation (in terms of chaining
+waiting threads, with linker list stored in per-thread structure?).
+
+=item F<os2.c>
+
+has a couple of static variables used in OS/2-specific functions.  (Need to be
+moved to per-thread structure, or serialized?)
+
+=back
+
+Note that these problems should not discourage experimenting, since they
+have a low probability of affecting small programs.
+
 =cut
 
 OS/2 extensions
 =cut
 
 OS/2 extensions