X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=README.os2;h=ab501ba28c36bf0f84d075d65bca729d9eed6dc3;hb=879fa96f55d904836d80046db7f8557649d93011;hp=a0b3d979d35ce4e199cfdaf369a3495cc5fc9cd8;hpb=2c2e0e8c03d67909bd8b889b6cdbb201bea519fc;p=p5sagit%2Fp5-mst-13.2.git diff --git a/README.os2 b/README.os2 index a0b3d97..ab501ba 100644 --- a/README.os2 +++ b/README.os2 @@ -112,9 +112,10 @@ Contents - Threading - Calls to external programs - Memory allocation + - Threads AUTHOR SEE ALSO - + =head1 DESCRIPTION =head2 Target @@ -130,20 +131,28 @@ The current state is quite close to this target. Known limitations: =item * -Some *nix programs use fork() a lot, but currently fork() is not -supported after Iing dynamically loaded extensions. +Some *nix programs use fork() a lot; with the mostly useful flavors of perl +for OS/2 (there are several built simultaneously) this is supported; +some flavors do not. Using fork() after Iing dynamically loading +extensions would not work with very old versions of EMX. =item * You need a separate perl executable F (see L) -to use PM code in your application (like the forthcoming Perl/Tk). +if you want to use PM code in your application (as Perl/Tk or OpenGL +Perl modules do) without having a text-mode window present. + +While using the standard F from a text-mode window is possible +too, I have seen cases when this causes degradation of the system stability. +Using F avoids such a degradation. =item * There is no simple way to access WPS objects. The only way I know is via C extension (see L), and we do not have access to convenience methods of Object-REXX. (Is it possible at all? I know -of no Object-REXX API.) +of no Object-REXX API.) The C extension (currently in alpha-text) +may eventually remove this shortcoming. =back @@ -152,7 +161,7 @@ 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 +run (and build extensions, and - possibly - be built 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">. @@ -177,13 +186,14 @@ has much more functions working (like C, C 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 +Only the latest runtime is supported, currently C<0.9d fix 03>. 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/ + http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/ + http://powerusersbbs.com/pub/os2/dev/ [EMX+GCC Development] + http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/ The runtime component should have the name F. @@ -214,9 +224,11 @@ One can get RSX from, say Contact the author on C. -The latest F with DOS hooks is available at +The latest F with DOS hooks is available in - ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.zip + ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/ + +as F or under similar names starting with C, C etc. =item HPFS @@ -231,15 +243,14 @@ read EMX docs to see how to do it. 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 , and located +shell. With EMX port such shell should be named F, and located either in the wired-in-during-compile locations (usually F), 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) as well, meanwhile use -the binary from +For best results use EMX pdksh. The standard binary (5.2.14 or later) runs +under DOS (with L) as well, see - ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.zip + ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/ =back @@ -251,7 +262,7 @@ 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 +opposed to your program), use perl -my_opts foo.pl arg1 arg2 arg3 @@ -266,7 +277,7 @@ rename your program to F, and start it by typing Note that because of stupid OS/2 limitations the full path of the perl script is not available when you use C, thus you are forced to -use C<-S> perl switch, and your script should be on path. As a plus +use C<-S> perl switch, and your script should be on the C. As a plus side, if you know a full path to your script, you may still start it with @@ -375,29 +386,37 @@ there is an executable file F I on C. 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 and F denote the +The workaround is as simple as that: since F and F denote the same file, to start an executable residing in file F (no -extension) give an argument C to system(). +extension) give an argument C (dot appended) 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, or start it using +Perl will correctly start PM programs from VIO (=text-mode) Perl process; +the opposite is not true: when you start a non-PM program from a PM +Perl process, it would not run it in a separate session. If a separate +session is desired, either ensure +that shell will be used, as in C, or start it using optional arguments to system() documented in C module. This -is considered a bug and should be fixed soon. - +is considered to be a feature. =head1 Frequently asked questions +=head2 "It does not work" + +Perl binary distributions come with a F script which tries +to detect common problems with misconfigured installations. There is a +pretty large chance it will discover which step of the installation you +managed to goof. C<;-)> + =head2 I cannot run external programs =over 4 -=item +=item * Did you run your programs with C<-w> switch? See L. -=item +=item * Do you try to run I shell commands, like C<`copy a b`> (internal for F), or C<`glob a*b`> (internal for ksh)? You @@ -443,7 +462,7 @@ Use one of This would start F via F via C via C, but this is a price to pay if you want to use non-conforming program. In fact F cannot be started at all -using C library API only. Otherwise the following command-lines were +using C library API only. Otherwise the following command-lines would be equivalent: find "pattern" file @@ -453,7 +472,7 @@ equivalent: =head2 Automatic binary installation -The most convenient way of installing perl is via perl installer +The most convenient way of installing a binary distribution of perl is via perl installer F. Just follow the instructions, and 99% of the installation blues would go away. @@ -541,26 +560,28 @@ LIBPATH); 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 +If this directory is exactly the same as the prefix which was compiled +into F, you do not need to change +anything. However, for perl to find the library if you use a different +path, you need to C in F, see L<"PERLLIB_PREFIX">. =item Additional Perl modules - unzip perl_ste.zip -d f:/perllib/lib/site_perl + unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.8.3/ -If you do not change this directory, do nothing. Otherwise put this +Same remark as above applies. Additionally, if this directory is not +one of directories on @INC (and @INC is influenced by C), you +need to put this directory and subdirectory F<./os2> in C or C variable. Do not use C unless you have it set already. See -L. +L. =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 in F, see L<"PERLLIB_PREFIX">. +Same remark as for F. =item Manpages for Perl and utilities @@ -580,7 +601,7 @@ working man to access these files. unzip perl_pod.zip -d f:/perllib/lib -This is used by by C program (see L), and may be used to +This is used by the C program (see L), and may be used to generate HTML documentation usable by WWW browsers, and documentation in zillions of other formats: C, C, C, C and so on. @@ -603,7 +624,7 @@ Set C (see L<"PERL_SH_DIR">) if you move F from the above location. B It may be possible to use some other sh-compatible shell -(I). +(file globbing - if done via shell - may break). =back @@ -688,6 +709,8 @@ on our C, like this set MANPATH=c:/man;f:/perllib/man +for Perl manpages in C etc. + =head2 HTML If you have some WWW browser available, installed the Perl @@ -722,7 +745,29 @@ can be constructed using C. =head1 BUILD Here we discuss how to build Perl under OS/2. There is an alternative -(but maybe older) view on L. +(but maybe older) view on http://www.shadow.net/~troc/os2perl.html + +=head2 The short story + +Assume that you are a seasoned porter, so are sure that all the necessary +tools are already present on your system, and you know how to get the Perl +source distribution. Untar it, change to the extract directory, and + + gnupatch -p0 < os2\diff.configure + sh Configure -des -D prefix=f:/perllib + make + make test + make install + make aout_test + make aout_install + +This puts the executables in f:/perllib/bin. Manually move them to the +C, manually move the built F to C (here F<*> is +a not-very-meaningful hex checksum), and run + + make installcmd INSTALLCMDDIR=d:/ir/on/path + +What follows is a detailed guide through these steps. =head2 Prerequisites @@ -747,14 +792,16 @@ Possible locations to get this from are 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: +build perl: F, F, F, F, +F, F, F, F and +F (or a later version). 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 +If you have I installed already, +make sure that no copies or perl are currently running. Later steps +of the build may fail since an older version of F loaded into memory may be found. Also make sure that you have F directory on the current drive, @@ -775,15 +822,15 @@ but may be not installed due to customization. If typing shows you do not have it, do I, and choose C in I. If you get into -link386, press C. +link386 prompts, press C to exit. =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 + http://www.cpan.org/src/5.0 + http://www.cpan.org/src/5.0/unsupported If not, you may need to dig in the indices to find it in the directory of the current maintainer. @@ -791,7 +838,7 @@ 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/ + http://www.cpan.org/ports/os2/ilyaz/ may indicate the latest release which was publicly released by the maintainer. Note that the release may include some additional patches @@ -808,38 +855,20 @@ 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: +You need to apply the patches in F<./os2/diff.*> 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 and F 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 +are not suitable for multi-threaded compile (even single-threaded +flavor of Perl uses multi-threaded C RTL, for compatibility with XFree86-OS/2). Get a corrected one from 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 @@ -854,79 +883,72 @@ correct prefix you may avoid the need to specify C, see L<"PERLLIB_PREFIX">. I, and about C<-c> option to -tr>. In fact if you can trace where the latter spurious warning -comes from, please inform me. +tr>. The latter is most probably already fixed, if you see it and can trace +where the latter spurious warning comes from, please inform me. Now make At some moment the built may die, reporting a I or -I>. This means that most of the build has been -finished, and it is the time to move the constructed F to -some I location in LIBPATH. After this is done the build -should finish without a lot of fuss. I on LIBPATH, but -probably this is not needed anymore, since F is linked -statically now.> - -Warnings which are safe to ignore: I inside -F. +I>. This means that you do not have F<.> in +your LIBPATH, so F cannot find the needed F (treat +these hex digits as line noise). After this is fixed the build +should finish without a lot of fuss. =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 -Some tests (4..6) should fail. Some perl invocations should end in a -segfault (system error C). To get finer error reports, call +All tests should succeed (with some of them skipped). - perl t/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 -Note that using C target two more tests may fail: C -because of (mis)feature of pdksh, and C, 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. I +If it persists, 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 tests pass. This means -that soon the number of failing tests may decrease yet more. +=item Process terminated by SIGTERM/SIGINT -However, the test F is disabled, since it never terminates, I -do not know why. Comments/fixes welcome. +This is a standard message issued by OS/2 applications. *nix +applications die in silence. It is considered to be a feature. One can +easily disable this by appropriate sighandlers. -The reasons for failed tests are: +However the test engine bleeds these message to screen in unexpected +moments. Two messages of this kind I be present during +testing. -=over 8 +=back + +To get finer test reports, call + + perl t/harness -=item F +The report with F failing may look like this: -Checks I operations. Tests: + 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 and C - nonesuch under OS/2. +=item F + +=over 4 =item 18 -Checks C and C of C - I could not understand this test. +Checks C and C of C - unfortunately, HPFS +provides only 2sec time granularity (for compatibility with FAT?). =item 25 @@ -935,78 +957,21 @@ know why this should or should not work. =back -=item F - -Checks C module. Some feature of EMX - test fork()s with -dynamic extension loaded - unsupported now. - -=item F - -Checks C module. Some feature of EMX - test fork()s -with dynamic extension loaded - unsupported now. - =item F Checks C. Tests: =over 4 -=item 3 - -Checks C - nonesuch under OS/2. - =item 4 -Checks C and C of C - I could not understand this test. - -=item 20 - -Checks C<-x> - determined by the file extension only under OS/2. - -=item 35 - -Needs F. - -=item 39 - -Checks C<-t> of F. Should not fail! +Checks C and C of C - unfortunately, HPFS +provides only 2sec time granularity (for compatibility with FAT?). =back =back -In addition to errors, you should get a lot of warnings. - -=over 4 - -=item A lot of C - -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 be present during -testing. - -=item F<*/sh.exe>: ln: not found - -=item C: /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 *nixish. - -=back - -A lot of C... 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 If you haven't yet moved perl.dll onto LIBPATH, do it now. @@ -1021,7 +986,7 @@ PATH, F to a location on your LIBPATH. Run - make cmdscripts INSTALLCMDDIR=d:/ir/on/path + make installcmd 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 @@ -1041,21 +1006,11 @@ test and install by Manually put F to a location on your PATH. -Since C has the extensions prebuilt, it does not suffer from -the I 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 The build process for C I about all the dependencies, so you should make sure that anything is up-to-date, say, by doing - make perl.dll + make perl_dll first. @@ -1086,6 +1041,10 @@ You did not run C. See L. You use an old version of GNU make. See L. +=head2 op/sprintf test failure + +This can result from a bug in emx sprintf which was fixed in 0.9d fix 03. + =head1 Specific (mis)features of OS/2 port =head2 C, C @@ -1094,28 +1053,75 @@ 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. Calling C 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 Multi-argument form of C allows an additional numeric argument. The meaning of this argument is described in L. +When finding a program to run, Perl first asks the OS to look for executables +on C (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 +first line as the beginning of the command line to run this script. The +only mangling done to the first line is extraction of arguments (currently +up to 3), and ignoring of the path-part of the "interpreter" name if it can't +be found using the full path. + +E.g., C may lead Perl to finding +F with the first line being + + extproc /bin/bash -x -c + +If F is not found, then Perl looks for an executable F on +C. If found in F, then the above system() is +translated to + + system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz) + +One additional translation is performed: instead of F Perl uses +the hardwired-or-customized shell (see C>). + +The above search for "interpreter" is recursive: if F executable is not +found, but F is found, Perl will investigate its first line etc. +The only hardwired limit on the recursion depth is implicit: there is a limit +4 on the number of additional arguments inserted before the actual arguments +given to system(). In particular, if no additional arguments are specified +on the "magic" first lines, then the limit on the depth is 4. + +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 to disable this magic. + +B. Due to the described logic, you need to explicitly +specify F<.com> extension if needed. Moreover, if the executable +F is requested, Perl will not look for F. +[This may change in the future.] + =head2 C on the first line -If the first chars of a script are C<"extproc ">, this line is treated +If the first chars of a Perl 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). +if script was started via cmd.exe). See L. =head2 Additional modules: -L, L, L, L. These +L, L, L, L, L. These modules provide access to additional numeric argument for C -and to the list of the running processes, -to DLLs having functions with REXX signature and to REXX runtime, to +and to the information about the running process, +to DLLs having functions with REXX signature and to the REXX runtime, to OS/2 databases in the F<.INI> format, and to Extended Attributes. Two additional extensions by Andreas Kaiser, C, and -C, are included into my ftp directory, mirrored on CPAN. +C, are included into C directory, mirrored on CPAN. =head2 Prebuilt methods: @@ -1139,6 +1145,7 @@ leaves drive as it is. =item C +chanes the "current" drive. =item C @@ -1162,7 +1169,7 @@ Really really odious function to implement. Returns absolute name of file which would have C if CWD were C. C defaults to the current dir. -=item C Get current value of extended library search path. If C is present and I, works with END_LIBPATH, otherwise with @@ -1174,28 +1181,136 @@ Set current value of extended library search path. If C is present and I, works with END_LIBPATH, otherwise with C. +=item C + +Returns C if it was not called yet, otherwise bit 1 is +set if on the previous call do_harderror was enabled, bit +2 is set if on previous call do_exception was enabled. + +This function enables/disables error popups associated with +hardware errors (Disk not ready etc.) and software exceptions. + +I know of no way to find out the state of popups I the first call +to this function. + +=item C + +Returns C if it was not called yet, otherwise return false if errors +were not requested to be written to a hard drive, or the drive letter if +this was requested. + +This function may redirect error popups associated with hardware errors +(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at +the root directory of the specified drive. Overrides OS2::Error() specified +by individual programs. Given argument undef will disable redirection. + +Has global effect, persists after the application exits. + +I know of no way to find out the state of redirection of popups to the disk +I the first call to this function. + +=item OS2::SysInfo() + +Returns a hash with system information. The keys of the hash are + + MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS, + MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION, + MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE, + VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION, + MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM, + TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL, + MAX_COMP_LENGTH, FOREGROUND_FS_SESSION, + FOREGROUND_PROCESS + +=item OS2::BootDrive() + +Returns a letter without colon. + +=item C, C + +Transforms the current application into a PM application and back. +The argument true means that a real message loop is going to be served. +OS2::MorphPM() returns the PM message queue handle as an integer. + +See L<"Centralized management of resources"> for additional details. + +=item C + +Fake on-demand retrieval of outstanding PM messages. If C is false, +will not dispatch messages if a real message loop is known to +be present. Returns number of messages retrieved. + +Dies with "QUITing..." if WM_QUIT message is obtained. + +=item C + +Retrieval of PM messages until window creation/destruction. +If C is false, will not dispatch messages if a real message loop +is known to be present. + +Returns change in number of windows. If C is given, +it is incremented by the number of messages retrieved. + +Dies with "QUITing..." if WM_QUIT message is obtained. + +=item C + +the same as L<_control87(3)> of EMX. Takes integers as arguments, returns +the previous coprocessor control word as an integer. Only bits in C which +are present in C are changed in the control word. + +=item OS2::get_control87() + +gets the coprocessor control word as an integer. + +=item C + +The variant of OS2::_control87() with default values good for +handling exception mask: if no C, uses exception mask part of C +only. If no C, disables all the floating point exceptions. + +See L<"Misfeatures"> for details. + =back (Note that some of these may be moved to different libraries - eventually). +=head2 Prebuilt variables: + +=over 4 + +=item $OS2::emx_rev + +same as _emx_rev of EMX, a string similar to C<0.9c>. + +=item $OS2::emx_env + +same as _emx_env of EMX, a number similar to 0x8001. + +=item $OS2::os_ver + +a number C. + +=back + =head2 Misfeatures =over 4 -=item +=item * Since L is present in EMX, but is not functional, it is emulated by perl. To disable the emulations, set environment variable C. -=item +=item * Here is the list of things which may be "broken" on EMX (from EMX docs): -=over +=over 4 =item * @@ -1226,7 +1341,7 @@ L: Note that C does not work with the current version of EMX. -=item +=item * Since F is used for globing (see L), the bugs of F plague perl as well. @@ -1234,6 +1349,53 @@ of F plague perl as well. In particular, uppercase letters do not work in C<[...]>-patterns with the current pdksh. +=item * + +Unix-domain sockets on OS/2 live in a pseudo-file-system C. +To avoid a failure to create a socket with a name of a different form, +C<"/socket/"> is prepended to the socket name (unless it starts with this +already). + +This may lead to problems later in case the socket is accessed via the +"usual" file-system calls using the "initial" name. + +=item * + +Apparently, IBM used a compiler (for some period of time around '95?) which +changes FP mask right and left. This is not I bad for IBM's +programs, but the same compiler was used for DLLs which are used with +general-purpose applications. When these DLLs are used, the state of +floating-point flags in the application is not predictable. + +What is much worse, some DLLs change the floating point flags when in +_DLLInitTerm() (e.g., F). This means that even if you do not I +any function in the DLL, just the act of loading this DLL will reset your +flags. What is worse, the same compiler was used to compile some HOOK DLLs. +Given that HOOK dlls are executed in the context of I the applications +in the system, this means a complete unpredictablity of floating point +flags on systems using such HOOK DLLs. E.g., F of B +origin changes the floating point flags on each write to the TTY of a VIO +(windowed text-mode) applications. + +Some other (not completely debugged) situations when FP flags change include +some video drivers (?), and some operations related to creation of the windows. +People who code B may have more experience on this. + +Perl is generally used in the situation when all the floating-point +exceptions are ignored, as is the default under EMX. If they are not ignored, +some benign Perl programs would get a C and would die a horrible death. + +To circumvent this, Perl uses two hacks. They help against I type of +damage only: FP flags changed when loading a DLL. + +One of the hacks is to disable floating point exceptions on startup (as +is the default with EMX). This helps only with compile-time-linked DLLs +changing the flags before main() had a chance to be called. + +The other hack is to restore FP flags after a call to dlopen(). This helps +against similar damage done by DLLs _DLLInitTerm() at runtime. Currently +no way to switch these hacks off is provided. + =back =head2 Modifications @@ -1264,6 +1426,11 @@ a dummy implementation. C special-cases F and F. +=item C, C + +these EMX functions do not work if the path contains a trailing C. +Perl contains a workaround for this. + =item C Since L is present in EMX, but is not functional, it is @@ -1272,6 +1439,70 @@ C. =back +=head2 Identifying DLLs + +All the DLLs built with the current versions of Perl have ID strings +identifying the name of the extension, its version, and the version +of Perl required for this DLL. Run C to find this +info. + +=head2 Centralized management of resources + +Since to call certain OS/2 API one needs to have a correctly initialized +C subsystem, OS/2-specific extensions may require getting Cs and +Cs. If an extension would do it on its own, another extension could +fail to initialize. + +Perl provides a centralized management of these resources: + +=over + +=item C + +To get the HAB, the extension should call C in C. After +this call is performed, C may be accessed as C. There is +no need to release the HAB after it is used. + +If by some reasons F cannot be included, use + + extern int Perl_hab_GET(void); + +instead. + +=item C + +There are two cases: + +=over + +=item * + +the extension needs an C only because some API will not work otherwise. +Use C below. + +=item * + +the extension needs an C since it wants to engage in a PM event loop. +Use C below. + +=back + +To get an C, the extension should call C in C. +After this call is performed, C may be accessed as C. + +To signal to Perl that HMQ is not needed any more, call +C. Perl process will automatically morph/unmorph itself +into/from a PM process if HMQ is needed/not-needed. Perl will automatically +enable/disable C message during shutdown if the message queue is +served/not-served. + +B. If during a shutdown there is a message queue which did not disable +WM_QUIT, and which did not process the received WM_QUIT message, the +shutdown will be automatically cancelled. Do not call C +unless you are going to process messages on an orderly basis. + +=back + =head1 Perl flavors Because of idiosyncrasies of OS/2 one cannot have all the eggs in the @@ -1286,29 +1517,19 @@ C-style executable, but is linked with C-style dynamic library F, 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). +It can load perl dynamic extensions, and it can fork(). B Keep in mind that fork() is needed to open a pipe to yourself. =head2 F -This is a statically linked C-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, like fork()ing when -having some standard extension loaded. This executable is a VIO +This is a statically linked C-style executable. It cannot +load dynamic Perl extensions. The executable supplied in binary +distributions has a lot of extensions prebuilt, thus the above restriction is +important only if you use custom-built extensions. This executable is a VIO application. -B A better behaviour could be obtained from C if it -were statically linked with standard I, but -dynamically linked with the I and CRT DLL. Then it would -be able to fork() with standard extensions, I would be able to -dynamically load arbitrary extensions. Some changes to Makefiles and -hint files should be necessary to achieve this. - -I The +I The friends locked into C 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">. @@ -1318,15 +1539,30 @@ appropriate extender. See L<"Other OSes">. This is the same executable as F, but it is a PM application. -B Usually STDIN, STDERR, and STDOUT of a PM -application are redirected to C. However, it is possible to see +B Usually (unless explicitly redirected during the startup) +STDIN, STDERR, and STDOUT of a PM +application are redirected to F. However, it is possible to I them if you start C from a PM program which emulates a console window, like I of Emacs or EPM. Thus it I to use Perl debugger (see L) to debug your PM -application. +application (but beware of the message loop lockups - this will not +work if you have a message queue to serve, unless you hook the serving +into the getc() function of the debugger). -This flavor is required if you load extensions which use PM, like -the forthcoming C. +Another way to see the output of a PM program is to run it as + + pm_prog args 2>&1 | cat - + +with a shell I from F, so that it does not create +a link between a VIO session and the session of C. (Such a link +closes the VIO window.) E.g., this works with F - or with Perl! + + open P, 'pm_prog args 2>&1 |' or die; + print while

; + +The flavor F is required if you want to start your program without +a VIO window present, but not Ced (run C for more info). +Very useful for extensions which use PM, like C or C. =head2 F @@ -1352,37 +1588,67 @@ digits (which have absolutely different semantics). 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. +additional work to make it compile. The reason is the complicated-to-developers +but very quick and convenient-to-users "hard" dynamic linking used by OS/2. + +There are two distinctive features of the dyna-linking model of OS/2: +all the references to external functions are resolved at the compile time; +there is no runtime fixup of the DLLs after they are loaded into memory. +The first feature is an enormous advantage over other models: it avoids +conflicts when several DLLs used by an application export entries with +the same name. In such cases "other" models of dyna-linking just choose +between these two entry points using some random criterion - with predictable +disasters as results. But it is the second feature which requires the build +of F. 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. +loaded. The addresses of the entry points into DLLs are guaranteed to be +the same for all the programs which use the same DLL. This removes the +runtime fixup - once DLL is loaded, its code is read-only. -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. +While this allows some (significant?) performance advantages, this makes life +much harder for developers, since the above scheme makes it impossible +for a DLL to be "linked" to a symbol in the F<.EXE> file. Indeed, this +would need a DLL to have different relocations tables for the +(different) executables which use this DLL. + +However, a dynamically loaded Perl extension is forced to use some symbols +from the perl +executable, e.g., to know how to find the arguments to the functions: +the arguments live on the perl +internal evaluation stack. The solution is to put the main code of +the interpreter into a DLL, and make the F<.EXE> file which just loads +this DLL into memory and supplies command-arguments. The extension DLL +cannot link to symbols in F<.EXE>, but it has no problem linking +to symbols in the F<.DLL>. This I 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). +complexity of the compilation). Since interpreter is in a DLL, +the C RTL is basically forced to reside in a DLL as well (otherwise +extensions would not be able to use CRT). There are some advantages if +you use different flavors of perl, such as running F and +F simultaneously: they share the memory of F. + +B. There is one additional effect which makes DLLs more wasteful: +DLLs are loaded in the shared memory region, which is a scarse resource +given the 512M barrier of the "standard" OS/2 virtual memory. The code of +F<.EXE> files is also shared by all the processes which use the particular +F<.EXE>, but they are "shared in the private address space of the process"; +this is possible because the address at which different sections +of the F<.EXE> file are loaded is decided at compile-time, thus all the +processes have these sections loaded at same addresses, and no fixup +of internal links inside the F<.EXE> is needed. + +Since DLLs may be loaded at run time, to have the same mechanism for DLLs +one needs to have the address range of I DLLs in the +system to be available I which did not load a particular +DLL yet. This is why the DLLs are mapped to the shared memory region. =head2 Why chimera build? Current EMX environment does not allow DLLs compiled using Unixish -C format to export symbols for data. This forces C-style -compile of F. +C format to export symbols for data (or at least some types of +data). This forces C-style compile of F. Current EMX environment does not allow F<.EXE> files compiled in C format to fork(). fork() is needed for exactly three Perl @@ -1390,20 +1656,23 @@ operations: =over 4 -=item explicit fork() +=item * -in the script, and +explicit fork() in the script, -=item open FH, "|-" +=item * -=item open FH, "-|" +C -opening pipes to itself. +=item * + +C, in other words, 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-style compile of +While these operations are not questions of life and death, they are +needed for a lot of +useful scripts. This forces C-style compile of F. @@ -1427,22 +1696,41 @@ substituted with F. Should be used if the perl library is moved from the default location in preference to C, since this would not leave wrong -entries in @INC. Say, if the compiled version of perl looks for @INC +entries in @INC. For example, if the compiled version of perl looks for @INC in F, and you want to install the library in F, do set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu +This will cause Perl with the prebuilt @INC of + + f:/perllib/lib/5.00553/os2 + f:/perllib/lib/5.00553 + f:/perllib/lib/site_perl/5.00553/os2 + f:/perllib/lib/site_perl/5.00553 + . + +to use the following @INC: + + h:/opt/gnu/5.00553/os2 + h:/opt/gnu/5.00553 + h:/opt/gnu/site_perl/5.00553/os2 + h:/opt/gnu/site_perl/5.00553 + . + =head2 C -If 1, perl ignores setlocale() failing. May be useful with some +If 0, perl ignores setlocale() failing. May be useful with some strange Is. =head2 C -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. +If 0, perl would not warn of in case of unwarranted free(). With older +perls this might be +useful in conjunction with the module DB_File, which was buggy when +dynamically linked and OMF-built. + +Should not be set with newer Perls, since this may hide some I problems. =head2 C @@ -1457,8 +1745,7 @@ environment variable C. =head2 C or C -Specific for EMX port. Used as storage place for temporary files, most -notably C<-e> scripts. +Specific for EMX port. Used as storage place for temporary files. =head1 Evolution @@ -1469,21 +1756,180 @@ Here we list major changes which could make you by surprise. C and C 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. In particular, DLLs are now created with the names +should be rebuilt when a different version of Perl is compiled. In particular, +DLLs (including F) are now created with the names which contain a checksum, thus allowing workaround for OS/2 scheme of caching DLLs. +It may be possible to code a simple workaround which would + +=over + +=item * + +find the old DLLs looking through the old @INC; + +=item * + +mangle the names according to the scheme of new perl and copy the DLLs to +these names; + +=item * + +edit the internal C tables of DLL to reflect the change of the name +(probably not needed for Perl extension DLLs, since the internally coded names +are not used for "specific" DLLs, they used only for "global" DLLs). + +=item * + +edit the internal C tables and change the name of the "old" +F to the "new" F. + +=back + +=head2 DLL name mangling: 5.6.2 and beyond + +In fact mangling of I 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; 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 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 and C + +(which depend on the process) + +=item F<.> from C + +which I depends on the process (although C is the +same for all the processes). + +=back + +Unless C is set to C (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 and C, or F<.> from C may affect +I DLL is loaded when I executable requests a DLL with +the same name. I 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 of old extension DLLs +if @INC allows finding their directories. + +However, this still does not guarantee that these DLL may be loaded. +The reason is the mangling of the name of the I. 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 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 executable. 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 this may be circumvented - unless +one of DLLs is started from F<.> from C (I do not know +whether C affects this case). + +B. Unless newer kernels allow F<.> in C (older +do not), this mess cannot be completely cleaned. + + +B. C, C and C are +not environment variables, although F emulates them on C lines. From Perl they may be accessed by L and +L. + +=head2 DLL forwarder generation + +Assume that the old DLL is named F (as is one for +5.005_53), and the new version is 5.6.1. Create a file +F 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). + =head2 Threading -As of release 5.003_01 perl is linked to multithreaded CRT -DLL. If perl itself is not compiled multithread-enabled, so will not be perl +As of release 5.003_01 perl is linked to multithreaded C RTL +DLL. If perl itself is not compiled multithread-enabled, so will not be perl's malloc(). However, extensions may use multiple thread on their own risk. -Needed to compile C for XFree86-OS/2 out-of-the-box. +This was needed to compile C for XFree86-OS/2 out-of-the-box, and +link with DLLs for other useful libraries, which typically are compiled +with C<-Zmt -Zcrtdll>. =head2 Calls to external programs @@ -1493,21 +1939,21 @@ external program I, the F 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 as well (I -use one from pdksh). The drive F above is set up automatically during +use one from pdksh). The path F above is set up automatically during the build to a correct value on the builder machine, but is overridable at runtime, B a consensus on C was that perl should use one non-overridable shell per platform. The obvious choices for OS/2 are F and F. Having perl build itself would be impossible -with F as a shell, thus I picked up C. Thus assures almost +with F as a shell, thus I picked up C. This 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 currently F of pdksh calls external programs via fork()/exec(), and there is I functioning exec() on -OS/2. exec() is emulated by EMX by asyncroneous call while the caller +OS/2. exec() is emulated by EMX by an asynchronous call while the caller waits for child completion (to pretend that the C did not change). This means that 1 I copy of F is made active via fork()/exec(), which may lead to some resources taken from the system (even if we do @@ -1536,28 +1982,31 @@ 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. +see L. Set us mention a couple +of features: -=over +=over 4 -=item +=item * -External scripts may be called by name. Perl will try the same extensions -as when processing B<-S> command-line switch. +External scripts may be called by their basename. Perl will try the same +extensions as when processing B<-S> command-line switch. + +=item * + +External scripts starting with C<#!> or C will be executed directly, +without calling the shell, by calling the program specified on the rest of +the first line. =back =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 quicker +than EMX one. I do not have convincing data about memory footprint, but +a (pretty random) benchmark showed that Perl's 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 @@ -1566,6 +2015,36 @@ such functions, system memory-allocation functions are still available with the prefix C added. (Currently only DLL perl has this, it should propagate to F shortly.) +=head2 Threads + +One can build perl with thread support enabled by providing C<-D usethreads> +option to F. Currently OS/2 support of threads is very +preliminary. + +Most notable problems: + +=over 4 + +=item C + +may have a race condition. Needs a reimplementation (in terms of chaining +waiting threads, with the linked list stored in per-thread structure?). + +=item F + +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. + +=head1 BUGS + +This description was not updated since 5.6.1, see F for +more info. + =cut OS/2 extensions