This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Avoid redefinedness warning for now.
[perl5.git] / README.os2
CommitLineData
a56dbb1c
PP
1If you read this file _as_is_, just ignore the funny characters you
2see. It is written in the POD format (see perlpod manpage) which is
3specially designed to be readable as is.
4
5=head1 NAME
6
72ea3524 7perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
a56dbb1c
PP
8
9=head1 SYNOPSIS
10
11One can read this document in the following formats:
12
13 man perlos2
14 view perl perlos2
15 explorer perlos2.html
16 info perlos2
17
18to list some (not all may be available simultaneously), or it may
19be read I<as is>: either as F<README.os2>, or F<pod/perlos2.pod>.
20
72ea3524
IZ
21To read the F<.INF> version of documentation (B<very> recommended)
22outside of OS/2, one needs an IBM's reader (may be available on IBM
df3ef7a9
IZ
23ftp sites (?) (URL anyone?)) or shipped with PC DOS 7.0 and IBM's
24Visual Age C++ 3.5.
25
26A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package
27
28 ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip
29
aa689395 30in F<?:\JUST_ADD\view.exe>. This gives one an access to EMX's
df3ef7a9 31F<.INF> docs as well (text form is available in F</emx/doc> in
aa689395 32EMX's distribution).
72ea3524 33
d7678ab8
CS
34Note that if you have F<lynx.exe> installed, you can follow WWW links
35from this document in F<.INF> format. If you have EMX docs installed
36correctly, you can follow library links (you need to have C<view emxbook>
37working by setting C<EMXBOOK> environment variable as it is described
38in EMX docs).
39
a56dbb1c
PP
40=cut
41
42Contents
43
df3ef7a9 44 perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
a56dbb1c 45
df3ef7a9
IZ
46 NAME
47 SYNOPSIS
48 DESCRIPTION
a56dbb1c
PP
49 - Target
50 - Other OSes
51 - Prerequisites
aa689395
PP
52 - Starting Perl programs under OS/2 (and DOS and...)
53 - Starting OS/2 (and DOS) programs under Perl
df3ef7a9 54 Frequently asked questions
72ea3524 55 - I cannot run external programs
df3ef7a9
IZ
56 - I cannot embed perl into my program, or use perl.dll from my program.
57 - `` and pipe-open do not work under DOS.
aa689395 58 - Cannot start find.exe "pattern" file
df3ef7a9 59 INSTALLATION
a56dbb1c
PP
60 - Automatic binary installation
61 - Manual binary installation
62 - Warning
df3ef7a9 63 Accessing documentation
a56dbb1c
PP
64 - OS/2 .INF file
65 - Plain text
66 - Manpages
67 - HTML
68 - GNU info files
69 - .PDF files
70 - LaTeX docs
df3ef7a9 71 BUILD
a56dbb1c
PP
72 - Prerequisites
73 - Getting perl source
74 - Application of the patches
75 - Hand-editing
76 - Making
77 - Testing
78 - Installing the built perl
79 - a.out-style build
df3ef7a9 80 Build FAQ
a56dbb1c
PP
81 - Some / became \ in pdksh.
82 - 'errno' - unresolved external
83 - Problems with tr
84 - Some problem (forget which ;-)
85 - Library ... not found
df3ef7a9 86 - Segfault in make
aa689395 87 Specific (mis)features of EMX port
a56dbb1c
PP
88 - setpriority, getpriority
89 - system()
aa689395 90 - extproc on the first line
a56dbb1c
PP
91 - Additional modules:
92 - Prebuilt methods:
93 - Misfeatures
df3ef7a9
IZ
94 - Modifications
95 Perl flavors
a56dbb1c
PP
96 - perl.exe
97 - perl_.exe
98 - perl__.exe
99 - perl___.exe
100 - Why strange names?
101 - Why dynamic linking?
102 - Why chimera build?
df3ef7a9 103 ENVIRONMENT
a56dbb1c
PP
104 - PERLLIB_PREFIX
105 - PERL_BADLANG
106 - PERL_BADFREE
107 - PERL_SH_DIR
108 - TMP or TEMP
df3ef7a9 109 Evolution
a56dbb1c 110 - Priorities
72ea3524 111 - DLL name mangling
a56dbb1c
PP
112 - Threading
113 - Calls to external programs
df3ef7a9 114 - Memory allocation
ec40c0cd 115 - Threads
df3ef7a9
IZ
116 AUTHOR
117 SEE ALSO
abe67105 118
a56dbb1c
PP
119=head1 DESCRIPTION
120
121=head2 Target
122
123The target is to make OS/2 the best supported platform for
72ea3524 124using/building/developing Perl and I<Perl applications>, as well as
aa689395
PP
125make Perl the best language to use under OS/2. The secondary target is
126to try to make this work under DOS and Win* as well (but not B<too> hard).
a56dbb1c
PP
127
128The current state is quite close to this target. Known limitations:
129
130=over 5
131
132=item *
133
3998488b
JH
134Some *nix programs use fork() a lot; with the mostly useful flavors of perl
135for OS/2 (there are several built simultaneously) this is supported;
136some flavors do not. Using fork() after I<use>ing dynamically loading
137extensions would not work with very old versions of EMX.
a56dbb1c
PP
138
139=item *
140
141You need a separate perl executable F<perl__.exe> (see L<perl__.exe>)
3998488b
JH
142if you want to use PM code in your application (as Perl/Tk or OpenGL
143Perl modules do) without having a text-mode window present.
144
145While using the standard F<perl.exe> from a text-mode window is possible
146too, I have seen cases when this causes degradation of the system stability.
147Using F<perl__.exe> avoids such a degradation.
a56dbb1c
PP
148
149=item *
150
aa689395 151There is no simple way to access WPS objects. The only way I know
a56dbb1c 152is via C<OS2::REXX> extension (see L<OS2::REXX>), and we do not have access to
aa689395 153convenience methods of Object-REXX. (Is it possible at all? I know
3998488b
JH
154of no Object-REXX API.) The C<SOM> extension (currently in alpha-text)
155may eventually remove this shortcoming.
a56dbb1c
PP
156
157=back
158
159Please keep this list up-to-date by informing me about other items.
160
161=head2 Other OSes
162
aa689395 163Since OS/2 port of perl uses a remarkable EMX environment, it can
3998488b 164run (and build extensions, and - possibly - be built itself) under any
a56dbb1c 165environment which can run EMX. The current list is DOS,
72ea3524 166DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
a56dbb1c
PP
167only one works, see L<"perl_.exe">.
168
169Note that not all features of Perl are available under these
170environments. This depends on the features the I<extender> - most
aa689395 171probably RSX - decided to implement.
a56dbb1c
PP
172
173Cf. L<Prerequisites>.
174
175=head2 Prerequisites
176
177=over 6
178
aa689395 179=item EMX
a56dbb1c 180
aa689395 181EMX runtime is required (may be substituted by RSX). Note that
55497cff 182it is possible to make F<perl_.exe> to run under DOS without any
72ea3524 183external support by binding F<emx.exe>/F<rsx.exe> to it, see L<emxbind>. Note
aa689395 184that under DOS for best results one should use RSX runtime, which
55497cff 185has much more functions working (like C<fork>, C<popen> and so on). In
aa689395
PP
186fact RSX is required if there is no VCPI present. Note the
187RSX requires DPMI.
a56dbb1c 188
884335e8 189Only the latest runtime is supported, currently C<0.9d fix 03>. Perl may run
aa689395 190under earlier versions of EMX, but this is not tested.
a56dbb1c 191
aa689395 192One can get different parts of EMX from, say
a56dbb1c 193
884335e8
YST
194 http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/
195 http://powerusersbbs.com/pub/os2/dev/ [EMX+GCC Development]
196 http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/
a56dbb1c
PP
197
198The runtime component should have the name F<emxrt.zip>.
199
72ea3524
IZ
200B<NOTE>. It is enough to have F<emx.exe>/F<rsx.exe> on your path. One
201does not need to specify them explicitly (though this
202
203 emx perl_.exe -de 0
204
205will work as well.)
206
aa689395 207=item RSX
a56dbb1c 208
aa689395 209To run Perl on DPMI platforms one needs RSX runtime. This is
72ea3524 210needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see
aa689395
PP
211L<"Other OSes">). RSX would not work with VCPI
212only, as EMX would, it requires DMPI.
55497cff 213
aa689395 214Having RSX and the latest F<sh.exe> one gets a fully functional
55497cff
PP
215B<*nix>-ish environment under DOS, say, C<fork>, C<``> and
216pipe-C<open> work. In fact, MakeMaker works (for static build), so one
217can have Perl development environment under DOS.
a56dbb1c 218
aa689395 219One can get RSX from, say
a56dbb1c 220
d7678ab8 221 ftp://ftp.cdrom.com/pub/os2/emx09c/contrib
a56dbb1c 222 ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
d7678ab8 223 ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/contrib
a56dbb1c
PP
224
225Contact the author on C<rainer@mathematik.uni-bielefeld.de>.
226
3998488b
JH
227The latest F<sh.exe> with DOS hooks is available in
228
229 ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/
55497cff 230
3998488b 231as F<sh_dos.zip> or under similar names starting with C<sh>, C<pdksh> etc.
55497cff 232
aa689395 233=item HPFS
a56dbb1c
PP
234
235Perl does not care about file systems, but to install the whole perl
236library intact one needs a file system which supports long file names.
237
238Note that if you do not plan to build the perl itself, it may be
aa689395
PP
239possible to fool EMX to truncate file names. This is not supported,
240read EMX docs to see how to do it.
241
242=item pdksh
243
244To start external programs with complicated command lines (like with
245pipes in between, and/or quoting of arguments), Perl uses an external
3998488b 246shell. With EMX port such shell should be named F<sh.exe>, and located
aa689395
PP
247either in the wired-in-during-compile locations (usually F<F:/bin>),
248or in configurable location (see L<"PERL_SH_DIR">).
249
3998488b
JH
250For best results use EMX pdksh. The standard binary (5.2.14 or later) runs
251under DOS (with L<RSX>) as well, see
aa689395 252
3998488b 253 ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/
a56dbb1c
PP
254
255=back
256
aa689395 257=head2 Starting Perl programs under OS/2 (and DOS and...)
a56dbb1c
PP
258
259Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the
260same way as on any other platform, by
261
262 perl foo.pl arg1 arg2 arg3
263
264If you want to specify perl options C<-my_opts> to the perl itself (as
d1be9408 265opposed to your program), use
a56dbb1c
PP
266
267 perl -my_opts foo.pl arg1 arg2 arg3
268
aa689395 269Alternately, if you use OS/2-ish shell, like CMD or 4os2, put
a56dbb1c
PP
270the following at the start of your perl script:
271
aa689395 272 extproc perl -S -my_opts
a56dbb1c
PP
273
274rename your program to F<foo.cmd>, and start it by typing
275
276 foo arg1 arg2 arg3
277
a56dbb1c
PP
278Note that because of stupid OS/2 limitations the full path of the perl
279script is not available when you use C<extproc>, thus you are forced to
3998488b 280use C<-S> perl switch, and your script should be on the C<PATH>. As a plus
a56dbb1c
PP
281side, if you know a full path to your script, you may still start it
282with
283
aa689395 284 perl ../../blah/foo.cmd arg1 arg2 arg3
a56dbb1c 285
aa689395
PP
286(note that the argument C<-my_opts> is taken care of by the C<extproc> line
287in your script, see L<C<extproc> on the first line>).
a56dbb1c
PP
288
289To understand what the above I<magic> does, read perl docs about C<-S>
aa689395 290switch - see L<perlrun>, and cmdref about C<extproc>:
a56dbb1c
PP
291
292 view perl perlrun
293 man perlrun
294 view cmdref extproc
295 help extproc
296
297or whatever method you prefer.
298
72ea3524 299There are also endless possibilities to use I<executable extensions> of
aa689395 3004os2, I<associations> of WPS and so on... However, if you use
a56dbb1c 301*nixish shell (like F<sh.exe> supplied in the binary distribution),
72ea3524 302you need to follow the syntax specified in L<perlrun/"Switches">.
a56dbb1c 303
d8c2d278
IZ
304Note that B<-S> switch enables a search with additional extensions
305F<.cmd>, F<.btm>, F<.bat>, F<.pl> as well.
306
aa689395 307=head2 Starting OS/2 (and DOS) programs under Perl
a56dbb1c
PP
308
309This is what system() (see L<perlfunc/system>), C<``> (see
310L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>)
311are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you
312do).
313
314Note however that to use some of these operators you need to have a
aa689395 315sh-syntax shell installed (see L<"Pdksh">,
a56dbb1c
PP
316L<"Frequently asked questions">), and perl should be able to find it
317(see L<"PERL_SH_DIR">).
318
2c2e0e8c
IZ
319The cases when the shell is used are:
320
321=over
322
323=item 1
324
325One-argument system() (see L<perlfunc/system>), exec() (see L<perlfunc/exec>)
326with redirection or shell meta-characters;
327
328=item 2
329
330Pipe-open (see L<perlfunc/open>) with the command which contains redirection
331or shell meta-characters;
332
333=item 3
334
335Backticks C<``> (see L<perlop/"I/O Operators">) with the command which contains
336redirection or shell meta-characters;
337
338=item 4
339
340If the executable called by system()/exec()/pipe-open()/C<``> is a script
341with the "magic" C<#!> line or C<extproc> line which specifies shell;
342
343=item 5
344
345If the executable called by system()/exec()/pipe-open()/C<``> is a script
346without "magic" line, and C<$ENV{EXECSHELL}> is set to shell;
347
348=item 6
349
350If the executable called by system()/exec()/pipe-open()/C<``> is not
351found;
352
353=item 7
354
355For globbing (see L<perlfunc/glob>, L<perlop/"I/O Operators">).
356
357=back
358
359For the sake of speed for a common case, in the above algorithms
360backslashes in the command name are not considered as shell metacharacters.
361
362Perl starts scripts which begin with cookies
363C<extproc> or C<#!> directly, without an intervention of shell. Perl uses the
364same algorithm to find the executable as F<pdksh>: if the path
365on C<#!> line does not work, and contains C</>, then the executable
366is searched in F<.> and on C<PATH>. To find arguments for these scripts
367Perl uses a different algorithm than F<pdksh>: up to 3 arguments are
368recognized, and trailing whitespace is stripped.
369
370If a script
371does not contain such a cooky, then to avoid calling F<sh.exe>, Perl uses
372the same algorithm as F<pdksh>: if C<$ENV{EXECSHELL}> is set, the
373script is given as the first argument to this command, if not set, then
374C<$ENV{COMSPEC} /c> is used (or a hardwired guess if C<$ENV{COMSPEC}> is
375not set).
491527d0
GS
376
377If starting scripts directly, Perl will use exactly the same algorithm as for
378the search of script given by B<-S> command-line option: it will look in
379the current directory, then on components of C<$ENV{PATH}> using the
380following order of appended extensions: no extension, F<.cmd>, F<.btm>,
381F<.bat>, F<.pl>.
382
383Note that Perl will start to look for scripts only if OS/2 cannot start the
384specified application, thus C<system 'blah'> will not look for a script if
385there is an executable file F<blah.exe> I<anywhere> on C<PATH>.
386
387Note also that executable files on OS/2 can have an arbitrary extension,
388but F<.exe> will be automatically appended if no dot is present in the name.
d1be9408 389The workaround is as simple as that: since F<blah.> and F<blah> denote the
491527d0 390same file, to start an executable residing in file F<n:/bin/blah> (no
3998488b 391extension) give an argument C<n:/bin/blah.> (dot appended) to system().
491527d0 392
3998488b
JH
393Perl will correctly start PM programs from VIO (=text-mode) Perl process;
394the opposite is not true: when you start a non-PM program from a PM
395Perl process, it would not run it in a separate session. If a separate
396session is desired, either ensure
397that shell will be used, as in C<system 'cmd /c myprog'>, or start it using
491527d0 398optional arguments to system() documented in C<OS2::Process> module. This
3998488b 399is considered to be a feature.
a56dbb1c
PP
400
401=head1 Frequently asked questions
402
3998488b
JH
403=head2 "It does not work"
404
405Perl binary distributions come with a F<testperl.cmd> script which tries
406to detect common problems with misconfigured installations. There is a
407pretty large chance it will discover which step of the installation you
408managed to goof. C<;-)>
409
72ea3524 410=head2 I cannot run external programs
a56dbb1c 411
55497cff
PP
412=over 4
413
13a2d996 414=item *
55497cff 415
a56dbb1c 416Did you run your programs with C<-w> switch? See
aa689395 417L<Starting OS/2 (and DOS) programs under Perl>.
a56dbb1c 418
13a2d996 419=item *
55497cff
PP
420
421Do you try to run I<internal> shell commands, like C<`copy a b`>
422(internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You
72ea3524 423need to specify your shell explicitly, like C<`cmd /c copy a b`>,
55497cff
PP
424since Perl cannot deduce which commands are internal to your shell.
425
426=back
427
a56dbb1c
PP
428=head2 I cannot embed perl into my program, or use F<perl.dll> from my
429program.
430
431=over 4
432
aa689395 433=item Is your program EMX-compiled with C<-Zmt -Zcrtdll>?
a56dbb1c
PP
434
435If not, you need to build a stand-alone DLL for perl. Contact me, I
436did it once. Sockets would not work, as a lot of other stuff.
437
aa689395 438=item Did you use L<ExtUtils::Embed>?
a56dbb1c
PP
439
440I had reports it does not work. Somebody would need to fix it.
441
442=back
443
55497cff
PP
444=head2 C<``> and pipe-C<open> do not work under DOS.
445
72ea3524 446This may a variant of just L<"I cannot run external programs">, or a
aa689395 447deeper problem. Basically: you I<need> RSX (see L<"Prerequisites">)
72ea3524 448for these commands to work, and you may need a port of F<sh.exe> which
55497cff 449understands command arguments. One of such ports is listed in
aa689395
PP
450L<"Prerequisites"> under RSX. Do not forget to set variable
451C<L<"PERL_SH_DIR">> as well.
452
453DPMI is required for RSX.
454
455=head2 Cannot start C<find.exe "pattern" file>
55497cff 456
aa689395
PP
457Use one of
458
459 system 'cmd', '/c', 'find "pattern" file';
460 `cmd /c 'find "pattern" file'`
461
462This would start F<find.exe> via F<cmd.exe> via C<sh.exe> via
463C<perl.exe>, but this is a price to pay if you want to use
464non-conforming program. In fact F<find.exe> cannot be started at all
3998488b 465using C library API only. Otherwise the following command-lines would be
aa689395
PP
466equivalent:
467
468 find "pattern" file
469 find pattern file
55497cff 470
a56dbb1c
PP
471=head1 INSTALLATION
472
473=head2 Automatic binary installation
474
3998488b 475The most convenient way of installing a binary distribution of perl is via perl installer
a56dbb1c
PP
476F<install.exe>. Just follow the instructions, and 99% of the
477installation blues would go away.
478
479Note however, that you need to have F<unzip.exe> on your path, and
aa689395
PP
480EMX environment I<running>. The latter means that if you just
481installed EMX, and made all the needed changes to F<Config.sys>,
482you may need to reboot in between. Check EMX runtime by running
a56dbb1c
PP
483
484 emxrev
485
486A folder is created on your desktop which contains some useful
487objects.
488
489B<Things not taken care of by automatic binary installation:>
490
491=over 15
492
493=item C<PERL_BADLANG>
494
495may be needed if you change your codepage I<after> perl installation,
aa689395 496and the new value is not supported by EMX. See L<"PERL_BADLANG">.
a56dbb1c
PP
497
498=item C<PERL_BADFREE>
499
500see L<"PERL_BADFREE">.
501
502=item F<Config.pm>
503
504This file resides somewhere deep in the location you installed your
505perl library, find it out by
506
507 perl -MConfig -le "print $INC{'Config.pm'}"
508
509While most important values in this file I<are> updated by the binary
510installer, some of them may need to be hand-edited. I know no such
511data, please keep me informed if you find one.
512
513=back
514
aa689395
PP
515B<NOTE>. Because of a typo the binary installer of 5.00305
516would install a variable C<PERL_SHPATH> into F<Config.sys>. Please
517remove this variable and put C<L<PERL_SH_DIR>> instead.
518
a56dbb1c
PP
519=head2 Manual binary installation
520
72ea3524 521As of version 5.00305, OS/2 perl binary distribution comes split
a56dbb1c 522into 11 components. Unfortunately, to enable configurable binary
aa689395 523installation, the file paths in the zip files are not absolute, but
a56dbb1c
PP
524relative to some directory.
525
526Note that the extraction with the stored paths is still necessary
aa689395 527(default with unzip, specify C<-d> to pkunzip). However, you
a56dbb1c
PP
528need to know where to extract the files. You need also to manually
529change entries in F<Config.sys> to reflect where did you put the
72ea3524 530files. Note that if you have some primitive unzipper (like
aa689395 531pkunzip), you may get a lot of warnings/errors during
72ea3524 532unzipping. Upgrade to C<(w)unzip>.
a56dbb1c
PP
533
534Below is the sample of what to do to reproduce the configuration on my
535machine:
536
537=over 3
538
539=item Perl VIO and PM executables (dynamically linked)
540
541 unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
542 unzip perl_exc.zip *.dll -d f:/emx.add/dll
543
aa689395
PP
544(have the directories with C<*.exe> on PATH, and C<*.dll> on
545LIBPATH);
a56dbb1c
PP
546
547=item Perl_ VIO executable (statically linked)
548
549 unzip perl_aou.zip -d f:/emx.add/bin
550
aa689395 551(have the directory on PATH);
a56dbb1c
PP
552
553=item Executables for Perl utilities
554
555 unzip perl_utl.zip -d f:/emx.add/bin
556
aa689395 557(have the directory on PATH);
a56dbb1c
PP
558
559=item Main Perl library
560
561 unzip perl_mlb.zip -d f:/perllib/lib
562
3998488b
JH
563If this directory is exactly the same as the prefix which was compiled
564into F<perl.exe>, you do not need to change
565anything. However, for perl to find the library if you use a different
566path, you need to
a56dbb1c
PP
567C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
568
569=item Additional Perl modules
570
3998488b 571 unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.8.3/
a56dbb1c 572
3998488b
JH
573Same remark as above applies. Additionally, if this directory is not
574one of directories on @INC (and @INC is influenced by C<PERLLIB_PREFIX>), you
575need to put this
a56dbb1c
PP
576directory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB>
577variable. Do not use C<PERL5LIB> unless you have it set already. See
3998488b 578L<perl/"ENVIRONMENT">.
a56dbb1c
PP
579
580=item Tools to compile Perl modules
581
582 unzip perl_blb.zip -d f:/perllib/lib
583
3998488b 584Same remark as for F<perl_ste.zip>.
a56dbb1c
PP
585
586=item Manpages for Perl and utilities
587
588 unzip perl_man.zip -d f:/perllib/man
589
590This directory should better be on C<MANPATH>. You need to have a
aa689395 591working man to access these files.
a56dbb1c
PP
592
593=item Manpages for Perl modules
594
595 unzip perl_mam.zip -d f:/perllib/man
596
597This directory should better be on C<MANPATH>. You need to have a
aa689395 598working man to access these files.
a56dbb1c
PP
599
600=item Source for Perl documentation
601
602 unzip perl_pod.zip -d f:/perllib/lib
603
3998488b 604This is used by the C<perldoc> program (see L<perldoc>), and may be used to
aa689395 605generate HTML documentation usable by WWW browsers, and
a56dbb1c
PP
606documentation in zillions of other formats: C<info>, C<LaTeX>,
607C<Acrobat>, C<FrameMaker> and so on.
608
aa689395 609=item Perl manual in F<.INF> format
a56dbb1c
PP
610
611 unzip perl_inf.zip -d d:/os2/book
612
613This directory should better be on C<BOOKSHELF>.
614
615=item Pdksh
616
617 unzip perl_sh.zip -d f:/bin
618
72ea3524 619This is used by perl to run external commands which explicitly
a56dbb1c
PP
620require shell, like the commands using I<redirection> and I<shell
621metacharacters>. It is also used instead of explicit F</bin/sh>.
622
623Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
624the above location.
625
aa689395 626B<Note.> It may be possible to use some other sh-compatible shell
3998488b 627(file globbing - if done via shell - may break).
a56dbb1c
PP
628
629=back
630
631After you installed the components you needed and updated the
632F<Config.sys> correspondingly, you need to hand-edit
633F<Config.pm>. This file resides somewhere deep in the location you
634installed your perl library, find it out by
635
636 perl -MConfig -le "print $INC{'Config.pm'}"
637
638You need to correct all the entries which look like file paths (they
639currently start with C<f:/>).
640
641=head2 B<Warning>
642
643The automatic and manual perl installation leave precompiled paths
644inside perl executables. While these paths are overwriteable (see
645L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), one may get better results by
646binary editing of paths inside the executables/DLLs.
647
648=head1 Accessing documentation
649
650Depending on how you built/installed perl you may have (otherwise
651identical) Perl documentation in the following formats:
652
653=head2 OS/2 F<.INF> file
654
aa689395 655Most probably the most convenient form. Under OS/2 view it as
a56dbb1c
PP
656
657 view perl
658 view perl perlfunc
659 view perl less
660 view perl ExtUtils::MakeMaker
661
662(currently the last two may hit a wrong location, but this may improve
aa689395 663soon). Under Win* see L<"SYNOPSIS">.
a56dbb1c
PP
664
665If you want to build the docs yourself, and have I<OS/2 toolkit>, run
666
667 pod2ipf > perl.ipf
668
669in F</perllib/lib/pod> directory, then
670
671 ipfc /inf perl.ipf
672
673(Expect a lot of errors during the both steps.) Now move it on your
674BOOKSHELF path.
675
676=head2 Plain text
677
678If you have perl documentation in the source form, perl utilities
aa689395 679installed, and GNU groff installed, you may use
a56dbb1c
PP
680
681 perldoc perlfunc
682 perldoc less
683 perldoc ExtUtils::MakeMaker
684
72ea3524 685to access the perl documentation in the text form (note that you may get
a56dbb1c
PP
686better results using perl manpages).
687
688Alternately, try running pod2text on F<.pod> files.
689
690=head2 Manpages
691
aa689395 692If you have man installed on your system, and you installed perl
a56dbb1c 693manpages, use something like this:
5243f9ae 694
5243f9ae
PP
695 man perlfunc
696 man 3 less
697 man ExtUtils.MakeMaker
5243f9ae 698
a56dbb1c
PP
699to access documentation for different components of Perl. Start with
700
701 man perl
702
703Note that dot (F<.>) is used as a package separator for documentation
704for packages, and as usual, sometimes you need to give the section - C<3>
705above - to avoid shadowing by the I<less(1) manpage>.
706
707Make sure that the directory B<above> the directory with manpages is
708on our C<MANPATH>, like this
709
710 set MANPATH=c:/man;f:/perllib/man
711
3998488b
JH
712for Perl manpages in C<f:/perllib/man/man1/> etc.
713
aa689395 714=head2 HTML
a56dbb1c
PP
715
716If you have some WWW browser available, installed the Perl
717documentation in the source form, and Perl utilities, you can build
aa689395 718HTML docs. Cd to directory with F<.pod> files, and do like this
a56dbb1c
PP
719
720 cd f:/perllib/lib/pod
5243f9ae 721 pod2html
5243f9ae 722
a56dbb1c
PP
723After this you can direct your browser the file F<perl.html> in this
724directory, and go ahead with reading docs, like this:
5243f9ae 725
a56dbb1c 726 explore file:///f:/perllib/lib/pod/perl.html
5243f9ae 727
aa689395 728Alternatively you may be able to get these docs prebuilt from CPAN.
5243f9ae 729
aa689395 730=head2 GNU C<info> files
bb14ff96 731
aa689395 732Users of Emacs would appreciate it very much, especially with
a56dbb1c
PP
733C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
734or, alternately, prebuilt info pages.
615d1a09 735
a56dbb1c
PP
736=head2 F<.PDF> files
737
738for C<Acrobat> are available on CPAN (for slightly old version of
739perl).
740
741=head2 C<LaTeX> docs
742
743can be constructed using C<pod2latex>.
744
745=head1 BUILD
746
747Here we discuss how to build Perl under OS/2. There is an alternative
b3b6085d 748(but maybe older) view on http://www.shadow.net/~troc/os2perl.html
a56dbb1c 749
3998488b
JH
750=head2 The short story
751
752Assume that you are a seasoned porter, so are sure that all the necessary
753tools are already present on your system, and you know how to get the Perl
754source distribution. Untar it, change to the extract directory, and
755
756 gnupatch -p0 < os2\diff.configure
757 sh Configure -des -D prefix=f:/perllib
758 make
759 make test
760 make install
761 make aout_test
762 make aout_install
763
764This puts the executables in f:/perllib/bin. Manually move them to the
765C<PATH>, manually move the built F<perl*.dll> to C<LIBPATH> (here F<*> is
766a not-very-meaningful hex checksum), and run
767
768 make installcmd INSTALLCMDDIR=d:/ir/on/path
769
770What follows is a detailed guide through these steps.
771
a56dbb1c
PP
772=head2 Prerequisites
773
aa689395
PP
774You need to have the latest EMX development environment, the full
775GNU tool suite (gawk renamed to awk, and GNU F<find.exe>
a56dbb1c
PP
776earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to
777check use
778
779 find --version
780 sort --version
781
782). You need the latest version of F<pdksh> installed as F<sh.exe>.
783
2c2e0e8c
IZ
784Check that you have B<BSD> libraries and headers installed, and -
785optionally - Berkeley DB headers and libraries, and crypt.
786
a56dbb1c
PP
787Possible locations to get this from are
788
d7678ab8 789 ftp://hobbes.nmsu.edu/os2/unix/
a56dbb1c
PP
790 ftp://ftp.cdrom.com/pub/os2/unix/
791 ftp://ftp.cdrom.com/pub/os2/dev32/
d7678ab8 792 ftp://ftp.cdrom.com/pub/os2/emx09c/
a56dbb1c 793
eb447b86 794It is reported that the following archives contain enough utils to
3998488b
JH
795build perl: F<gnufutil.zip>, F<gnusutil.zip>, F<gnututil.zip>, F<gnused.zip>,
796F<gnupatch.zip>, F<gnuawk.zip>, F<gnumake.zip>, F<bsddev.zip> and
797F<ksh527rt.zip> (or a later version). Note that all these utilities are
798known to be available from LEO:
eb447b86
IZ
799
800 ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu
a56dbb1c 801
3998488b
JH
802If you have I<exactly the same version of Perl> installed already,
803make sure that no copies or perl are currently running. Later steps
804of the build may fail since an older version of F<perl.dll> loaded into
a56dbb1c
PP
805memory may be found.
806
807Also make sure that you have F</tmp> directory on the current drive,
808and F<.> directory in your C<LIBPATH>. One may try to correct the
809latter condition by
810
811 set BEGINLIBPATH .
812
813if you use something like F<CMD.EXE> or latest versions of F<4os2.exe>.
814
aa689395 815Make sure your gcc is good for C<-Zomf> linking: run C<omflibs>
a56dbb1c
PP
816script in F</emx/lib> directory.
817
aa689395 818Check that you have link386 installed. It comes standard with OS/2,
a56dbb1c
PP
819but may be not installed due to customization. If typing
820
821 link386
822
823shows you do not have it, do I<Selective install>, and choose C<Link
72ea3524 824object modules> in I<Optional system utilities/More>. If you get into
3998488b 825link386 prompts, press C<Ctrl-C> to exit.
a56dbb1c
PP
826
827=head2 Getting perl source
828
72ea3524 829You need to fetch the latest perl source (including developers
a56dbb1c
PP
830releases). With some probability it is located in
831
468f45d5
MJD
832 http://www.cpan.org/src/5.0
833 http://www.cpan.org/src/5.0/unsupported
a56dbb1c
PP
834
835If not, you may need to dig in the indices to find it in the directory
836of the current maintainer.
837
72ea3524 838Quick cycle of developers release may break the OS/2 build time to
a56dbb1c
PP
839time, looking into
840
468f45d5 841 http://www.cpan.org/ports/os2/ilyaz/
a56dbb1c
PP
842
843may indicate the latest release which was publicly released by the
844maintainer. Note that the release may include some additional patches
845to apply to the current source of perl.
846
847Extract it like this
848
849 tar vzxf perl5.00409.tar.gz
850
851You may see a message about errors while extracting F<Configure>. This is
852because there is a conflict with a similarly-named file F<configure>.
853
a56dbb1c
PP
854Change to the directory of extraction.
855
856=head2 Application of the patches
857
10fb174d 858You need to apply the patches in F<./os2/diff.*> like this:
a56dbb1c 859
df3ef7a9 860 gnupatch -p0 < os2\diff.configure
a56dbb1c
PP
861
862You may also need to apply the patches supplied with the binary
863distribution of perl.
864
aa689395 865Note also that the F<db.lib> and F<db.a> from the EMX distribution
3998488b
JH
866are not suitable for multi-threaded compile (even single-threaded
867flavor of Perl uses multi-threaded C RTL, for
aa689395 868compatibility with XFree86-OS/2). Get a corrected one from
a56dbb1c
PP
869
870 ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip
871
872=head2 Hand-editing
873
874You may look into the file F<./hints/os2.sh> and correct anything
875wrong you find there. I do not expect it is needed anywhere.
615d1a09 876
a56dbb1c 877=head2 Making
615d1a09 878
a56dbb1c 879 sh Configure -des -D prefix=f:/perllib
615d1a09 880
aa689395 881C<prefix> means: where to install the resulting perl library. Giving
a56dbb1c
PP
882correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
883see L<"PERLLIB_PREFIX">.
5243f9ae 884
a56dbb1c 885I<Ignore the message about missing C<ln>, and about C<-c> option to
3998488b
JH
886tr>. The latter is most probably already fixed, if you see it and can trace
887where the latter spurious warning comes from, please inform me.
615d1a09 888
a56dbb1c 889Now
5243f9ae 890
a56dbb1c 891 make
5243f9ae 892
a56dbb1c 893At some moment the built may die, reporting a I<version mismatch> or
3998488b
JH
894I<unable to run F<perl>>. This means that you do not have F<.> in
895your LIBPATH, so F<perl.exe> cannot find the needed F<perl67B2.dll> (treat
896these hex digits as line noise). After this is fixed the build
897should finish without a lot of fuss.
615d1a09 898
a56dbb1c
PP
899=head2 Testing
900
901Now run
902
903 make test
904
3998488b 905All tests should succeed (with some of them skipped).
a56dbb1c 906
ec40c0cd 907Some tests may generate extra messages similar to
a56dbb1c 908
ec40c0cd 909=over 4
a56dbb1c 910
ec40c0cd 911=item A lot of C<bad free>
a56dbb1c 912
3998488b
JH
913in database tests related to Berkeley DB. I<This should be fixed already.>
914If it persists, you may disable this warnings, see L<"PERL_BADFREE">.
72ea3524 915
ec40c0cd 916=item Process terminated by SIGTERM/SIGINT
72ea3524 917
ec40c0cd 918This is a standard message issued by OS/2 applications. *nix
3998488b 919applications die in silence. It is considered to be a feature. One can
ec40c0cd 920easily disable this by appropriate sighandlers.
a56dbb1c 921
ec40c0cd
IZ
922However the test engine bleeds these message to screen in unexpected
923moments. Two messages of this kind I<should> be present during
924testing.
a56dbb1c 925
ec40c0cd 926=back
a56dbb1c 927
ec40c0cd
IZ
928To get finer test reports, call
929
930 perl t/harness
931
932The report with F<io/pipe.t> failing may look like this:
a56dbb1c 933
ec40c0cd
IZ
934 Failed Test Status Wstat Total Fail Failed List of failed
935 ------------------------------------------------------------
936 io/pipe.t 12 1 8.33% 9
937 7 tests skipped, plus 56 subtests skipped.
938 Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay.
939
940The reasons for most important skipped tests are:
941
942=over 8
a56dbb1c 943
ec40c0cd 944=item F<op/fs.t>
a56dbb1c 945
a7665c5e
GS
946=over 4
947
a56dbb1c
PP
948=item 18
949
ec40c0cd
IZ
950Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
951provides only 2sec time granularity (for compatibility with FAT?).
a56dbb1c
PP
952
953=item 25
954
955Checks C<truncate()> on a filehandle just opened for write - I do not
956know why this should or should not work.
957
958=back
959
a56dbb1c
PP
960=item F<op/stat.t>
961
962Checks C<stat()>. Tests:
963
964=over 4
965
a56dbb1c
PP
966=item 4
967
ec40c0cd
IZ
968Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
969provides only 2sec time granularity (for compatibility with FAT?).
a56dbb1c
PP
970
971=back
972
a56dbb1c 973=back
615d1a09 974
a56dbb1c 975=head2 Installing the built perl
615d1a09 976
491527d0
GS
977If you haven't yet moved perl.dll onto LIBPATH, do it now.
978
a56dbb1c 979Run
615d1a09 980
a56dbb1c 981 make install
615d1a09 982
a56dbb1c
PP
983It would put the generated files into needed locations. Manually put
984F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
aa689395 985PATH, F<perl.dll> to a location on your LIBPATH.
615d1a09 986
a56dbb1c 987Run
615d1a09 988
3998488b 989 make installcmd INSTALLCMDDIR=d:/ir/on/path
615d1a09 990
a56dbb1c 991to convert perl utilities to F<.cmd> files and put them on
aa689395 992PATH. You need to put F<.EXE>-utilities on path manually. They are
a56dbb1c
PP
993installed in C<$prefix/bin>, here C<$prefix> is what you gave to
994F<Configure>, see L<Making>.
995
996=head2 C<a.out>-style build
997
998Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
999
1000 make perl_
1001
1002test and install by
1003
1004 make aout_test
1005 make aout_install
1006
aa689395 1007Manually put F<perl_.exe> to a location on your PATH.
a56dbb1c 1008
a56dbb1c
PP
1009B<Note.> The build process for C<perl_> I<does not know> about all the
1010dependencies, so you should make sure that anything is up-to-date,
1011say, by doing
1012
3998488b 1013 make perl_dll
a56dbb1c
PP
1014
1015first.
1016
1017=head1 Build FAQ
1018
1019=head2 Some C</> became C<\> in pdksh.
1020
1021You have a very old pdksh. See L<Prerequisites>.
1022
1023=head2 C<'errno'> - unresolved external
1024
1025You do not have MT-safe F<db.lib>. See L<Prerequisites>.
1026
2c2e0e8c 1027=head2 Problems with tr or sed
a56dbb1c 1028
2c2e0e8c 1029reported with very old version of tr and sed.
a56dbb1c
PP
1030
1031=head2 Some problem (forget which ;-)
1032
aa689395 1033You have an older version of F<perl.dll> on your LIBPATH, which
a56dbb1c
PP
1034broke the build of extensions.
1035
1036=head2 Library ... not found
1037
1038You did not run C<omflibs>. See L<Prerequisites>.
1039
1040=head2 Segfault in make
1041
aa689395 1042You use an old version of GNU make. See L<Prerequisites>.
a56dbb1c 1043
884335e8
YST
1044=head2 op/sprintf test failure
1045
1046This can result from a bug in emx sprintf which was fixed in 0.9d fix 03.
1047
a56dbb1c
PP
1048=head1 Specific (mis)features of OS/2 port
1049
1050=head2 C<setpriority>, C<getpriority>
1051
1052Note that these functions are compatible with *nix, not with the older
1053ports of '94 - 95. The priorities are absolute, go from 32 to -95,
72ea3524 1054lower is quicker. 0 is the default priority.
a56dbb1c 1055
d88df687
IZ
1056B<WARNING>. Calling C<getpriority> on a non-existing process could lock
1057the system before Warp3 fixpak22. Starting with Warp3, Perl will use
1058a workaround: it aborts getpriority() if the process is not present.
1059This is not possible on older versions C<2.*>, and has a race
1060condition anyway.
3998488b 1061
a56dbb1c
PP
1062=head2 C<system()>
1063
1064Multi-argument form of C<system()> allows an additional numeric
1065argument. The meaning of this argument is described in
1066L<OS2::Process>.
1067
3998488b 1068When finding a program to run, Perl first asks the OS to look for executables
d88df687
IZ
1069on C<PATH> (OS/2 adds extension F<.exe> if no extension is present).
1070If not found, it looks for a script with possible extensions
3998488b
JH
1071added in this order: no extension, F<.cmd>, F<.btm>,
1072F<.bat>, F<.pl>. If found, Perl checks the start of the file for magic
1073strings C<"#!"> and C<"extproc ">. If found, Perl uses the rest of the
1074first line as the beginning of the command line to run this script. The
1075only mangling done to the first line is extraction of arguments (currently
1076up to 3), and ignoring of the path-part of the "interpreter" name if it can't
1077be found using the full path.
1078
1079E.g., C<system 'foo', 'bar', 'baz'> may lead Perl to finding
1080F<C:/emx/bin/foo.cmd> with the first line being
1081
1082 extproc /bin/bash -x -c
1083
d88df687 1084If F</bin/bash.exe> is not found, then Perl looks for an executable F<bash.exe> on
3998488b
JH
1085C<PATH>. If found in F<C:/emx.add/bin/bash.exe>, then the above system() is
1086translated to
1087
1088 system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
1089
1090One additional translation is performed: instead of F</bin/sh> Perl uses
1091the hardwired-or-customized shell (see C<L<"PERL_SH_DIR">>).
1092
1093The above search for "interpreter" is recursive: if F<bash> executable is not
1094found, but F<bash.btm> is found, Perl will investigate its first line etc.
1095The only hardwired limit on the recursion depth is implicit: there is a limit
10964 on the number of additional arguments inserted before the actual arguments
1097given to system(). In particular, if no additional arguments are specified
1098on the "magic" first lines, then the limit on the depth is 4.
1099
1100If Perl finds that the found executable is of different type than the
1101current session, it will start the new process in a separate session of
1102necessary type. Call via C<OS2::Process> to disable this magic.
1103
d88df687
IZ
1104B<WARNING>. Due to the described logic, you need to explicitly
1105specify F<.com> extension if needed. Moreover, if the executable
1106F<perl5.6.1> is requested, Perl will not look for F<perl5.6.1.exe>.
1107[This may change in the future.]
1108
aa689395
PP
1109=head2 C<extproc> on the first line
1110
3998488b 1111If the first chars of a Perl script are C<"extproc ">, this line is treated
aa689395 1112as C<#!>-line, thus all the switches on this line are processed (twice
3998488b 1113if script was started via cmd.exe). See L<perlrun/DESCRIPTION>.
aa689395 1114
a56dbb1c 1115=head2 Additional modules:
615d1a09 1116
3998488b 1117L<OS2::Process>, L<OS2::DLL>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. These
2c2e0e8c 1118modules provide access to additional numeric argument for C<system>
3998488b
JH
1119and to the information about the running process,
1120to DLLs having functions with REXX signature and to the REXX runtime, to
a56dbb1c 1121OS/2 databases in the F<.INI> format, and to Extended Attributes.
615d1a09 1122
72ea3524 1123Two additional extensions by Andreas Kaiser, C<OS2::UPM>, and
3998488b 1124C<OS2::FTP>, are included into C<ILYAZ> directory, mirrored on CPAN.
615d1a09 1125
a56dbb1c 1126=head2 Prebuilt methods:
615d1a09 1127
a56dbb1c 1128=over 4
615d1a09 1129
a56dbb1c 1130=item C<File::Copy::syscopy>
615d1a09 1131
d7678ab8 1132used by C<File::Copy::copy>, see L<File::Copy>.
615d1a09 1133
a56dbb1c 1134=item C<DynaLoader::mod2fname>
615d1a09 1135
72ea3524 1136used by C<DynaLoader> for DLL name mangling.
615d1a09 1137
a56dbb1c 1138=item C<Cwd::current_drive()>
615d1a09 1139
a56dbb1c 1140Self explanatory.
615d1a09 1141
a56dbb1c 1142=item C<Cwd::sys_chdir(name)>
615d1a09 1143
a56dbb1c 1144leaves drive as it is.
615d1a09 1145
a56dbb1c 1146=item C<Cwd::change_drive(name)>
615d1a09 1147
3998488b 1148chanes the "current" drive.
615d1a09 1149
a56dbb1c 1150=item C<Cwd::sys_is_absolute(name)>
615d1a09 1151
a56dbb1c 1152means has drive letter and is_rooted.
615d1a09 1153
a56dbb1c 1154=item C<Cwd::sys_is_rooted(name)>
615d1a09 1155
a56dbb1c 1156means has leading C<[/\\]> (maybe after a drive-letter:).
615d1a09 1157
a56dbb1c 1158=item C<Cwd::sys_is_relative(name)>
615d1a09 1159
a56dbb1c 1160means changes with current dir.
615d1a09 1161
a56dbb1c 1162=item C<Cwd::sys_cwd(name)>
615d1a09 1163
aa689395 1164Interface to cwd from EMX. Used by C<Cwd::cwd>.
615d1a09 1165
a56dbb1c 1166=item C<Cwd::sys_abspath(name, dir)>
615d1a09 1167
a56dbb1c
PP
1168Really really odious function to implement. Returns absolute name of
1169file which would have C<name> if CWD were C<dir>. C<Dir> defaults to the
1170current dir.
615d1a09 1171
6d0f518e 1172=item C<Cwd::extLibpath([type])>
615d1a09 1173
a56dbb1c
PP
1174Get current value of extended library search path. If C<type> is
1175present and I<true>, works with END_LIBPATH, otherwise with
1176C<BEGIN_LIBPATH>.
615d1a09 1177
a56dbb1c 1178=item C<Cwd::extLibpath_set( path [, type ] )>
615d1a09 1179
a56dbb1c
PP
1180Set current value of extended library search path. If C<type> is
1181present and I<true>, works with END_LIBPATH, otherwise with
1182C<BEGIN_LIBPATH>.
615d1a09 1183
3998488b
JH
1184=item C<OS2::Error(do_harderror,do_exception)>
1185
1186Returns C<undef> if it was not called yet, otherwise bit 1 is
1187set if on the previous call do_harderror was enabled, bit
d1be9408 11882 is set if on previous call do_exception was enabled.
3998488b
JH
1189
1190This function enables/disables error popups associated with
1191hardware errors (Disk not ready etc.) and software exceptions.
1192
1193I know of no way to find out the state of popups I<before> the first call
1194to this function.
1195
1196=item C<OS2::Errors2Drive(drive)>
1197
1198Returns C<undef> if it was not called yet, otherwise return false if errors
1199were not requested to be written to a hard drive, or the drive letter if
1200this was requested.
1201
1202This function may redirect error popups associated with hardware errors
1203(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at
1204the root directory of the specified drive. Overrides OS2::Error() specified
1205by individual programs. Given argument undef will disable redirection.
1206
1207Has global effect, persists after the application exits.
1208
1209I know of no way to find out the state of redirection of popups to the disk
1210I<before> the first call to this function.
1211
1212=item OS2::SysInfo()
1213
1214Returns a hash with system information. The keys of the hash are
1215
1216 MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
1217 MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
1218 MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
1219 VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
1220 MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
1221 TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
1222 MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
1223 FOREGROUND_PROCESS
1224
1225=item OS2::BootDrive()
1226
1227Returns a letter without colon.
1228
1229=item C<OS2::MorphPM(serve)>, C<OS2::UnMorphPM(serve)>
1230
1231Transforms the current application into a PM application and back.
1232The argument true means that a real message loop is going to be served.
1233OS2::MorphPM() returns the PM message queue handle as an integer.
1234
1235See L<"Centralized management of resources"> for additional details.
1236
1237=item C<OS2::Serve_Messages(force)>
1238
1239Fake on-demand retrieval of outstanding PM messages. If C<force> is false,
1240will not dispatch messages if a real message loop is known to
1241be present. Returns number of messages retrieved.
1242
1243Dies with "QUITing..." if WM_QUIT message is obtained.
1244
1245=item C<OS2::Process_Messages(force [, cnt])>
1246
1247Retrieval of PM messages until window creation/destruction.
1248If C<force> is false, will not dispatch messages if a real message loop
1249is known to be present.
1250
1251Returns change in number of windows. If C<cnt> is given,
1252it is incremented by the number of messages retrieved.
1253
1254Dies with "QUITing..." if WM_QUIT message is obtained.
1255
1256=item C<OS2::_control87(new,mask)>
1257
1258the same as L<_control87(3)> of EMX. Takes integers as arguments, returns
1259the previous coprocessor control word as an integer. Only bits in C<new> which
1260are present in C<mask> are changed in the control word.
1261
1262=item OS2::get_control87()
1263
1264gets the coprocessor control word as an integer.
1265
1266=item C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)>
1267
1268The variant of OS2::_control87() with default values good for
1269handling exception mask: if no C<mask>, uses exception mask part of C<new>
1270only. If no C<new>, disables all the floating point exceptions.
1271
1272See L<"Misfeatures"> for details.
1273
a56dbb1c 1274=back
615d1a09 1275
a56dbb1c
PP
1276(Note that some of these may be moved to different libraries -
1277eventually).
615d1a09 1278
615d1a09 1279
3998488b
JH
1280=head2 Prebuilt variables:
1281
1282=over 4
1283
1284=item $OS2::emx_rev
1285
1286same as _emx_rev of EMX, a string similar to C<0.9c>.
1287
1288=item $OS2::emx_env
1289
1290same as _emx_env of EMX, a number similar to 0x8001.
1291
1292=item $OS2::os_ver
1293
1294a number C<OS_MAJOR + 0.001 * OS_MINOR>.
1295
1296=back
1297
a56dbb1c 1298=head2 Misfeatures
615d1a09 1299
a56dbb1c 1300=over 4
615d1a09 1301
13a2d996 1302=item *
615d1a09 1303
367f3c24
IZ
1304Since L<flock(3)> is present in EMX, but is not functional, it is
1305emulated by perl. To disable the emulations, set environment variable
1306C<USE_PERL_FLOCK=0>.
1307
13a2d996 1308=item *
367f3c24
IZ
1309
1310Here is the list of things which may be "broken" on
55497cff
PP
1311EMX (from EMX docs):
1312
13a2d996 1313=over 4
d7678ab8
CS
1314
1315=item *
1316
1317The functions L<recvmsg(3)>, L<sendmsg(3)>, and L<socketpair(3)> are not
1318implemented.
1319
1320=item *
1321
1322L<sock_init(3)> is not required and not implemented.
1323
1324=item *
1325
367f3c24 1326L<flock(3)> is not yet implemented (dummy function). (Perl has a workaround.)
d7678ab8
CS
1327
1328=item *
1329
1330L<kill(3)>: Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
1331
1332=item *
1333
1334L<waitpid(3)>:
1335
55497cff
PP
1336 WUNTRACED
1337 Not implemented.
1338 waitpid() is not implemented for negative values of PID.
1339
d7678ab8
CS
1340=back
1341
55497cff 1342Note that C<kill -9> does not work with the current version of EMX.
615d1a09 1343
13a2d996 1344=item *
615d1a09 1345
72ea3524 1346Since F<sh.exe> is used for globing (see L<perlfunc/glob>), the bugs
a56dbb1c 1347of F<sh.exe> plague perl as well.
615d1a09 1348
a56dbb1c 1349In particular, uppercase letters do not work in C<[...]>-patterns with
aa689395 1350the current pdksh.
615d1a09 1351
3998488b
JH
1352=item *
1353
1354Unix-domain sockets on OS/2 live in a pseudo-file-system C</sockets/...>.
1355To avoid a failure to create a socket with a name of a different form,
1356C<"/socket/"> is prepended to the socket name (unless it starts with this
1357already).
1358
1359This may lead to problems later in case the socket is accessed via the
1360"usual" file-system calls using the "initial" name.
1361
1362=item *
1363
1364Apparently, IBM used a compiler (for some period of time around '95?) which
1365changes FP mask right and left. This is not I<that> bad for IBM's
1366programs, but the same compiler was used for DLLs which are used with
1367general-purpose applications. When these DLLs are used, the state of
1368floating-point flags in the application is not predictable.
1369
1370What is much worse, some DLLs change the floating point flags when in
1371_DLLInitTerm() (e.g., F<TCP32IP>). This means that even if you do not I<call>
1372any function in the DLL, just the act of loading this DLL will reset your
1373flags. What is worse, the same compiler was used to compile some HOOK DLLs.
1374Given that HOOK dlls are executed in the context of I<all> the applications
1375in the system, this means a complete unpredictablity of floating point
1376flags on systems using such HOOK DLLs. E.g., F<GAMESRVR.DLL> of B<DIVE>
1377origin changes the floating point flags on each write to the TTY of a VIO
1378(windowed text-mode) applications.
1379
1380Some other (not completely debugged) situations when FP flags change include
1381some video drivers (?), and some operations related to creation of the windows.
1382People who code B<OpenGL> may have more experience on this.
1383
1384Perl is generally used in the situation when all the floating-point
1385exceptions are ignored, as is the default under EMX. If they are not ignored,
1386some benign Perl programs would get a C<SIGFPE> and would die a horrible death.
1387
1388To circumvent this, Perl uses two hacks. They help against I<one> type of
1389damage only: FP flags changed when loading a DLL.
1390
1391One of the hacks is to disable floating point exceptions on startup (as
1392is the default with EMX). This helps only with compile-time-linked DLLs
1393changing the flags before main() had a chance to be called.
1394
1395The other hack is to restore FP flags after a call to dlopen(). This helps
1396against similar damage done by DLLs _DLLInitTerm() at runtime. Currently
1397no way to switch these hacks off is provided.
1398
a56dbb1c 1399=back
615d1a09 1400
55497cff
PP
1401=head2 Modifications
1402
1403Perl modifies some standard C library calls in the following ways:
1404
1405=over 9
1406
1407=item C<popen>
1408
72ea3524 1409C<my_popen> uses F<sh.exe> if shell is required, cf. L<"PERL_SH_DIR">.
55497cff
PP
1410
1411=item C<tmpnam>
1412
1413is created using C<TMP> or C<TEMP> environment variable, via
1414C<tempnam>.
1415
1416=item C<tmpfile>
1417
72ea3524 1418If the current directory is not writable, file is created using modified
55497cff
PP
1419C<tmpnam>, so there may be a race condition.
1420
1421=item C<ctermid>
1422
1423a dummy implementation.
1424
1425=item C<stat>
1426
1427C<os2_stat> special-cases F</dev/tty> and F</dev/con>.
1428
3998488b
JH
1429=item C<mkdir>, C<rmdir>
1430
1431these EMX functions do not work if the path contains a trailing C</>.
1432Perl contains a workaround for this.
1433
367f3c24
IZ
1434=item C<flock>
1435
1436Since L<flock(3)> is present in EMX, but is not functional, it is
1437emulated by perl. To disable the emulations, set environment variable
1438C<USE_PERL_FLOCK=0>.
1439
55497cff
PP
1440=back
1441
3998488b
JH
1442=head2 Identifying DLLs
1443
1444All the DLLs built with the current versions of Perl have ID strings
1445identifying the name of the extension, its version, and the version
1446of Perl required for this DLL. Run C<bldlevel DLL-name> to find this
1447info.
1448
1449=head2 Centralized management of resources
1450
1451Since to call certain OS/2 API one needs to have a correctly initialized
1452C<Win> subsystem, OS/2-specific extensions may require getting C<HAB>s and
1453C<HMQ>s. If an extension would do it on its own, another extension could
1454fail to initialize.
1455
1456Perl provides a centralized management of these resources:
1457
1458=over
1459
1460=item C<HAB>
1461
1462To get the HAB, the extension should call C<hab = perl_hab_GET()> in C. After
1463this call is performed, C<hab> may be accessed as C<Perl_hab>. There is
1464no need to release the HAB after it is used.
1465
1466If by some reasons F<perl.h> cannot be included, use
1467
1468 extern int Perl_hab_GET(void);
1469
1470instead.
1471
1472=item C<HMQ>
1473
1474There are two cases:
1475
1476=over
1477
1478=item *
1479
1480the extension needs an C<HMQ> only because some API will not work otherwise.
1481Use C<serve = 0> below.
1482
1483=item *
1484
1485the extension needs an C<HMQ> since it wants to engage in a PM event loop.
1486Use C<serve = 1> below.
1487
1488=back
1489
1490To get an C<HMQ>, the extension should call C<hmq = perl_hmq_GET(serve)> in C.
1491After this call is performed, C<hmq> may be accessed as C<Perl_hmq>.
1492
1493To signal to Perl that HMQ is not needed any more, call
1494C<perl_hmq_UNSET(serve)>. Perl process will automatically morph/unmorph itself
1495into/from a PM process if HMQ is needed/not-needed. Perl will automatically
1496enable/disable C<WM_QUIT> message during shutdown if the message queue is
1497served/not-served.
1498
1499B<NOTE>. If during a shutdown there is a message queue which did not disable
1500WM_QUIT, and which did not process the received WM_QUIT message, the
1501shutdown will be automatically cancelled. Do not call C<perl_hmq_GET(1)>
1502unless you are going to process messages on an orderly basis.
1503
1504=back
1505
a56dbb1c 1506=head1 Perl flavors
615d1a09 1507
72ea3524 1508Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
aa689395 1509same basket (though EMX environment tries hard to overcome this
a56dbb1c
PP
1510limitations, so the situation may somehow improve). There are 4
1511executables for Perl provided by the distribution:
615d1a09 1512
a56dbb1c 1513=head2 F<perl.exe>
615d1a09 1514
a56dbb1c
PP
1515The main workhorse. This is a chimera executable: it is compiled as an
1516C<a.out>-style executable, but is linked with C<omf>-style dynamic
aa689395
PP
1517library F<perl.dll>, and with dynamic CRT DLL. This executable is a
1518VIO application.
a56dbb1c 1519
3998488b 1520It can load perl dynamic extensions, and it can fork().
a56dbb1c
PP
1521
1522B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.
1523
1524=head2 F<perl_.exe>
1525
3998488b
JH
1526This is a statically linked C<a.out>-style executable. It cannot
1527load dynamic Perl extensions. The executable supplied in binary
1528distributions has a lot of extensions prebuilt, thus the above restriction is
1529important only if you use custom-built extensions. This executable is a VIO
a56dbb1c
PP
1530application.
1531
3998488b 1532I<This is the only executable with does not require OS/2.> The
a56dbb1c 1533friends locked into C<M$> world would appreciate the fact that this
72ea3524 1534executable runs under DOS, Win0.3*, Win0.95 and WinNT with an
a56dbb1c
PP
1535appropriate extender. See L<"Other OSes">.
1536
1537=head2 F<perl__.exe>
1538
aa689395 1539This is the same executable as F<perl___.exe>, but it is a PM
a56dbb1c
PP
1540application.
1541
3998488b
JH
1542B<Note.> Usually (unless explicitly redirected during the startup)
1543STDIN, STDERR, and STDOUT of a PM
1544application are redirected to F<nul>. However, it is possible to I<see>
a56dbb1c 1545them if you start C<perl__.exe> from a PM program which emulates a
aa689395 1546console window, like I<Shell mode> of Emacs or EPM. Thus it I<is
a56dbb1c 1547possible> to use Perl debugger (see L<perldebug>) to debug your PM
3998488b
JH
1548application (but beware of the message loop lockups - this will not
1549work if you have a message queue to serve, unless you hook the serving
1550into the getc() function of the debugger).
a56dbb1c 1551
3998488b
JH
1552Another way to see the output of a PM program is to run it as
1553
1554 pm_prog args 2>&1 | cat -
1555
1556with a shell I<different> from F<cmd.exe>, so that it does not create
1557a link between a VIO session and the session of C<pm_porg>. (Such a link
1558closes the VIO window.) E.g., this works with F<sh.exe> - or with Perl!
1559
1560 open P, 'pm_prog args 2>&1 |' or die;
1561 print while <P>;
1562
1563The flavor F<perl__.exe> is required if you want to start your program without
1564a VIO window present, but not C<detach>ed (run C<help detach> for more info).
1565Very useful for extensions which use PM, like C<Perl/Tk> or C<OpenGL>.
a56dbb1c
PP
1566
1567=head2 F<perl___.exe>
1568
1569This is an C<omf>-style executable which is dynamically linked to
aa689395 1570F<perl.dll> and CRT DLL. I know no advantages of this executable
a56dbb1c
PP
1571over C<perl.exe>, but it cannot fork() at all. Well, one advantage is
1572that the build process is not so convoluted as with C<perl.exe>.
1573
aa689395 1574It is a VIO application.
a56dbb1c
PP
1575
1576=head2 Why strange names?
1577
1578Since Perl processes the C<#!>-line (cf.
1579L<perlrun/DESCRIPTION>, L<perlrun/Switches>,
1580L<perldiag/"Not a perl script">,
1581L<perldiag/"No Perl script found in input">), it should know when a
1582program I<is a Perl>. There is some naming convention which allows
1583Perl to distinguish correct lines from wrong ones. The above names are
72ea3524 1584almost the only names allowed by this convention which do not contain
a56dbb1c
PP
1585digits (which have absolutely different semantics).
1586
1587=head2 Why dynamic linking?
1588
1589Well, having several executables dynamically linked to the same huge
1590library has its advantages, but this would not substantiate the
3998488b
JH
1591additional work to make it compile. The reason is the complicated-to-developers
1592but very quick and convenient-to-users "hard" dynamic linking used by OS/2.
1593
1594There are two distinctive features of the dyna-linking model of OS/2:
1595all the references to external functions are resolved at the compile time;
1596there is no runtime fixup of the DLLs after they are loaded into memory.
1597The first feature is an enormous advantage over other models: it avoids
1598conflicts when several DLLs used by an application export entries with
1599the same name. In such cases "other" models of dyna-linking just choose
1600between these two entry points using some random criterion - with predictable
1601disasters as results. But it is the second feature which requires the build
1602of F<perl.dll>.
a56dbb1c 1603
72ea3524 1604The address tables of DLLs are patched only once, when they are
3998488b
JH
1605loaded. The addresses of the entry points into DLLs are guaranteed to be
1606the same for all the programs which use the same DLL. This removes the
1607runtime fixup - once DLL is loaded, its code is read-only.
a56dbb1c 1608
3998488b
JH
1609While this allows some (significant?) performance advantages, this makes life
1610much harder for developers, since the above scheme makes it impossible
1611for a DLL to be "linked" to a symbol in the F<.EXE> file. Indeed, this
1612would need a DLL to have different relocations tables for the
1613(different) executables which use this DLL.
1614
1615However, a dynamically loaded Perl extension is forced to use some symbols
1616from the perl
1617executable, e.g., to know how to find the arguments to the functions:
1618the arguments live on the perl
1619internal evaluation stack. The solution is to put the main code of
1620the interpreter into a DLL, and make the F<.EXE> file which just loads
1621this DLL into memory and supplies command-arguments. The extension DLL
1622cannot link to symbols in F<.EXE>, but it has no problem linking
1623to symbols in the F<.DLL>.
a56dbb1c 1624
72ea3524 1625This I<greatly> increases the load time for the application (as well as
3998488b
JH
1626complexity of the compilation). Since interpreter is in a DLL,
1627the C RTL is basically forced to reside in a DLL as well (otherwise
1628extensions would not be able to use CRT). There are some advantages if
1629you use different flavors of perl, such as running F<perl.exe> and
1630F<perl__.exe> simultaneously: they share the memory of F<perl.dll>.
1631
1632B<NOTE>. There is one additional effect which makes DLLs more wasteful:
1633DLLs are loaded in the shared memory region, which is a scarse resource
1634given the 512M barrier of the "standard" OS/2 virtual memory. The code of
1635F<.EXE> files is also shared by all the processes which use the particular
1636F<.EXE>, but they are "shared in the private address space of the process";
1637this is possible because the address at which different sections
1638of the F<.EXE> file are loaded is decided at compile-time, thus all the
1639processes have these sections loaded at same addresses, and no fixup
1640of internal links inside the F<.EXE> is needed.
1641
d1be9408 1642Since DLLs may be loaded at run time, to have the same mechanism for DLLs
3998488b
JH
1643one needs to have the address range of I<any of the loaded> DLLs in the
1644system to be available I<in all the processes> which did not load a particular
1645DLL yet. This is why the DLLs are mapped to the shared memory region.
a56dbb1c
PP
1646
1647=head2 Why chimera build?
1648
aa689395 1649Current EMX environment does not allow DLLs compiled using Unixish
3998488b
JH
1650C<a.out> format to export symbols for data (or at least some types of
1651data). This forces C<omf>-style compile of F<perl.dll>.
a56dbb1c 1652
aa689395 1653Current EMX environment does not allow F<.EXE> files compiled in
a56dbb1c
PP
1654C<omf> format to fork(). fork() is needed for exactly three Perl
1655operations:
1656
1657=over 4
1658
3998488b 1659=item *
a56dbb1c 1660
3998488b 1661explicit fork() in the script,
a56dbb1c 1662
3998488b 1663=item *
a56dbb1c 1664
3998488b
JH
1665C<open FH, "|-">
1666
1667=item *
a56dbb1c 1668
3998488b 1669C<open FH, "-|">, in other words, opening pipes to itself.
a56dbb1c
PP
1670
1671=back
1672
3998488b
JH
1673While these operations are not questions of life and death, they are
1674needed for a lot of
1675useful scripts. This forces C<a.out>-style compile of
a56dbb1c
PP
1676F<perl.exe>.
1677
1678
1679=head1 ENVIRONMENT
1680
aa689395
PP
1681Here we list environment variables with are either OS/2- and DOS- and
1682Win*-specific, or are more important under OS/2 than under other OSes.
a56dbb1c
PP
1683
1684=head2 C<PERLLIB_PREFIX>
1685
aa689395 1686Specific for EMX port. Should have the form
a56dbb1c
PP
1687
1688 path1;path2
1689
1690or
1691
1692 path1 path2
1693
1694If the beginning of some prebuilt path matches F<path1>, it is
1695substituted with F<path2>.
1696
1697Should be used if the perl library is moved from the default
1698location in preference to C<PERL(5)LIB>, since this would not leave wrong
3998488b 1699entries in @INC. For example, if the compiled version of perl looks for @INC
eb447b86
IZ
1700in F<f:/perllib/lib>, and you want to install the library in
1701F<h:/opt/gnu>, do
1702
1703 set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
a56dbb1c 1704
3998488b
JH
1705This will cause Perl with the prebuilt @INC of
1706
1707 f:/perllib/lib/5.00553/os2
1708 f:/perllib/lib/5.00553
1709 f:/perllib/lib/site_perl/5.00553/os2
1710 f:/perllib/lib/site_perl/5.00553
1711 .
1712
1713to use the following @INC:
1714
1715 h:/opt/gnu/5.00553/os2
1716 h:/opt/gnu/5.00553
1717 h:/opt/gnu/site_perl/5.00553/os2
1718 h:/opt/gnu/site_perl/5.00553
1719 .
1720
a56dbb1c
PP
1721=head2 C<PERL_BADLANG>
1722
3998488b 1723If 0, perl ignores setlocale() failing. May be useful with some
a56dbb1c
PP
1724strange I<locale>s.
1725
1726=head2 C<PERL_BADFREE>
1727
3998488b
JH
1728If 0, perl would not warn of in case of unwarranted free(). With older
1729perls this might be
1730useful in conjunction with the module DB_File, which was buggy when
1731dynamically linked and OMF-built.
1732
1733Should not be set with newer Perls, since this may hide some I<real> problems.
a56dbb1c
PP
1734
1735=head2 C<PERL_SH_DIR>
1736
aa689395 1737Specific for EMX port. Gives the directory part of the location for
a56dbb1c
PP
1738F<sh.exe>.
1739
367f3c24
IZ
1740=head2 C<USE_PERL_FLOCK>
1741
1742Specific for EMX port. Since L<flock(3)> is present in EMX, but is not
1743functional, it is emulated by perl. To disable the emulations, set
1744environment variable C<USE_PERL_FLOCK=0>.
1745
a56dbb1c
PP
1746=head2 C<TMP> or C<TEMP>
1747
3998488b 1748Specific for EMX port. Used as storage place for temporary files.
a56dbb1c
PP
1749
1750=head1 Evolution
1751
1752Here we list major changes which could make you by surprise.
1753
1754=head2 Priorities
1755
1756C<setpriority> and C<getpriority> are not compatible with earlier
1757ports by Andreas Kaiser. See C<"setpriority, getpriority">.
1758
d88df687 1759=head2 DLL name mangling: pre 5.6.2
a56dbb1c
PP
1760
1761With the release 5.003_01 the dynamically loadable libraries
3998488b
JH
1762should be rebuilt when a different version of Perl is compiled. In particular,
1763DLLs (including F<perl.dll>) are now created with the names
a56dbb1c
PP
1764which contain a checksum, thus allowing workaround for OS/2 scheme of
1765caching DLLs.
1766
3998488b
JH
1767It may be possible to code a simple workaround which would
1768
1769=over
1770
1771=item *
1772
1773find the old DLLs looking through the old @INC;
1774
1775=item *
1776
1777mangle the names according to the scheme of new perl and copy the DLLs to
1778these names;
1779
1780=item *
1781
1782edit the internal C<LX> tables of DLL to reflect the change of the name
1783(probably not needed for Perl extension DLLs, since the internally coded names
1784are not used for "specific" DLLs, they used only for "global" DLLs).
1785
1786=item *
1787
1788edit the internal C<IMPORT> tables and change the name of the "old"
1789F<perl????.dll> to the "new" F<perl????.dll>.
1790
1791=back
1792
354a27bf 1793=head2 DLL name mangling: 5.6.2 and beyond
d88df687
IZ
1794
1795In fact mangling of I<extension> DLLs was done due to misunderstanding
1796of the OS/2 dynaloading model. OS/2 (effectively) maintains two
1797different tables of loaded DLL:
1798
1799=over
1800
1801=item Global DLLs
1802
1803those loaded by the base name from C<LIBPATH>; including those
1804associated at link time;
1805
1806=item specific DLLs
1807
1808loaded by the full name.
1809
1810=back
1811
1812When resolving a request for a global DLL, the table of already-loaded
1813specific DLLs is (effectively) ignored; moreover, specific DLLs are
1814I<always> loaded from the prescribed path.
1815
1816There is/was a minor twist which makes this scheme fragile: what to do
1817with DLLs loaded from
1818
1819=over
1820
1821=item C<BEGINLIBPATH> and C<ENDLIBPATH>
1822
1823(which depend on the process)
1824
1825=item F<.> from C<LIBPATH>
1826
1827which I<effectively> depends on the process (although C<LIBPATH> is the
1828same for all the processes).
1829
1830=back
1831
1832Unless C<LIBPATHSTRICT> is set to C<T> (and the kernel is after
18332000/09/01), such DLLs are considered to be global. When loading a
1834global DLL it is first looked in the table of already-loaded global
1835DLLs. Because of this the fact that one executable loaded a DLL from
1836C<BEGINLIBPATH> and C<ENDLIBPATH>, or F<.> from C<LIBPATH> may affect
1837I<which> DLL is loaded when I<another> executable requests a DLL with
1838the same name. I<This> is the reason for version-specific mangling of
1839the DLL name for perl DLL.
1840
1841Since the Perl extension DLLs are always loaded with the full path,
1842there is no need to mangle their names in a version-specific ways:
1843their directory already reflects the corresponding version of perl,
1844and @INC takes into account binary compatibility with older version.
1845Starting from C<5.6.2> the name mangling scheme is fixed to be the
1846same as for Perl 5.005_53 (same as in a popular binary release). Thus
1847new Perls will be able to I<resolve the names> of old extension DLLs
1848if @INC allows finding their directories.
1849
1850However, this still does not guarantie that these DLL may be loaded.
1851The reason is the mangling of the name of the I<Perl DLL>. And since
1852the extension DLLs link with the Perl DLL, extension DLLs for older
1853versions would load an older Perl DLL, and would most probably
1854segfault (since the data in this DLL is not properly initialized).
1855
1856There is a partial workaround (which can be made complete with newer
1857OS/2 kernels): create a forwarder DLL with the same name as the DLL of
1858the older version of Perl, which forwards the entry points to the
1859newer Perl's DLL. Make this DLL accessible on (say) the C<BEGINLIBPATH> of
1860the new Perl executable. When the new executable accesses old Perl's
1861extension DLLs, they would request the old Perl's DLL by name, get the
1862forwarder instead, so effectively will link with the currently running
1863(new) Perl DLL.
1864
1865This may break in two ways:
1866
1867=over
1868
1869=item *
1870
1871Old perl executable is started when a new executable is running has
1872loaded an extension compiled for the old executable (ouph!). In this
1873case the old executable will get a forwarder DLL instead of the old
1874perl DLL, so would link with the new perl DLL. While not directly
1875fatal, it will behave the same as new excutable. This beats the whole
1876purpose of explicitly starting an old executable.
1877
1878=item *
1879
1880A new executable loads an extension compiled for the old executable
1881when an old perl executable is running. In this case the extension
1882will not pick up the forwarder - with fatal results.
1883
1884=back
1885
1886With support for C<LIBPATHSTRICT> this may be circumvented - unless
1887one of DLLs is started from F<.> from C<LIBPATH> (I do not know
1888whether C<LIBPATHSTRICT> affects this case).
1889
1890B<REMARK>. Unless newer kernels allow F<.> in C<BEGINLIBPATH> (older
1891do not), this mess cannot be completely cleaned.
1892
1893
1894B<REMARK>. C<LIBPATHSTRICT>, C<BEGINLIBPATH> and C<ENDLIBPATH> are
1895not environment variables, although F<cmd.exe> emulates them on C<SET
1896...> lines. From Perl they may be accessed by L<Cwd::extLibpath> and
1897L<Cwd::extLibpath_set>.
1898
1899=head2 DLL forwarder generation
1900
1901Assume that the old DLL is named F<perlE0AC.dll> (as is one for
19025.005_53), and the new version is 5.6.1. Create a file
1903F<perl5shim.def-leader> with
1904
1905 LIBRARY 'perlE0AC' INITINSTANCE TERMINSTANCE
1906 DESCRIPTION '@#perl5-porters@perl.org:5.006001#@ Perl module for 5.00553 -> Perl 5.6.1 forwarder'
1907 CODE LOADONCALL
1908 DATA LOADONCALL NONSHARED MULTIPLE
1909 EXPORTS
1910
1911modifying the versions/names as needed. Run
1912
1913 perl -wnle "next if 0../EXPORTS/; print qq( \"$1\") if /\"(\w+)\"/" perl5.def >lst
1914
1915in the Perl build directory (to make the DLL smaller replace perl5.def
1916with the definition file for the older version of Perl if present).
1917
1918 cat perl5shim.def-leader lst >perl5shim.def
1919 gcc -Zomf -Zdll -o perlE0AC.dll perl5shim.def -s -llibperl
1920
1921(ignore multiple C<warning L4085>).
1922
a56dbb1c
PP
1923=head2 Threading
1924
3998488b
JH
1925As of release 5.003_01 perl is linked to multithreaded C RTL
1926DLL. If perl itself is not compiled multithread-enabled, so will not be perl's
a56dbb1c
PP
1927malloc(). However, extensions may use multiple thread on their own
1928risk.
1929
3998488b
JH
1930This was needed to compile C<Perl/Tk> for XFree86-OS/2 out-of-the-box, and
1931link with DLLs for other useful libraries, which typically are compiled
1932with C<-Zmt -Zcrtdll>.
a56dbb1c
PP
1933
1934=head2 Calls to external programs
1935
1936Due to a popular demand the perl external program calling has been
72ea3524 1937changed wrt Andreas Kaiser's port. I<If> perl needs to call an
a56dbb1c
PP
1938external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
1939whatever is the override, see L<"PERL_SH_DIR">.
1940
1941Thus means that you need to get some copy of a F<sh.exe> as well (I
3998488b 1942use one from pdksh). The path F<F:/bin> above is set up automatically during
a56dbb1c
PP
1943the build to a correct value on the builder machine, but is
1944overridable at runtime,
1945
1946B<Reasons:> a consensus on C<perl5-porters> was that perl should use
1947one non-overridable shell per platform. The obvious choices for OS/2
1948are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible
3998488b 1949with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. This assures almost
aa689395
PP
1950100% compatibility with the scripts coming from *nix. As an added benefit
1951this works as well under DOS if you use DOS-enabled port of pdksh
1952(see L<"Prerequisites">).
a56dbb1c 1953
aa689395 1954B<Disadvantages:> currently F<sh.exe> of pdksh calls external programs
a56dbb1c 1955via fork()/exec(), and there is I<no> functioning exec() on
3998488b 1956OS/2. exec() is emulated by EMX by an asynchronous call while the caller
72ea3524 1957waits for child completion (to pretend that the C<pid> did not change). This
a56dbb1c
PP
1958means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(),
1959which may lead to some resources taken from the system (even if we do
1960not count extra work needed for fork()ing).
1961
72ea3524
IZ
1962Note that this a lesser issue now when we do not spawn F<sh.exe>
1963unless needed (metachars found).
1964
1965One can always start F<cmd.exe> explicitly via
a56dbb1c
PP
1966
1967 system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
1968
72ea3524 1969If you need to use F<cmd.exe>, and do not want to hand-edit thousands of your
a56dbb1c
PP
1970scripts, the long-term solution proposed on p5-p is to have a directive
1971
1972 use OS2::Cmd;
1973
1974which will override system(), exec(), C<``>, and
1975C<open(,'...|')>. With current perl you may override only system(),
1976readpipe() - the explicit version of C<``>, and maybe exec(). The code
1977will substitute the one-argument call to system() by
1978C<CORE::system('cmd.exe', '/c', shift)>.
1979
1980If you have some working code for C<OS2::Cmd>, please send it to me,
1981I will include it into distribution. I have no need for such a module, so
1982cannot test it.
1983
2c2e0e8c 1984For the details of the current situation with calling external programs,
3998488b
JH
1985see L<Starting OS/2 (and DOS) programs under Perl>. Set us mention a couple
1986of features:
2c2e0e8c 1987
13a2d996 1988=over 4
2c2e0e8c 1989
13a2d996 1990=item *
2c2e0e8c 1991
3998488b
JH
1992External scripts may be called by their basename. Perl will try the same
1993extensions as when processing B<-S> command-line switch.
1994
1995=item *
1996
1997External scripts starting with C<#!> or C<extproc > will be executed directly,
1998without calling the shell, by calling the program specified on the rest of
1999the first line.
2c2e0e8c
IZ
2000
2001=back
2002
df3ef7a9
IZ
2003=head2 Memory allocation
2004
2005Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound
ec40c0cd 2006for speed, but perl is not, since its malloc is lightning-fast.
4375e838
GS
2007Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quicker
2008than EMX one. I do not have convincing data about memory footprint, but
3998488b 2009a (pretty random) benchmark showed that Perl's one is 5% better.
df3ef7a9
IZ
2010
2011Combination of perl's malloc() and rigid DLL name resolution creates
2012a special problem with library functions which expect their return value to
2013be free()d by system's free(). To facilitate extensions which need to call
2014such functions, system memory-allocation functions are still available with
2015the prefix C<emx_> added. (Currently only DLL perl has this, it should
2016propagate to F<perl_.exe> shortly.)
2017
ec40c0cd
IZ
2018=head2 Threads
2019
2020One can build perl with thread support enabled by providing C<-D usethreads>
2021option to F<Configure>. Currently OS/2 support of threads is very
2022preliminary.
2023
2024Most notable problems:
2025
13a2d996 2026=over 4
ec40c0cd
IZ
2027
2028=item C<COND_WAIT>
2029
2030may have a race condition. Needs a reimplementation (in terms of chaining
3998488b 2031waiting threads, with the linked list stored in per-thread structure?).
ec40c0cd
IZ
2032
2033=item F<os2.c>
2034
2035has a couple of static variables used in OS/2-specific functions. (Need to be
2036moved to per-thread structure, or serialized?)
2037
2038=back
2039
2040Note that these problems should not discourage experimenting, since they
2041have a low probability of affecting small programs.
2042
d88df687
IZ
2043=head1 BUGS
2044
2045This description was not updated since 5.6.1, see F<os2/Changes> for
2046more info.
2047
a56dbb1c
PP
2048=cut
2049
2050OS/2 extensions
2051~~~~~~~~~~~~~~~
72ea3524 2052I include 3 extensions by Andreas Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP,
a56dbb1c
PP
2053into my ftp directory, mirrored on CPAN. I made
2054some minor changes needed to compile them by standard tools. I cannot
2055test UPM and FTP, so I will appreciate your feedback. Other extensions
2056there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI
2057files - and maybe some other extensions at the time you read it.
2058
2059Note that OS2 perl defines 2 pseudo-extension functions
aa689395
PP
2060OS2::Copy::copy and DynaLoader::mod2fname (many more now, see
2061L<Prebuilt methods>).
a56dbb1c
PP
2062
2063The -R switch of older perl is deprecated. If you need to call a REXX code
2064which needs access to variables, include the call into a REXX compartment
2065created by
2066 REXX_call {...block...};
2067
2068Two new functions are supported by REXX code,
2069 REXX_eval 'string';
2070 REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference;
2071
2072If you have some other extensions you want to share, send the code to
2073me. At least two are available: tied access to EA's, and tied access
2074to system databases.
615d1a09 2075
a56dbb1c 2076=head1 AUTHOR
615d1a09 2077
a56dbb1c 2078Ilya Zakharevich, ilya@math.ohio-state.edu
615d1a09 2079
a56dbb1c 2080=head1 SEE ALSO
615d1a09 2081
a56dbb1c 2082perl(1).
615d1a09 2083
a56dbb1c 2084=cut
615d1a09 2085