Contents (This may be a little bit obsolete)
- perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
+ perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
NAME
SYNOPSIS
run (and build extensions, and - possibly - be built itself) under any
environment which can run EMX. The current list is DOS,
DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
-only one works, see L<"perl_.exe">.
+only one works, see L</"F<perl_.exe>">.
Note that not all features of Perl are available under these
environments. This depends on the features the I<extender> - most
EMX runtime is required (may be substituted by RSX). Note that
it is possible to make F<perl_.exe> to run under DOS without any
-external support by binding F<emx.exe>/F<rsx.exe> to it, see C<emxbind>. Note
-that under DOS for best results one should use RSX runtime, which
+external support by binding F<emx.exe>/F<rsx.exe> to it, see L<emxbind(1)>.
+Note that under DOS for best results one should use RSX runtime, which
has much more functions working (like C<fork>, C<popen> and so on). In
fact RSX is required if there is no VCPI present. Note the
RSX requires DPMI. Many implementations of DPMI are known to be very
To run Perl on DPMI platforms one needs RSX runtime. This is
needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see
-L<"Other OSes">). RSX would not work with VCPI
+L</"Other OSes">). RSX would not work with VCPI
only, as EMX would, it requires DMPI.
Having RSX and the latest F<sh.exe> one gets a fully functional
pipes in between, and/or quoting of arguments), Perl uses an external
shell. With EMX port such shell should be named F<sh.exe>, and located
either in the wired-in-during-compile locations (usually F<F:/bin>),
-or in configurable location (see L<"PERL_SH_DIR">).
+or in configurable location (see L</"C<PERL_SH_DIR>">).
For best results use EMX pdksh. The standard binary (5.2.14 or later) runs
under DOS (with L</RSX>) as well, see
perl ../../blah/foo.cmd arg1 arg2 arg3
(note that the argument C<-my_opts> is taken care of by the C<extproc> line
-in your script, see L<C<extproc> on the first line>).
+in your script, see C<L</extproc>> on the first line).
To understand what the above I<magic> does, read perl docs about C<-S>
switch - see L<perlrun>, and cmdref about C<extproc>:
do).
Note however that to use some of these operators you need to have a
-sh-syntax shell installed (see L<"Pdksh">,
-L<"Frequently asked questions">), and perl should be able to find it
-(see L<"PERL_SH_DIR">).
+sh-syntax shell installed (see L</"Pdksh">,
+L</"Frequently asked questions">), and perl should be able to find it
+(see L</"C<PERL_SH_DIR>">).
The cases when the shell is used are:
=item *
Did you run your programs with C<-w> switch? See
-L<Starting OSE<sol>2 (and DOS) programs under Perl>.
+L</Starting OSE<sol>2 (and DOS) programs under Perl>.
=item *
=head2 C<``> and pipe-C<open> do not work under DOS.
-This may a variant of just L<"I cannot run external programs">, or a
+This may a variant of just L</"I cannot run external programs">, or a
deeper problem. Basically: you I<need> RSX (see L</Prerequisites>)
for these commands to work, and you may need a port of F<sh.exe> which
understands command arguments. One of such ports is listed in
L</Prerequisites> under RSX. Do not forget to set variable
-C<L<"PERL_SH_DIR">> as well.
+L</"C<PERL_SH_DIR>"> as well.
DPMI is required for RSX.
=item C<PERL_BADLANG>
may be needed if you change your codepage I<after> perl installation,
-and the new value is not supported by EMX. See L<"PERL_BADLANG">.
+and the new value is not supported by EMX. See L</"C<PERL_BADLANG>">.
=item C<PERL_BADFREE>
-see L<"PERL_BADFREE">.
+see L</"C<PERL_BADFREE>">.
=item F<Config.pm>
into F<perl.exe>, you do not need to change
anything. However, for perl to find the library if you use a different
path, you need to
-C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
+C<set PERLLIB_PREFIX> in F<Config.sys>, see L</"C<PERLLIB_PREFIX>">.
=item Additional Perl modules
- unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.23.7/
+ unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.37.4/
Same remark as above applies. Additionally, if this directory is not
one of directories on @INC (and @INC is influenced by C<PERLLIB_PREFIX>), you
require shell, like the commands using I<redirection> and I<shell
metacharacters>. It is also used instead of explicit F</bin/sh>.
-Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
+Set C<PERL_SH_DIR> (see L</"C<PERL_SH_DIR>">) if you move F<sh.exe> from
the above location.
B<Note.> It may be possible to use some other sh-compatible shell (untested).
=head2 B<Warning>
The automatic and manual perl installation leave precompiled paths
-inside perl executables. While these paths are overwriteable (see
-L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), some people may prefer
+inside perl executables. While these paths are overwritable (see
+L</"C<PERLLIB_PREFIX>">, L</"C<PERL_SH_DIR>">), some people may prefer
binary editing of paths inside the executables/DLLs.
=head1 Accessing documentation
view perl ExtUtils::MakeMaker
(currently the last two may hit a wrong location, but this may improve
-soon). Under Win* see L<"SYNOPSIS">.
+soon). Under Win* see L</"SYNOPSIS">.
If you want to build the docs yourself, and have I<OS/2 toolkit>, run
C<prefix> means: where to install the resulting perl library. Giving
correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
-see L<"PERLLIB_PREFIX">.
+see L</"C<PERLLIB_PREFIX>">.
I<Ignore the message about missing C<ln>, and about C<-c> option to
tr>. The latter is most probably already fixed, if you see it and can trace
=item A lot of C<bad free>
in database tests related to Berkeley DB. I<This should be fixed already.>
-If it persists, you may disable this warnings, see L<"PERL_BADFREE">.
+If it persists, you may disable this warnings, see L</"C<PERL_BADFREE>">.
=item Process terminated by SIGTERM/SIGINT
The report with F<io/pipe.t> failing may look like this:
- Failed Test Status Wstat Total Fail Failed List of failed
- ------------------------------------------------------------
- io/pipe.t 12 1 8.33% 9
- 7 tests skipped, plus 56 subtests skipped.
- Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay.
+ Failed Test Status Wstat Total Fail Failed List of failed
+ ------------------------------------------------------------
+ io/pipe.t 12 1 8.33% 9
+ 7 tests skipped, plus 56 subtests skipped.
+ Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed,
+ 99.98% okay.
The reasons for most important skipped tests are:
=head2 C<a.out>-style build
-Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
+Proceed as above, but make F<perl_.exe> (see L</"F<perl_.exe>">) by
make perl_
Install the bundle C<Bundle::OS2_default>
- perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1
+ perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_1
This may take a couple of hours on 1GHz processor (when run the first time).
And this should not be necessarily a smooth procedure. Some modules may not
specify required dependencies, so one may need to repeat this procedure several
times until the results stabilize.
- perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2
- perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3
+ perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_2
+ perl5.8.2 -MCPAN -e "install Bundle::OS2_default" < nul |& tee 00cpan_i_3
Even after they stabilize, some tests may fail.
a new executable per XS extension.
Here is a possible workaround: create a toplevel F<Makefile.PL> in
-F<$CPANHOME/.cpan/build/> with contents being (compare with L<Making
+F<$CPANHOME/.cpan/build/> with contents being (compare with L</Making
executables with a custom collection of statically loaded extensions>)
use ExtUtils::MakeMaker;
emximp -o foo.a foo.lib
whichever is appropriate.) Also, make sure that the DLLs for external
-libraries are usable with with executables compiled without C<-Zmtd> options.
+libraries are usable with executables compiled without C<-Zmtd> options.
When you are sure that only a few subdirectories
lead to failures, you may want to add C<-j4> option to C<make> to speed up
to ignore the environment when setting the Perl-library search patch, etc.
If you fill comfortable with I<embedding> interface (see L<perlembed>), such
-things are easy to do repeating the steps outlined in L<Making
+things are easy to do repeating the steps outlined in L</Making
executables with a custom collection of statically loaded extensions>, and
doing more comprehensive edits to main() of F<perlmain.c>. The people with
little desire to understand Perl can just rename main(), and do necessary
Here is the sample C file:
- #define INCL_DOS
- #define INCL_NOPM
- /* These are needed for compile if os2.h includes os2tk.h, not os2emx.h */
- #define INCL_DOSPROCESS
- #include <os2.h>
-
- #include "EXTERN.h"
- #define PERL_IN_MINIPERLMAIN_C
- #include "perl.h"
-
- static char *me;
- HMODULE handle;
-
- static void
- die_with(char *msg1, char *msg2, char *msg3, char *msg4)
- {
- ULONG c;
- char *s = " error: ";
-
- DosWrite(2, me, strlen(me), &c);
- DosWrite(2, s, strlen(s), &c);
- DosWrite(2, msg1, strlen(msg1), &c);
- DosWrite(2, msg2, strlen(msg2), &c);
- DosWrite(2, msg3, strlen(msg3), &c);
- DosWrite(2, msg4, strlen(msg4), &c);
- DosWrite(2, "\r\n", 2, &c);
- exit(255);
- }
-
- typedef ULONG (*fill_extLibpath_t)(int type, char *pre, char *post, int replace, char *msg);
- typedef int (*main_t)(int type, char *argv[], char *env[]);
- typedef int (*handler_t)(void* data, int which);
-
- #ifndef PERL_DLL_BASENAME
- # define PERL_DLL_BASENAME "perl"
- #endif
-
- static HMODULE
- load_perl_dll(char *basename)
- {
- char buf[300], fail[260];
- STRLEN l, dirl;
- fill_extLibpath_t f;
- ULONG rc_fullname;
- HMODULE handle, handle1;
-
- if (_execname(buf, sizeof(buf) - 13) != 0)
- die_with("Can't find full path: ", strerror(errno), "", "");
- /* XXXX Fill 'me' with new value */
- l = strlen(buf);
- while (l && buf[l-1] != '/' && buf[l-1] != '\\')
- l--;
- dirl = l - 1;
- strcpy(buf + l, basename);
- l += strlen(basename);
- strcpy(buf + l, ".dll");
- if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle)) != 0
- && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
- die_with("Can't load DLL ", buf, "", "");
- if (rc_fullname)
- return handle; /* was loaded with short name; all is fine */
- if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
- die_with(buf, ": DLL exports no symbol ", "fill_extLibpath", "");
- buf[dirl] = 0;
- if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
- 0 /* keep old value */, me))
- die_with(me, ": prepending BEGINLIBPATH", "", "");
- if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
- die_with(me, ": finding perl DLL again via BEGINLIBPATH", "", "");
- buf[dirl] = '\\';
- if (handle1 != handle) {
- if (DosQueryModuleName(handle1, sizeof(fail), fail))
- strcpy(fail, "???");
- die_with(buf, ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
- fail,
- "\n\tYou may need to manipulate global BEGINLIBPATH and LIBPATHSTRICT"
- "\n\tso that the other copy is loaded via BEGINLIBPATH.");
- }
- return handle;
- }
-
- int
- main(int argc, char **argv, char **env)
- {
- main_t f;
- handler_t h;
-
- me = argv[0];
- /**/
- handle = load_perl_dll(PERL_DLL_BASENAME);
-
- if (DosQueryProcAddr(handle, 0, "Perl_OS2_handler_install", (PFN*)&h))
- die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "Perl_OS2_handler_install", "");
- if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
- || !h((void *)"~dll", Perlos2_handler_perllib_to)
- || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
- die_with(PERL_DLL_BASENAME, ": Can't install @INC manglers", "", "");
-
- if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
- die_with(PERL_DLL_BASENAME, ": DLL exports no symbol ", "dll_perlmain", "");
- return f(argc, argv, env);
- }
-
+ #define INCL_DOS
+ #define INCL_NOPM
+ /* These are needed for compile if os2.h includes os2tk.h, not
+ * os2emx.h */
+ #define INCL_DOSPROCESS
+ #include <os2.h>
+
+ #include "EXTERN.h"
+ #define PERL_IN_MINIPERLMAIN_C
+ #include "perl.h"
+
+ static char *me;
+ HMODULE handle;
+
+ static void
+ die_with(char *msg1, char *msg2, char *msg3, char *msg4)
+ {
+ ULONG c;
+ char *s = " error: ";
+
+ DosWrite(2, me, strlen(me), &c);
+ DosWrite(2, s, strlen(s), &c);
+ DosWrite(2, msg1, strlen(msg1), &c);
+ DosWrite(2, msg2, strlen(msg2), &c);
+ DosWrite(2, msg3, strlen(msg3), &c);
+ DosWrite(2, msg4, strlen(msg4), &c);
+ DosWrite(2, "\r\n", 2, &c);
+ exit(255);
+ }
+
+ typedef ULONG (*fill_extLibpath_t)(int type,
+ char *pre,
+ char *post,
+ int replace,
+ char *msg);
+ typedef int (*main_t)(int type, char *argv[], char *env[]);
+ typedef int (*handler_t)(void* data, int which);
+
+ #ifndef PERL_DLL_BASENAME
+ # define PERL_DLL_BASENAME "perl"
+ #endif
+
+ static HMODULE
+ load_perl_dll(char *basename)
+ {
+ char buf[300], fail[260];
+ STRLEN l, dirl;
+ fill_extLibpath_t f;
+ ULONG rc_fullname;
+ HMODULE handle, handle1;
+
+ if (_execname(buf, sizeof(buf) - 13) != 0)
+ die_with("Can't find full path: ", strerror(errno), "", "");
+ /* XXXX Fill 'me' with new value */
+ l = strlen(buf);
+ while (l && buf[l-1] != '/' && buf[l-1] != '\\')
+ l--;
+ dirl = l - 1;
+ strcpy(buf + l, basename);
+ l += strlen(basename);
+ strcpy(buf + l, ".dll");
+ if ( (rc_fullname = DosLoadModule(fail, sizeof fail, buf, &handle))
+ != 0
+ && DosLoadModule(fail, sizeof fail, basename, &handle) != 0 )
+ die_with("Can't load DLL ", buf, "", "");
+ if (rc_fullname)
+ return handle; /* was loaded with short name; all is fine */
+ if (DosQueryProcAddr(handle, 0, "fill_extLibpath", (PFN*)&f))
+ die_with(buf,
+ ": DLL exports no symbol ",
+ "fill_extLibpath",
+ "");
+ buf[dirl] = 0;
+ if (f(0 /*BEGINLIBPATH*/, buf /* prepend */, NULL /* append */,
+ 0 /* keep old value */, me))
+ die_with(me, ": prepending BEGINLIBPATH", "", "");
+ if (DosLoadModule(fail, sizeof fail, basename, &handle1) != 0)
+ die_with(me,
+ ": finding perl DLL again via BEGINLIBPATH",
+ "",
+ "");
+ buf[dirl] = '\\';
+ if (handle1 != handle) {
+ if (DosQueryModuleName(handle1, sizeof(fail), fail))
+ strcpy(fail, "???");
+ die_with(buf,
+ ":\n\tperl DLL via BEGINLIBPATH is different: \n\t",
+ fail,
+ "\n\tYou may need to manipulate global BEGINLIBPATH"
+ " and LIBPATHSTRICT"
+ "\n\tso that the other copy is loaded via"
+ BEGINLIBPATH.");
+ }
+ return handle;
+ }
+
+ int
+ main(int argc, char **argv, char **env)
+ {
+ main_t f;
+ handler_t h;
+
+ me = argv[0];
+ /**/
+ handle = load_perl_dll(PERL_DLL_BASENAME);
+
+ if (DosQueryProcAddr(handle,
+ 0,
+ "Perl_OS2_handler_install",
+ (PFN*)&h))
+ die_with(PERL_DLL_BASENAME,
+ ": DLL exports no symbol ",
+ "Perl_OS2_handler_install",
+ "");
+ if ( !h((void *)"~installprefix", Perlos2_handler_perllib_from)
+ || !h((void *)"~dll", Perlos2_handler_perllib_to)
+ || !h((void *)"~dll/sh/ksh.exe", Perlos2_handler_perl_sh) )
+ die_with(PERL_DLL_BASENAME,
+ ": Can't install @INC manglers",
+ "",
+ "");
+ if (DosQueryProcAddr(handle, 0, "dll_perlmain", (PFN*)&f))
+ die_with(PERL_DLL_BASENAME,
+ ": DLL exports no symbol ",
+ "dll_perlmain",
+ "");
+ return f(argc, argv, env);
+ }
=head1 Build FAQ
system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
One additional translation is performed: instead of F</bin/sh> Perl uses
-the hardwired-or-customized shell (see C<L<"PERL_SH_DIR">>).
+the hardwired-or-customized shell (see L</"C<PERL_SH_DIR>">).
The above search for "interpreter" is recursive: if F<bash> executable is not
found, but F<bash.btm> is found, Perl will investigate its first line etc.
The argument true means that a real message loop is going to be served.
OS2::MorphPM() returns the PM message queue handle as an integer.
-See L<"Centralized management of resources"> for additional details.
+See L</"Centralized management of resources"> for additional details.
=item C<OS2::Serve_Messages(force)>
handling exception mask: if no C<mask>, uses exception mask part of C<new>
only. If no C<new>, disables all the floating point exceptions.
-See L<"Misfeatures"> for details.
+See L</"Misfeatures"> for details.
=item C<OS2::DLLname([how [, \&xsub]])>
=item *
-See L<"Text-mode filehandles">.
+See L</"Text-mode filehandles">.
=item *
=item C<popen>
-C<my_popen> uses F<sh.exe> if shell is required, cf. L<"PERL_SH_DIR">.
+C<my_popen> uses F<sh.exe> if shell is required, cf. L</"C<PERL_SH_DIR>">.
=item C<tmpnam>
- and also C<PMWIN_entries> - in F<os2ish.h>). These ordinals can be
accessed via the APIs:
- CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
- DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
- DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
- DeclWinFuncByORD_CACHE_resetError_survive(),
- DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
- DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
+ CallORD(), DeclFuncByORD(), DeclVoidFuncByORD(),
+ DeclOSFuncByORD(), DeclWinFuncByORD(), AssignFuncPByORD(),
+ DeclWinFuncByORD_CACHE(), DeclWinFuncByORD_CACHE_survive(),
+ DeclWinFuncByORD_CACHE_resetError_survive(),
+ DeclWinFunc_CACHE(), DeclWinFunc_CACHE_resetError(),
+ DeclWinFunc_CACHE_survive(), DeclWinFunc_CACHE_resetError_survive()
See the header files and the C code in the supplied OS/2-related
modules for the details on usage of these functions.
I<This is the only executable with does not require OS/2.> The
friends locked into C<M$> world would appreciate the fact that this
executable runs under DOS, Win0.3*, Win0.95 and WinNT with an
-appropriate extender. See L<"Other OSes">.
+appropriate extender. See L</"Other OSes">.
=head2 F<perl__.exe>
=head2 Priorities
C<setpriority> and C<getpriority> are not compatible with earlier
-ports by Andreas Kaiser. See C<"setpriority, getpriority">.
+ports by Andreas Kaiser. See L</setpriority, getpriority>.
=head2 DLL name mangling: pre 5.6.2
modifying the versions/names as needed. Run
- perl -wnle "next if 0../EXPORTS/; print qq( \"$1\") if /\"(\w+)\"/" perl5.def >lst
+ perl -wnle "next if 0../EXPORTS/; print qq( \"$1\")
+ if /\"(\w+)\"/" perl5.def >lst
in the Perl build directory (to make the DLL smaller replace perl5.def
with the definition file for the older version of Perl if present).
Due to a popular demand the perl external program calling has been
changed wrt Andreas Kaiser's port. I<If> perl needs to call an
external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
-whatever is the override, see L<"PERL_SH_DIR">.
+whatever is the override, see L</"C<PERL_SH_DIR>">.
Thus means that you need to get some copy of a F<sh.exe> as well (I
use one from pdksh). The path F<F:/bin> above is set up automatically during
cannot test it.
For the details of the current situation with calling external programs,
-see L<Starting OSE<sol>2 (and DOS) programs under Perl>. Set us mention a couple
-of features:
+see L</Starting OSE<sol>2 (and DOS) programs under Perl>. Set us
+mention a couple of features:
=over 4
Note that OS2 perl defines 2 pseudo-extension functions
OS2::Copy::copy and DynaLoader::mod2fname (many more now, see
-L<Prebuilt methods>).
+L</Prebuilt methods>).
The -R switch of older perl is deprecated. If you need to call a REXX code
which needs access to variables, include the call into a REXX compartment