1 If you read this file _as_is_, just ignore the funny characters you
2 see. It is written in the POD format (see perlpod manpage) which is
3 specially designed to be readable as is.
7 perlos2 - Perl under OS/2, Win0.31, Win0.95 and WinNT.
11 One can read this document in the following formats:
18 to list some (not all may be available simultaneously), or it may
19 be read I<as is>: either as F<README.os2>, or F<pod/perlos2.pod>.
25 perlos2 - Perl under OS/2
33 - Starting Perl programs under OS/2
34 - Starting OS/2 programs under Perl
35 Frequently asked questions
36 - I cannot run extenal programs
37 - I cannot embed perl into my program, or use perl.dll from my program.
39 - Automatic binary installation
40 - Manual binary installation
42 Accessing documentation
53 - Application of the patches
57 - Installing the built perl
60 - Some / became \ in pdksh.
61 - 'errno' - unresolved external
63 - Some problem (forget which ;-)
64 - Library ... not found
66 Specific (mis)features of OS/2 port
67 - setpriority, getpriority
78 - Why dynamic linking?
90 - Calls to external programs
98 The target is to make OS/2 the best supported platform for
99 using/building/developping Perl and I<Perl applications>, as well as
100 make Perl the best language to use under OS/2.
102 The current state is quite close to this target. Known limitations:
108 Some *nix programs use fork() a lot, but currently fork() is not
109 supported after I<use>ing dynamically loaded extensions.
113 You need a separate perl executable F<perl__.exe> (see L<perl__.exe>)
114 to use PM code in your application (like the forthcoming Perl/Tk).
118 There is no simple way to access B<WPS> objects. The only way I know
119 is via C<OS2::REXX> extension (see L<OS2::REXX>), and we do not have access to
120 convinience methods of B<Object REXX>. (Is it possible at all? I know
121 of no B<Object-REXX> API.)
125 Please keep this list up-to-date by informing me about other items.
129 Since OS/2 port of perl uses a remarkable B<EMX> environment, it can
130 run (and build extensions, and - possibly - be build itself) under any
131 environment which can run EMX. The current list is DOS,
132 DOS-inside-OS/2, Win0.31, Win0.95 and WinNT. Out of many perl flavors,
133 only one works, see L<"perl_.exe">.
135 Note that not all features of Perl are available under these
136 environments. This depends on the features the I<extender> - most
137 probably C<RSX> - decided to implement.
139 Cf. L<Prerequisites>.
147 B<EMX> runtime is required (may be substituted by B<RSX>). Note that
148 it is possible to make F<perl_.exe> to run under DOS without any
149 external support by binding F<emx.exe> to it, see L<emxbind>. Note
150 that under DOS for best results one should use B<RSX> runtime, which
151 has much more functions working (like C<fork>, C<popen> and so on). In
152 fact B<RSX> is required if there is no C<VCPI> present.
154 Only the latest runtime is supported, currently C<0.9c>.
156 One can get different parts of B<EMX> from, say
158 ftp://ftp.cdrom.com/pub/os2/emx0.9c/
159 ftp://hobbes.nmsu.edu/os2/unix/gnu/
161 The runtime component should have the name F<emxrt.zip>.
165 To run Perl on C<DPMS> platforms one needs B<RSX> runtime. This is
166 needed under DOS-inside-OS/2, Win0.31, Win0.95 and WinNT (see
167 L<"Other OSes">). I do not know whether B<RSX> would work with C<VCPI>
168 only, as B<EMX> would.
170 Having B<RSX> and the latest F<sh.exe> one gets a fully functional
171 B<*nix>-ish environment under DOS, say, C<fork>, C<``> and
172 pipe-C<open> work. In fact, MakeMaker works (for static build), so one
173 can have Perl development environment under DOS.
175 One can get B<RSX> from, say
177 ftp://ftp.cdrom.com/pub/os2/emx0.9c/contrib
178 ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
180 Contact the author on C<rainer@mathematik.uni-bielefeld.de>.
182 The latest F<sh.exe> with DOS hooks is available at
184 ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/sh_dos.exe
188 Perl does not care about file systems, but to install the whole perl
189 library intact one needs a file system which supports long file names.
191 Note that if you do not plan to build the perl itself, it may be
192 possible to fool B<EMX> to truncate file names. This is not supported,
193 read B<EMX> docs to see how to do it.
197 =head2 Starting Perl programs under OS/2
199 Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the
200 same way as on any other platform, by
202 perl foo.pl arg1 arg2 arg3
204 If you want to specify perl options C<-my_opts> to the perl itself (as
205 opposed to to your program), use
207 perl -my_opts foo.pl arg1 arg2 arg3
209 Alternately, if you use OS/2-ish shell, like C<CMD> or C<4os2>, put
210 the following at the start of your perl script:
213 #!/usr/bin/perl -my_opts
215 rename your program to F<foo.cmd>, and start it by typing
219 (Note that having *nixish full path to perl F</usr/bin/perl> is not
220 necessary, F<perl> would be enough, but having full path would make it
221 easier to use your script under *nix.)
223 Note that because of stupid OS/2 limitations the full path of the perl
224 script is not available when you use C<extproc>, thus you are forced to
225 use C<-S> perl switch, and your script should be on path. As a plus
226 side, if you know a full path to your script, you may still start it
229 perl -x ../../blah/foo.cmd arg1 arg2 arg3
231 (note that the argument C<-my_opts> is taken care of by the C<#!> line
234 To understand what the above I<magic> does, read perl docs about C<-S>
235 and C<-x> switches - see L<perlrun>, and cmdref about C<extproc>:
242 or whatever method you prefer.
244 There are also endless possibilites to use I<executable extensions> of
245 B<4OS2>, I<associations> of B<WPS> and so on... However, if you use
246 *nixish shell (like F<sh.exe> supplied in the binary distribution),
247 you need follow the syntax specified in L<perlrun/"Switches">.
249 =head2 Starting OS/2 programs under Perl
251 This is what system() (see L<perlfunc/system>), C<``> (see
252 L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>)
253 are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you
256 Note however that to use some of these operators you need to have a
257 C<sh>-syntax shell installed (see L<"Pdksh">,
258 L<"Frequently asked questions">), and perl should be able to find it
259 (see L<"PERL_SH_DIR">).
261 The only cases when the shell is not used is the multi-argument
262 system() (see L<perlfunc/system>)/exec() (see L<perlfunc/exec>), and
263 one-argument version thereof without redirection and shell
266 =head1 Frequently asked questions
268 =head2 I cannot run extenal programs
274 Did you run your programs with C<-w> switch? See
275 L<Starting OS/2 programs under Perl>.
279 Do you try to run I<internal> shell commands, like C<`copy a b`>
280 (internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You
281 need to specify your shell explicitely, like C<`cmd /c copy a b`>,
282 since Perl cannot deduce which commands are internal to your shell.
286 =head2 I cannot embed perl into my program, or use F<perl.dll> from my
291 =item Is your program B<EMX>-compiled with C<-Zmt -Zcrtdll>?
293 If not, you need to build a stand-alone DLL for perl. Contact me, I
294 did it once. Sockets would not work, as a lot of other stuff.
296 =item Did you use C<ExtUtils::Embed>?
298 I had reports it does not work. Somebody would need to fix it.
302 =head2 C<``> and pipe-C<open> do not work under DOS.
304 This may a variant of just L<"I cannot run extenal programs">, or a
305 deeper problem. Basically: you I<need> B<RSX> (see L<"Prerequisites">)
306 for these commands to work, and you need a port of F<sh.exe> which
307 understands command arguments. One of such ports is listed in
308 L<"Prerequisites"> under B<RSX>.
310 I do not know whether C<DPMI> is required.
314 =head2 Automatic binary installation
316 The most convinient way of installing perl is via perl installer
317 F<install.exe>. Just follow the instructions, and 99% of the
318 installation blues would go away.
320 Note however, that you need to have F<unzip.exe> on your path, and
321 B<EMX> environment I<running>. The latter means that if you just
322 installed B<EMX>, and made all the needed changes to F<Config.sys>,
323 you may need to reboot in between. Check B<EMX> runtime by running
327 A folder is created on your desktop which contains some useful
330 B<Things not taken care of by automatic binary installation:>
334 =item C<PERL_BADLANG>
336 may be needed if you change your codepage I<after> perl installation,
337 and the new value is not supported by B<EMX>. See L<"PERL_BADLANG">.
339 =item C<PERL_BADFREE>
341 see L<"PERL_BADFREE">.
345 This file resides somewhere deep in the location you installed your
346 perl library, find it out by
348 perl -MConfig -le "print $INC{'Config.pm'}"
350 While most important values in this file I<are> updated by the binary
351 installer, some of them may need to be hand-edited. I know no such
352 data, please keep me informed if you find one.
356 =head2 Manual binary installation
358 As of version 5.00305, OS/2 perl binary distribution comes splitted
359 into 11 components. Unfortunately, to enable configurable binary
360 installation, the file paths in the C<zip> files are not absolute, but
361 relative to some directory.
363 Note that the extraction with the stored paths is still necessary
364 (default with C<unzip>, specify C<-d> to C<pkunzip>). However, you
365 need to know where to extract the files. You need also to manually
366 change entries in F<Config.sys> to reflect where did you put the
369 Below is the sample of what to do to reproduce the configuration on my
374 =item Perl VIO and PM executables (dynamically linked)
376 unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
377 unzip perl_exc.zip *.dll -d f:/emx.add/dll
379 (have the directories with C<*.exe> on C<PATH>, and C<*.dll> on
382 =item Perl_ VIO executable (statically linked)
384 unzip perl_aou.zip -d f:/emx.add/bin
386 (have the directory on C<PATH>);
388 =item Executables for Perl utilities
390 unzip perl_utl.zip -d f:/emx.add/bin
392 (have the directory on C<PATH>);
394 =item Main Perl library
396 unzip perl_mlb.zip -d f:/perllib/lib
398 If this directory is preserved, you do not need to change
399 anything. However, for perl to find it if it is changed, you need to
400 C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
402 =item Additional Perl modules
404 unzip perl_ste.zip -d f:/perllib/lib/site_perl
406 If you do not change this directory, do nothing. Otherwise put this
407 directory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB>
408 variable. Do not use C<PERL5LIB> unless you have it set already. See
409 L<perl/"ENVIRONMENT">.
411 =item Tools to compile Perl modules
413 unzip perl_blb.zip -d f:/perllib/lib
415 If this directory is preserved, you do not need to change
416 anything. However, for perl to find it if it is changed, you need to
417 C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
419 =item Manpages for Perl and utilities
421 unzip perl_man.zip -d f:/perllib/man
423 This directory should better be on C<MANPATH>. You need to have a
424 working C<man> to access these files.
426 =item Manpages for Perl modules
428 unzip perl_mam.zip -d f:/perllib/man
430 This directory should better be on C<MANPATH>. You need to have a
431 working C<man> to access these files.
433 =item Source for Perl documentation
435 unzip perl_pod.zip -d f:/perllib/lib
437 This is used by by C<perldoc> program (see L<perldoc>), and may be used to
438 generate B<HTML> documentation usable by WWW browsers, and
439 documentation in zillions of other formats: C<info>, C<LaTeX>,
440 C<Acrobat>, C<FrameMaker> and so on.
442 =item Perl manual in .INF format
444 unzip perl_inf.zip -d d:/os2/book
446 This directory should better be on C<BOOKSHELF>.
450 unzip perl_sh.zip -d f:/bin
452 This is used by perl to run external commands which explicitely
453 require shell, like the commands using I<redirection> and I<shell
454 metacharacters>. It is also used instead of explicit F</bin/sh>.
456 Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
459 B<Note.> It may be possible to use some other C<sh>-compatible shell
464 After you installed the components you needed and updated the
465 F<Config.sys> correspondingly, you need to hand-edit
466 F<Config.pm>. This file resides somewhere deep in the location you
467 installed your perl library, find it out by
469 perl -MConfig -le "print $INC{'Config.pm'}"
471 You need to correct all the entries which look like file paths (they
472 currently start with C<f:/>).
476 The automatic and manual perl installation leave precompiled paths
477 inside perl executables. While these paths are overwriteable (see
478 L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), one may get better results by
479 binary editing of paths inside the executables/DLLs.
481 =head1 Accessing documentation
483 Depending on how you built/installed perl you may have (otherwise
484 identical) Perl documentation in the following formats:
486 =head2 OS/2 F<.INF> file
488 Most probably the most convinient form. View it as
493 view perl ExtUtils::MakeMaker
495 (currently the last two may hit a wrong location, but this may improve
498 If you want to build the docs yourself, and have I<OS/2 toolkit>, run
502 in F</perllib/lib/pod> directory, then
506 (Expect a lot of errors during the both steps.) Now move it on your
511 If you have perl documentation in the source form, perl utilities
512 installed, and B<GNU> C<groff> installed, you may use
516 perldoc ExtUtils::MakeMaker
518 to access the perl documention in the text form (note that you may get
519 better results using perl manpages).
521 Alternately, try running pod2text on F<.pod> files.
525 If you have C<man> installed on your system, and you installed perl
526 manpages, use something like this:
530 man ExtUtils.MakeMaker
532 to access documentation for different components of Perl. Start with
536 Note that dot (F<.>) is used as a package separator for documentation
537 for packages, and as usual, sometimes you need to give the section - C<3>
538 above - to avoid shadowing by the I<less(1) manpage>.
540 Make sure that the directory B<above> the directory with manpages is
541 on our C<MANPATH>, like this
543 set MANPATH=c:/man;f:/perllib/man
547 If you have some WWW browser available, installed the Perl
548 documentation in the source form, and Perl utilities, you can build
549 B<HTML> docs. Cd to directory with F<.pod> files, and do like this
551 cd f:/perllib/lib/pod
554 After this you can direct your browser the file F<perl.html> in this
555 directory, and go ahead with reading docs, like this:
557 explore file:///f:/perllib/lib/pod/perl.html
559 Alternatively you may be able to get these docs prebuild from C<CPAN>.
561 =head2 B<GNU> C<info> files
563 Users of C<Emacs> would appreciate it very much, especially with
564 C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
565 or, alternately, prebuilt info pages.
569 for C<Acrobat> are available on CPAN (for slightly old version of
574 can be constructed using C<pod2latex>.
578 Here we discuss how to build Perl under OS/2. There is an alternative
579 (but maybe older) view on L<http://www.shadow.net/~troc/os2perl.html>.
583 You need to have the latest B<EMX> development environment, the full
584 B<GNU> tool suite (C<gawk> renamed to C<awk>, and B<GNU> F<find.exe>
585 earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to
591 ). You need the latest version of F<pdksh> installed as F<sh.exe>.
593 Possible locations to get this from are
595 ftp://hobbes.nmsu.edu/os2/unix/gnu/
596 ftp://ftp.cdrom.com/pub/os2/unix/
597 ftp://ftp.cdrom.com/pub/os2/dev32/
598 ftp://ftp.cdrom.com/pub/os2/emx0.9c/
601 Make sure that no copies or perl are currently running. Later steps
602 of the build may fail since an older version of perl.dll loaded into
605 Also make sure that you have F</tmp> directory on the current drive,
606 and F<.> directory in your C<LIBPATH>. One may try to correct the
611 if you use something like F<CMD.EXE> or latest versions of F<4os2.exe>.
613 Make sure your C<gcc> is good for C<-Zomf> linking: run C<omflibs>
614 script in F</emx/lib> directory.
616 Check that you have C<link386> installed. It comes standard with OS/2,
617 but may be not installed due to customization. If typing
621 shows you do not have it, do I<Selective install>, and choose C<Link
622 object modules> in I<Optional system utilites/More>. If you get into
623 C<link386>, press C<Ctrl-C>.
625 =head2 Getting perl source
627 You need to fetch the latest perl source (including developpers
628 releases). With some probability it is located in
630 http://www.perl.com/CPAN/src/5.0
631 http://www.perl.com/CPAN/src/5.0/unsupported
633 If not, you may need to dig in the indices to find it in the directory
634 of the current maintainer.
636 Quick cycle of developpers release may break the OS/2 build time to
639 http://www.perl.com/CPAN/ports/os2/ilyaz/
641 may indicate the latest release which was publicly released by the
642 maintainer. Note that the release may include some additional patches
643 to apply to the current source of perl.
647 tar vzxf perl5.00409.tar.gz
649 You may see a message about errors while extracting F<Configure>. This is
650 because there is a conflict with a similarly-named file F<configure>.
652 Rename F<configure> to F<configure.gnu>. Extract F<Configure> like this
654 tar --case-sensitive -vzxf perl5.00409.tar.gz perl5.00409/Configure
656 Change to the directory of extraction.
658 =head2 Application of the patches
660 You need to apply the patches in F<./os2/diff.*> and
661 F<./os2/POSIX.mkfifo> like this:
663 gnupatch -p0 < os2\POSIX.mkfifo
664 gnupatch -p0 < os2\os2\diff.configure
666 You may also need to apply the patches supplied with the binary
667 distribution of perl.
669 Note also that the F<db.lib> and F<db.a> from the B<EMX> distribution
670 are not suitable for multi-threaded compile (note that currently perl
671 is not multithreaded, but is compiled as multithreaded for
672 compatibility with B<XFree86>-OS/2). Get a corrected one from
674 ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip
678 You may look into the file F<./hints/os2.sh> and correct anything
679 wrong you find there. I do not expect it is needed anywhere.
683 sh Configure -des -D prefix=f:/perllib
685 Prefix means where to install the resulting perl library. Giving
686 correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
687 see L<"PERLLIB_PREFIX">.
689 I<Ignore the message about missing C<ln>, and about C<-c> option to
690 C<tr>>. In fact if you can trace where the latter spurious warning
691 comes from, please inform me.
697 At some moment the built may die, reporting a I<version mismatch> or
698 I<unable to run F<perl>>. This means that most of the build has been
699 finished, and it is the time to move the constructed F<perl.dll> to
700 some I<absolute> location in C<LIBPATH>. After this done the build
701 should finish without a lot of fuss. I<One can avoid it if one has the
702 correct prebuilt version of F<perl.dll> on C<LIBPATH>.>
704 Warnings which are safe to ignore: I<mkfifo() redefined> inside
713 Some tests (5..7) should fail. Some perl invocations should end in a
714 segfault (system error C<SYS3175>). To get finer error reports,
717 perl -I ../lib harness
719 The report you get may look like
721 Failed Test Status Wstat Total Fail Failed List of failed
722 ---------------------------------------------------------------
723 io/fs.t 26 11 42.31% 2-5, 7-11, 18, 25
724 lib/io_pipe.t 3 768 6 ?? % ??
725 lib/io_sock.t 3 768 5 ?? % ??
726 op/stat.t 56 5 8.93% 3-4, 20, 35, 39
727 Failed 4/118 test scripts, 96.61% okay. 27/2445 subtests failed, 98.90% okay.
729 Note that using `make test' target two more tests may fail: C<op/exec:1>
730 because of (mis)feature of C<pdksh>, and C<lib/posix:15>, which checks
731 that the buffers are not flushed on C<_exit> (this is a bug in the test
732 which assumes that tty output is buffered).
734 The reasons for failed tests are:
740 Checks I<file system> operations. Tests:
746 Check C<link()> and C<inode count> - nonesuch under OS/2.
750 Checks C<atime> and C<mtime> of C<stat()> - I could not understand this test.
754 Checks C<truncate()> on a filehandle just opened for write - I do not
755 know why this should or should not work.
759 =item F<lib/io_pipe.t>
761 Checks C<IO::Pipe> module. Some feature of B<EMX> - test fork()s with
762 dynamic extension loaded - unsupported now.
764 =item F<lib/io_sock.t>
766 Checks C<IO::Socket> module. Some feature of B<EMX> - test fork()s
767 with dynamic extension loaded - unsupported now.
771 Checks C<stat()>. Tests:
777 Checks C<inode count> - nonesuch under OS/2.
781 Checks C<mtime> and C<ctime> of C<stat()> - I could not understand this test.
785 Checks C<-x> - determined by the file extension only under OS/2.
793 Checks C<-t> of F</dev/null>. Should not fail!
799 In addition to errors, you should get a lot of warnings.
803 =item A lot of `bad free'
805 in databases related to Berkeley DB. This is a confirmed bug of
806 DB. You may disable this warnings, see L<"PERL_BADFREE">.
808 =item Process terminated by SIGTERM/SIGINT
810 This is a standard message issued by OS/2 applications. *nix
811 applications die in silence. It is considered a feature. One can
812 easily disable this by appropriate sighandlers.
814 However the test engine bleeds these message to screen in unexpected
815 moments. Two messages of this kind I<should> be present during
818 =item F<*/sh.exe>: ln: not found
820 =item C<ls>: /dev: No such file or directory
822 The last two should be self-explanatory. The test suite discovers that
823 the system it runs on is not I<that much> *nixish.
827 A lot of `bad free'... in databases, bug in DB confirmed on other
828 platforms. You may disable it by setting PERL_BADFREE environment variable
831 =head2 Installing the built perl
837 It would put the generated files into needed locations. Manually put
838 F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
839 C<PATH>, F<perl.dll> to a location on your C<LIBPATH>.
843 make cmdscripts INSTALLCMDDIR=d:/ir/on/path
845 to convert perl utilities to F<.cmd> files and put them on
846 C<PATH>. You need to put F<.EXE>-utilities on path manually. They are
847 installed in C<$prefix/bin>, here C<$prefix> is what you gave to
848 F<Configure>, see L<Making>.
850 =head2 C<a.out>-style build
852 Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
861 Manually put F<perl_.exe> to a location on your C<PATH>.
863 Since C<perl_> has the extensions prebuilt, it does not suffer from
864 the I<dynamic extensions + fork()> syndrom, thus the failing tests
867 Failed Test Status Wstat Total Fail Failed List of failed
868 ---------------------------------------------------------------
869 io/fs.t 26 11 42.31% 2-5, 7-11, 18, 25
870 op/stat.t 56 5 8.93% 3-4, 20, 35, 39
871 Failed 2/118 test scripts, 98.31% okay. 16/2445 subtests failed, 99.35% okay.
873 B<Note.> The build process for C<perl_> I<does not know> about all the
874 dependencies, so you should make sure that anything is up-to-date,
883 =head2 Some C</> became C<\> in pdksh.
885 You have a very old pdksh. See L<Prerequisites>.
887 =head2 C<'errno'> - unresolved external
889 You do not have MT-safe F<db.lib>. See L<Prerequisites>.
891 =head2 Problems with C<tr>
893 reported with very old version of C<tr>.
895 =head2 Some problem (forget which ;-)
897 You have an older version of F<perl.dll> on your C<LIBPATH>, which
898 broke the build of extensions.
900 =head2 Library ... not found
902 You did not run C<omflibs>. See L<Prerequisites>.
904 =head2 Segfault in make
906 You use an old version of C<GNU> make. See L<Prerequisites>.
908 =head1 Specific (mis)features of OS/2 port
910 =head2 C<setpriority>, C<getpriority>
912 Note that these functions are compatible with *nix, not with the older
913 ports of '94 - 95. The priorities are absolute, go from 32 to -95,
914 lower is quickier. 0 is the default priority.
918 Multi-argument form of C<system()> allows an additional numeric
919 argument. The meaning of this argument is described in
922 =head2 Additional modules:
924 L<OS2::Process>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. This
925 modules provide access to additional numeric argument for C<system>,
926 to DLLs having functions with REXX signature and to REXX runtime, to
927 OS/2 databases in the F<.INI> format, and to Extended Attributes.
929 Two additional extensions by Andread Kaiser, C<OS2::UPM>, and
930 C<OS2::FTP>, are included into my ftp directory, mirrored on CPAN.
932 =head2 Prebuilt methods:
936 =item C<File::Copy::syscopy>
938 used by C<File::Copy::copy>, see L<File::Copy/copy>.
940 =item C<DynaLoader::mod2fname>
942 used by C<DynaLoader> for DLL name mungling.
944 =item C<Cwd::current_drive()>
948 =item C<Cwd::sys_chdir(name)>
950 leaves drive as it is.
952 =item C<Cwd::change_drive(name)>
955 =item C<Cwd::sys_is_absolute(name)>
957 means has drive letter and is_rooted.
959 =item C<Cwd::sys_is_rooted(name)>
961 means has leading C<[/\\]> (maybe after a drive-letter:).
963 =item C<Cwd::sys_is_relative(name)>
965 means changes with current dir.
967 =item C<Cwd::sys_cwd(name)>
969 Interface to cwd from B<EMX>. Used by C<Cwd::cwd>.
971 =item C<Cwd::sys_abspath(name, dir)>
973 Really really odious function to implement. Returns absolute name of
974 file which would have C<name> if CWD were C<dir>. C<Dir> defaults to the
977 =item C<Cwd::extLibpath([type])
979 Get current value of extended library search path. If C<type> is
980 present and I<true>, works with END_LIBPATH, otherwise with
983 =item C<Cwd::extLibpath_set( path [, type ] )>
985 Set current value of extended library search path. If C<type> is
986 present and I<true>, works with END_LIBPATH, otherwise with
991 (Note that some of these may be moved to different libraries -
1001 Since <flock> is present in B<EMX>, but is not functional, the same is
1002 true for perl. Here is the list of things which may be "broken" on
1003 EMX (from EMX docs):
1005 - The functions recvmsg(), sendmsg(), and socketpair() are not
1007 - sock_init() is not required and not implemented.
1008 - flock() is not yet implemented (dummy function).
1010 Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
1014 waitpid() is not implemented for negative values of PID.
1016 Note that C<kill -9> does not work with the current version of EMX.
1020 Since F<sh.exe> is used for globbing (see L<perlfunc/glob>), the bugs
1021 of F<sh.exe> plague perl as well.
1023 In particular, uppercase letters do not work in C<[...]>-patterns with
1024 the current C<pdksh>.
1028 =head2 Modifications
1030 Perl modifies some standard C library calls in the following ways:
1036 C<my_popen> always uses F<sh.exe>, cf. L<"PERL_SH_DIR">.
1040 is created using C<TMP> or C<TEMP> environment variable, via
1045 If the current directory is not writable, it is created using modified
1046 C<tmpnam>, so there may be a race condition.
1050 a dummy implementation.
1054 C<os2_stat> special-cases F</dev/tty> and F</dev/con>.
1060 Because of ideosyncrasies of OS/2 one cannot have all the eggs in the
1061 same basket (though C<EMX> environment tries hard to overcome this
1062 limitations, so the situation may somehow improve). There are 4
1063 executables for Perl provided by the distribution:
1067 The main workhorse. This is a chimera executable: it is compiled as an
1068 C<a.out>-style executable, but is linked with C<omf>-style dynamic
1069 library F<perl.dll>, and with dynamic B<CRT> DLL. This executable is a
1072 It can load perl dynamic extensions, and it can fork(). Unfortunately,
1073 currently it cannot fork() with dynamic extensions loaded.
1075 B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.
1079 This is a statically linked C<a.out>-style executable. It can fork(),
1080 but cannot load dynamic Perl extensions. The supplied executable has a
1081 lot of extensions prebuilt, thus there are situations when it can
1082 perform tasks not possible using F<perl.exe>, like fork()ing when
1083 having some standard extension loaded. This executable is a C<VIO>
1086 B<Note.> A better behaviour could be obtained from C<perl.exe> if it
1087 were statically linked with standard I<Perl extensions>, but
1088 dynamically linked with the I<Perl DLL> and C<CRT> DLL. Then it would
1089 be able to fork() with standard extensions, I<and> would be able to
1090 dynamically load arbitrary extensions. Some changes to Makefiles and
1091 hint files should be necessary to achieve this.
1093 I<This is also the only executable with does not require OS/2.> The
1094 friends locked into C<M$> world would appreciate the fact that this
1095 executable runs under DOS, Win0.31, Win0.95 and WinNT with an
1096 appropriate extender. See L<"Other OSes">.
1098 =head2 F<perl__.exe>
1100 This is the same executable as <perl___.exe>, but it is a C<PM>
1103 B<Note.> Usually C<STDIN>, C<STDERR>, and C<STDOUT> of a C<PM>
1104 application are redirected to C<nul>. However, it is possible to see
1105 them if you start C<perl__.exe> from a PM program which emulates a
1106 console window, like I<Shell mode> of C<Emacs> or C<EPM>. Thus it I<is
1107 possible> to use Perl debugger (see L<perldebug>) to debug your PM
1110 This flavor is required if you load extensions which use C<PM>, like
1111 the forthcoming C<Perl/Tk>.
1113 =head2 F<perl___.exe>
1115 This is an C<omf>-style executable which is dynamically linked to
1116 F<perl.dll> and C<CRT> DLL. I know no advantages of this executable
1117 over C<perl.exe>, but it cannot fork() at all. Well, one advantage is
1118 that the build process is not so convoluted as with C<perl.exe>.
1120 It is a C<VIO> application.
1122 =head2 Why strange names?
1124 Since Perl processes the C<#!>-line (cf.
1125 L<perlrun/DESCRIPTION>, L<perlrun/Switches>,
1126 L<perldiag/"Not a perl script">,
1127 L<perldiag/"No Perl script found in input">), it should know when a
1128 program I<is a Perl>. There is some naming convention which allows
1129 Perl to distinguish correct lines from wrong ones. The above names are
1130 almost the only names allowed by this convension which do not contain
1131 digits (which have absolutely different semantics).
1133 =head2 Why dynamic linking?
1135 Well, having several executables dynamically linked to the same huge
1136 library has its advantages, but this would not substantiate the
1137 additional work to make it compile. The reason is stupid-but-quick
1138 "hard" dynamic linking used by OS/2.
1140 The address tables of DLLs are patches only once, when they are
1141 loaded. The addresses of entry points into DLLs are guarantied to be
1142 the same for all programs which use the same DLL, which reduces the
1143 amount of runtime patching - once DLL is loaded, its code is
1146 While this allows some performance advantages, this makes life
1147 terrible for developpers, since the above scheme makes it impossible
1148 for a DLL to be resolved to a symbol in the .EXE file, since this
1149 would need a DLL to have different relocations tables for the
1150 executables which use it.
1152 However, a Perl extension is forced to use some symbols from the perl
1153 executable, say to know how to find the arguments provided on the perl
1154 internal evaluation stack. The solution is that the main code of
1155 interpreter should be contained in a DLL, and the F<.EXE> file just loads
1156 this DLL into memory and supplies command-arguments.
1158 This I<greately> increases the load time for the application (as well as
1159 the number of problems during compilation). Since interpreter is in a DLL,
1160 the C<CRT> is basically forced to reside in a DLL as well (otherwise
1161 extensions would not be able to use C<CRT>).
1163 =head2 Why chimera build?
1165 Current C<EMX> environment does not allow DLLs compiled using Unixish
1166 C<a.out> format to export symbols for data. This forces C<omf>-style
1167 compile of F<perl.dll>.
1169 Current C<EMX> environment does not allow F<.EXE> files compiled in
1170 C<omf> format to fork(). fork() is needed for exactly three Perl
1175 =item explicit fork()
1183 opening pipes to itself.
1187 While these operations are not questions of life and death, a lot of
1188 useful scripts use them. This forces C<a.out>-style compile of
1194 Here we list environment variables with are either OS/2-specific, or
1195 are more important under OS/2 than under other OSes.
1197 =head2 C<PERLLIB_PREFIX>
1199 Specific for OS/2. Should have the form
1207 If the beginning of some prebuilt path matches F<path1>, it is
1208 substituted with F<path2>.
1210 Should be used if the perl library is moved from the default
1211 location in preference to C<PERL(5)LIB>, since this would not leave wrong
1214 =head2 C<PERL_BADLANG>
1216 If 1, perl ignores setlocale() failing. May be useful with some
1219 =head2 C<PERL_BADFREE>
1221 If 1, perl would not warn of in case of unwarranted free(). May be
1222 useful in conjunction with the module DB_File, since Berkeley DB
1223 memory handling code is buggy.
1225 =head2 C<PERL_SH_DIR>
1227 Specific for OS/2. Gives the directory part of the location for
1230 =head2 C<TMP> or C<TEMP>
1232 Specific for OS/2. Used as storage place for temporary files, most
1233 notably C<-e> scripts.
1237 Here we list major changes which could make you by surprise.
1241 C<setpriority> and C<getpriority> are not compatible with earlier
1242 ports by Andreas Kaiser. See C<"setpriority, getpriority">.
1244 =head2 DLL name mungling
1246 With the release 5.003_01 the dynamically loadable libraries
1247 should be rebuilt. In particular, DLLs are now created with the names
1248 which contain a checksum, thus allowing workaround for OS/2 scheme of
1253 As of release 5.003_01 perl is linked to multithreaded C<CRT>
1254 DLL. Perl itself is not multithread-safe, as is not perl
1255 malloc(). However, extensions may use multiple thread on their own
1258 Needed to compile C<Perl/Tk> for C<XFreeOS/2> out-of-the-box.
1260 =head2 Calls to external programs
1262 Due to a popular demand the perl external program calling has been
1263 changed wrt Andread Kaiser's port. I<If> perl needs to call an
1264 external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
1265 whatever is the override, see L<"PERL_SH_DIR">.
1267 Thus means that you need to get some copy of a F<sh.exe> as well (I
1268 use one from pdksh). The drive F: above is set up automatically during
1269 the build to a correct value on the builder machine, but is
1270 overridable at runtime,
1272 B<Reasons:> a consensus on C<perl5-porters> was that perl should use
1273 one non-overridable shell per platform. The obvious choices for OS/2
1274 are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible
1275 with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. Thus assures almost
1276 100% compatibility with the scripts coming from *nix.
1278 B<Disadvantages:> currently F<sh.exe> of C<pdksh> calls external programs
1279 via fork()/exec(), and there is I<no> functioning exec() on
1280 OS/2. exec() is emulated by EMX by asyncroneous call while the caller
1281 waits for child completion (to pretend that the pid did not change). This
1282 means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(),
1283 which may lead to some resources taken from the system (even if we do
1284 not count extra work needed for fork()ing).
1286 One can always start F<cmd.exe> explicitely via
1288 system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
1290 If you need to use F<cmd.exe>, and do not want to hand-edit thousends of your
1291 scripts, the long-term solution proposed on p5-p is to have a directive
1295 which will override system(), exec(), C<``>, and
1296 C<open(,'...|')>. With current perl you may override only system(),
1297 readpipe() - the explicit version of C<``>, and maybe exec(). The code
1298 will substitute the one-argument call to system() by
1299 C<CORE::system('cmd.exe', '/c', shift)>.
1301 If you have some working code for C<OS2::Cmd>, please send it to me,
1302 I will include it into distribution. I have no need for such a module, so
1309 I include 3 extensions by Andread Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP,
1310 into my ftp directory, mirrored on CPAN. I made
1311 some minor changes needed to compile them by standard tools. I cannot
1312 test UPM and FTP, so I will appreciate your feedback. Other extensions
1313 there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI
1314 files - and maybe some other extensions at the time you read it.
1316 Note that OS2 perl defines 2 pseudo-extension functions
1317 OS2::Copy::copy and DynaLoader::mod2fname.
1319 The -R switch of older perl is deprecated. If you need to call a REXX code
1320 which needs access to variables, include the call into a REXX compartment
1322 REXX_call {...block...};
1324 Two new functions are supported by REXX code,
1326 REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference;
1328 If you have some other extensions you want to share, send the code to
1329 me. At least two are available: tied access to EA's, and tied access
1330 to system databases.
1334 Ilya Zakharevich, ilya@math.ohio-state.edu