perlos2.pod

MSYS在windows下模拟了一个类unix的终端

C<BEGIN_LIBPATH>. 

=item  C<Cwd::extLibpath_set( path [, type ] )>

Set current value of extended library search path. If C<type> is
present and I<true>, works with END_LIBPATH, otherwise with
C<BEGIN_LIBPATH>. 

=item C<OS2::Error(do_harderror,do_exception)>

Returns	C<undef> if it was not called yet, otherwise bit 1 is
set if on the previous call do_harderror was enabled, bit
2 is set if if on previous call do_exception was enabled.

This function enables/disables error popups associated with 
hardware errors (Disk not ready etc.) and software exceptions.

I know of no way to find out the state of popups I<before> the first call
to this function.

=item C<OS2::Errors2Drive(drive)>

Returns C<undef> if it was not called yet, otherwise return false if errors
were not requested to be written to a hard drive, or the drive letter if
this was requested.

This function may redirect error popups associated with hardware errors
(Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at
the root directory of the specified drive.  Overrides OS2::Error() specified
by individual programs.  Given argument undef will disable redirection.

Has global effect, persists after the application exits.

I know of no way to find out the state of redirection of popups to the disk
I<before> the first call to this function.

=item OS2::SysInfo()

Returns a hash with system information. The keys of the hash are

	MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
	MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
	MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
	VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
	MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
	TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
	MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
	FOREGROUND_PROCESS

=item OS2::BootDrive()

Returns a letter without colon.

=item C<OS2::MorphPM(serve)>, C<OS2::UnMorphPM(serve)>

Transforms the current application into a PM application and back.
The argument true means that a real message loop is going to be served.
OS2::MorphPM() returns the PM message queue handle as an integer.

See L<"Centralized management of resources"> for additional details.

=item C<OS2::Serve_Messages(force)>

Fake on-demand retrieval of outstanding PM messages.  If C<force> is false,
will not dispatch messages if a real message loop is known to
be present.  Returns number of messages retrieved.

Dies with "QUITing..." if WM_QUIT message is obtained.

=item C<OS2::Process_Messages(force [, cnt])>

Retrieval of PM messages until window creation/destruction.  
If C<force> is false, will not dispatch messages if a real message loop
is known to be present.

Returns change in number of windows.  If C<cnt> is given,
it is incremented by the number of messages retrieved.

Dies with "QUITing..." if WM_QUIT message is obtained.

=item C<OS2::_control87(new,mask)>

the same as L<_control87(3)> of EMX.  Takes integers as arguments, returns
the previous coprocessor control word as an integer.  Only bits in C<new> which
are present in C<mask> are changed in the control word.

=item OS2::get_control87()

gets the coprocessor control word as an integer.

=item C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)>

The variant of OS2::_control87() with default values good for
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.

=back

(Note that some of these may be moved to different libraries -
eventually).


=head2 Prebuilt variables:

=over 4

=item $OS2::emx_rev

same as _emx_rev of EMX, a string similar to C<0.9c>.

=item $OS2::emx_env

same as _emx_env of EMX, a number similar to 0x8001.

=item $OS2::os_ver

a number C<OS_MAJOR + 0.001 * OS_MINOR>.

=back

=head2 Misfeatures

=over 4

=item *

Since L<flock(3)> is present in EMX, but is not functional, it is 
emulated by perl.  To disable the emulations, set environment variable
C<USE_PERL_FLOCK=0>.

=item *

Here is the list of things which may be "broken" on
EMX (from EMX docs):

=over 4

=item *

The functions L<recvmsg(3)>, L<sendmsg(3)>, and L<socketpair(3)> are not
implemented.

=item *

L<sock_init(3)> is not required and not implemented.

=item *

L<flock(3)> is not yet implemented (dummy function).  (Perl has a workaround.)

=item *

L<kill(3)>:  Special treatment of PID=0, PID=1 and PID=-1 is not implemented.

=item *

L<waitpid(3)>:

      WUNTRACED
	      Not implemented.
      waitpid() is not implemented for negative values of PID.

=back

Note that C<kill -9> does not work with the current version of EMX.

=item *

Since F<sh.exe> is used for globing (see L<perlfunc/glob>), the bugs
of F<sh.exe> plague perl as well. 

In particular, uppercase letters do not work in C<[...]>-patterns with
the current pdksh.

=item *

Unix-domain sockets on OS/2 live in a pseudo-file-system C</sockets/...>.
To avoid a failure to create a socket with a name of a different form,
C<"/socket/"> is prepended to the socket name (unless it starts with this
already).

This may lead to problems later in case the socket is accessed via the
"usual" file-system calls using the "initial" name.

=item *

Apparently, IBM used a compiler (for some period of time around '95?) which
changes FP mask right and left.  This is not I<that> bad for IBM's
programs, but the same compiler was used for DLLs which are used with
general-purpose applications.  When these DLLs are used, the state of
floating-point flags in the application is not predictable.

What is much worse, some DLLs change the floating point flags when in
_DLLInitTerm() (e.g., F<TCP32IP>).  This means that even if you do not I<call>
any function in the DLL, just the act of loading this DLL will reset your
flags.  What is worse, the same compiler was used to compile some HOOK DLLs.
Given that HOOK dlls are executed in the context of I<all> the applications
in the system, this means a complete unpredictablity of floating point
flags on systems using such HOOK DLLs.  E.g., F<GAMESRVR.DLL> of B<DIVE>
origin changes the floating point flags on each write to the TTY of a VIO
(windowed text-mode) applications.

Some other (not completely debugged) situations when FP flags change include
some video drivers (?), and some operations related to creation of the windows.
People who code B<OpenGL> may have more experience on this.

Perl is generally used in the situation when all the floating-point
exceptions are ignored, as is the default under EMX.  If they are not ignored,
some benign Perl programs would get a C<SIGFPE> and would die a horrible death.

To circumvent this, Perl uses two hacks.  They help against I<one> type of
damage only: FP flags changed when loading a DLL.

One of the hacks is to disable floating point exceptions on startup (as
is the default with EMX).  This helps only with compile-time-linked DLLs
changing the flags before main() had a chance to be called.

The other hack is to restore FP flags after a call to dlopen().  This helps
against similar damage done by DLLs _DLLInitTerm() at runtime.  Currently
no way to switch these hacks off is provided.

=back

=head2 Modifications

Perl modifies some standard C library calls in the following ways:

=over 9

=item C<popen>

C<my_popen> uses F<sh.exe> if shell is required, cf. L<"PERL_SH_DIR">.

=item C<tmpnam>

is created using C<TMP> or C<TEMP> environment variable, via
C<tempnam>.

=item C<tmpfile>

If the current directory is not writable, file is created using modified
C<tmpnam>, so there may be a race condition.

=item C<ctermid>

a dummy implementation.

=item C<stat>

C<os2_stat> special-cases F</dev/tty> and F</dev/con>.

=item C<mkdir>, C<rmdir>

these EMX functions do not work if the path contains a trailing C</>.
Perl contains a workaround for this.

=item C<flock>

Since L<flock(3)> is present in EMX, but is not functional, it is 
emulated by perl.  To disable the emulations, set environment variable
C<USE_PERL_FLOCK=0>.

=back

=head2 Identifying DLLs

All the DLLs built with the current versions of Perl have ID strings
identifying the name of the extension, its version, and the version
of Perl required for this DLL.  Run C<bldlevel DLL-name> to find this
info.

=head2 Centralized management of resources

Since to call certain OS/2 API one needs to have a correctly initialized
C<Win> subsystem, OS/2-specific extensions may require getting C<HAB>s and
C<HMQ>s.  If an extension would do it on its own, another extension could
fail to initialize.

Perl provides a centralized management of these resources:

=over

=item C<HAB>

To get the HAB, the extension should call C<hab = perl_hab_GET()> in C.  After
this call is performed, C<hab> may be accessed as C<Perl_hab>.  There is
no need to release the HAB after it is used.

If by some reasons F<perl.h> cannot be included, use

  extern int Perl_hab_GET(void);

instead.

=item C<HMQ>

There are two cases:

=over

=item *

the extension needs an C<HMQ> only because some API will not work otherwise.
Use C<serve = 0> below.

=item *

the extension needs an C<HMQ> since it wants to engage in a PM event loop.
Use C<serve = 1> below.

=back

To get an C<HMQ>, the extension should call C<hmq = perl_hmq_GET(serve)> in C.
After this call is performed, C<hmq> may be accessed as C<Perl_hmq>.

To signal to Perl that HMQ is not needed any more, call
C<perl_hmq_UNSET(serve)>.  Perl process will automatically morph/unmorph itself
into/from a PM process if HMQ is needed/not-needed.  Perl will automatically
enable/disable C<WM_QUIT> message during shutdown if the message queue is
served/not-served.

B<NOTE>.  If during a shutdown there is a message queue which did not disable
WM_QUIT, and which did not process the received WM_QUIT message, the
shutdown will be automatically cancelled.  Do not call C<perl_hmq_GET(1)>
unless you are going to process messages on an orderly basis.

=back

=head1 Perl flavors

Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
same basket (though EMX environment tries hard to overcome this
limitations, so the situation may somehow improve). There are 4
executables for Perl provided by the distribution:

=head2 F<perl.exe>

The main workhorse. This is a chimera executable: it is compiled as an
C<a.out>-style executable, but is linked with C<omf>-style dynamic
library F<perl.dll>, and with dynamic CRT DLL. This executable is a
VIO application.

It can load perl dynamic extensions, and it can fork().

B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.

=head2 F<perl_.exe>

This is a statically linked C<a.out>-style executable. It cannot
load dynamic Perl extensions. The executable supplied in binary
distributions has a lot of extensions prebuilt, thus the above restriction is 
important only if you use custom-built extensions. This executable is a VIO
application.

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">.

=head2 F<perl__.exe>

This is the same executable as F<perl___.exe>, but it is a PM
application. 

B<Note.> Usually (unless explicitly redirected during the startup)
STDIN, STDERR, and STDOUT of a PM
application are redirected to F<nul>. However, it is possible to I<see>
them if you start C<perl__.exe> from a PM program which emulates a
console window, like I<Shell mode> of Emacs or EPM. Thus it I<is
possible> to use Perl debugger (see L<perldebug>) to debug your PM
application (but beware of the message loop lockups - this will not
work if you have a message queue to serve, unless you hook the serving
into the getc() function of the debugger).

Another way to see the output of a PM program is to run it as

  pm_prog args 2>&1 | cat -

with a shell I<different> from F<cmd.exe>, so that it does not create
a link between a VIO session and the session of C<pm_porg>.  (Such a link
closes the VIO window.)  E.g., this works with F<sh.exe> - or with Perl!

  open P, 'pm_prog args 2>&1 |' or die;
  print while <P>;

The flavor F<perl__.exe> is required if you want to start your program without
a VIO window present, but not C<detach>ed (run C<help detach> for more info).