OS/2 docs

Message-ID: <20010629023412.A6033@math.ohio-state.edu>

p4raw-id: //depot/perl@11018

1 files changed, 149 insertions, 6 deletions

diff --git a/README.os2 b/README.os2
index fbc2731a48..69fa3866a4 100644
--- a/README.os2
+++ b/README.os2
@@ -1053,8 +1053,11 @@ 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.
 
-B<WARNING>.  Calling C<getpriority> on a non-existing process can lock the
-system before Warp3 fixpak22.
+B<WARNING>.  Calling C<getpriority> on a non-existing process could lock
+the system before Warp3 fixpak22.  Starting with Warp3, Perl will use
+a workaround: it aborts getpriority() if the process is not present.
+This is not possible on older versions C<2.*>, and has a race
+condition anyway.
 
 =head2 C<system()>
 
@@ -1063,7 +1066,8 @@ argument. The meaning of this argument is described in
 L<OS2::Process>.
 
 When finding a program to run, Perl first asks the OS to look for executables
-on C<PATH>.  If not found, it looks for a script with possible extensions 
+on C<PATH> (OS/2 adds extension F<.exe> if no extension is present).
+If not found, it looks for a script with possible extensions 
 added in this order: no extension, F<.cmd>, F<.btm>, 
 F<.bat>, F<.pl>.  If found, Perl checks the start of the file for magic
 strings C<"#!"> and C<"extproc ">.  If found, Perl uses the rest of the
@@ -1077,8 +1081,7 @@ F<C:/emx/bin/foo.cmd> with the first line being
 
  extproc /bin/bash    -x   -c
 
-If F</bin/bash> is not found, and appending of executable extensions to
-F</bin/bash> does not help either, then Perl looks for an executable F<bash> on
+If F</bin/bash.exe> is not found, then Perl looks for an executable F<bash.exe> on
 C<PATH>.  If found in F<C:/emx.add/bin/bash.exe>, then the above system() is
 translated to
 
@@ -1098,6 +1101,11 @@ If Perl finds that the found executable is of different type than the
 current session, it will start the new process in a separate session of
 necessary type.  Call via C<OS2::Process> to disable this magic.
 
+B<WARNING>.  Due to the described logic, you need to explicitly
+specify F<.com> extension if needed.  Moreover, if the executable
+F<perl5.6.1> is requested, Perl will not look for F<perl5.6.1.exe>.
+[This may change in the future.]
+
 =head2 C<extproc> on the first line
 
 If the first chars of a Perl script are C<"extproc ">, this line is treated
@@ -1748,7 +1756,7 @@ Here we list major changes which could make you by surprise.
 C<setpriority> and C<getpriority> are not compatible with earlier
 ports by Andreas Kaiser. See C<"setpriority, getpriority">.
 
-=head2 DLL name mangling
+=head2 DLL name mangling: pre 5.6.2
 
 With the release 5.003_01 the dynamically loadable libraries
 should be rebuilt when a different version of Perl is compiled. In particular,
@@ -1782,6 +1790,136 @@ F<perl????.dll> to the "new" F<perl????.dll>.
 
 =back
 
+=head2 DLL name mangling: 5.6.2 and beyound
+
+In fact mangling of I<extension> DLLs was done due to misunderstanding
+of the OS/2 dynaloading model.  OS/2 (effectively) maintains two
+different tables of loaded DLL:
+
+=over
+
+=item Global DLLs
+
+those loaded by the base name from C<LIBPATH>; including those
+associated at link time;
+
+=item specific DLLs
+
+loaded by the full name.
+
+=back
+
+When resolving a request for a global DLL, the table of already-loaded
+specific DLLs is (effectively) ignored; moreover, specific DLLs are
+I<always> loaded from the prescribed path.
+
+There is/was a minor twist which makes this scheme fragile: what to do
+with DLLs loaded from
+
+=over
+
+=item C<BEGINLIBPATH> and C<ENDLIBPATH>
+
+(which depend on the process)
+
+=item F<.> from C<LIBPATH>
+
+which I<effectively> depends on the process (although C<LIBPATH> is the
+same for all the processes).
+
+=back
+
+Unless C<LIBPATHSTRICT> is set to C<T> (and the kernel is after
+2000/09/01), such DLLs are considered to be global.  When loading a
+global DLL it is first looked in the table of already-loaded global
+DLLs.  Because of this the fact that one executable loaded a DLL from
+C<BEGINLIBPATH> and C<ENDLIBPATH>, or F<.> from C<LIBPATH> may affect
+I<which> DLL is loaded when I<another> executable requests a DLL with
+the same name.  I<This> is the reason for version-specific mangling of
+the DLL name for perl DLL.
+
+Since the Perl extension DLLs are always loaded with the full path,
+there is no need to mangle their names in a version-specific ways:
+their directory already reflects the corresponding version of perl,
+and @INC takes into account binary compatibility with older version.
+Starting from C<5.6.2> the name mangling scheme is fixed to be the
+same as for Perl 5.005_53 (same as in a popular binary release).  Thus
+new Perls will be able to I<resolve the names> of old extension DLLs
+if @INC allows finding their directories.
+
+However, this still does not guarantie that these DLL may be loaded.
+The reason is the mangling of the name of the I<Perl DLL>.  And since
+the extension DLLs link with the Perl DLL, extension DLLs for older
+versions would load an older Perl DLL, and would most probably
+segfault (since the data in this DLL is not properly initialized).
+
+There is a partial workaround (which can be made complete with newer
+OS/2 kernels): create a forwarder DLL with the same name as the DLL of
+the older version of Perl, which forwards the entry points to the
+newer Perl's DLL.  Make this DLL accessible on (say) the C<BEGINLIBPATH> of
+the new Perl executable.  When the new executable accesses old Perl's
+extension DLLs, they would request the old Perl's DLL by name, get the
+forwarder instead, so effectively will link with the currently running
+(new) Perl DLL.
+
+This may break in two ways:
+
+=over
+
+=item *
+
+Old perl executable is started when a new executable is running has
+loaded an extension compiled for the old executable (ouph!).  In this
+case the old executable will get a forwarder DLL instead of the old
+perl DLL, so would link with the new perl DLL.  While not directly
+fatal, it will behave the same as new excutable.  This beats the whole
+purpose of explicitly starting an old executable.
+
+=item *
+
+A new executable loads an extension compiled for the old executable
+when an old perl executable is running.  In this case the extension
+will not pick up the forwarder - with fatal results.
+
+=back
+
+With support for C<LIBPATHSTRICT> this may be circumvented - unless
+one of DLLs is started from F<.> from C<LIBPATH> (I do not know
+whether C<LIBPATHSTRICT> affects this case).
+
+B<REMARK>.  Unless newer kernels allow F<.> in C<BEGINLIBPATH> (older
+do not), this mess cannot be completely cleaned.
+
+
+B<REMARK>.  C<LIBPATHSTRICT>, C<BEGINLIBPATH> and C<ENDLIBPATH> are
+not environment variables, although F<cmd.exe> emulates them on C<SET
+...> lines.  From Perl they may be accessed by L<Cwd::extLibpath> and
+L<Cwd::extLibpath_set>.
+
+=head2 DLL forwarder generation
+
+Assume that the old DLL is named F<perlE0AC.dll> (as is one for
+5.005_53), and the new version is 5.6.1.  Create a file
+F<perl5shim.def-leader> with
+
+  LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
+  DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
+  CODE LOADONCALL
+  DATA LOADONCALL NONSHARED MULTIPLE
+  EXPORTS
+
+modifying the versions/names as needed.  Run
+
+ perl -wnle "next if 0../EXPORTS/; print qq(  \"$1\") if /\"(\w+)\"/" perl5.def >lst
+
+in the Perl build directory (to make the DLL smaller replace perl5.def
+with the definition file for the older version of Perl if present).
+
+ cat perl5shim.def-leader lst >perl5shim.def
+ gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl
+
+(ignore multiple C<warning L4085>).
+
 =head2 Threading
 
 As of release 5.003_01 perl is linked to multithreaded C RTL
@@ -1902,6 +2040,11 @@ moved to per-thread structure, or serialized?)
 Note that these problems should not discourage experimenting, since they
 have a low probability of affecting small programs.
 
+=head1 BUGS
+
+This description was not updated since 5.6.1, see F<os2/Changes> for
+more info.
+
 =cut
 
 OS/2 extensions