perlos2.pod

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

=head2 C<extproc> on the first line

If the first chars of a Perl script are C<"extproc ">, this line is treated
as C<#!>-line, thus all the switches on this line are processed (twice
if script was started via cmd.exe).  See L<perlrun/DESCRIPTION>.

=head2 Additional modules:

L<OS2::Process>, L<OS2::DLL>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. These
modules provide access to additional numeric argument for C<system>
and to the information about the running process,
to DLLs having functions with REXX signature and to the REXX runtime, to
OS/2 databases in the F<.INI> format, and to Extended Attributes.

Two additional extensions by Andreas Kaiser, C<OS2::UPM>, and
C<OS2::FTP>, are included into C<ILYAZ> directory, mirrored on CPAN.
Other OS/2-related extensions are available too.

=head2 Prebuilt methods:

=over 4

=item C<File::Copy::syscopy>

used by C<File::Copy::copy>, see L<File::Copy>.

=item C<DynaLoader::mod2fname>

used by C<DynaLoader> for DLL name mangling.

=item  C<Cwd::current_drive()>

Self explanatory.

=item  C<Cwd::sys_chdir(name)>

leaves drive as it is.

=item  C<Cwd::change_drive(name)>

chanes the "current" drive.

=item  C<Cwd::sys_is_absolute(name)>

means has drive letter and is_rooted.

=item  C<Cwd::sys_is_rooted(name)>

means has leading C<[/\\]> (maybe after a drive-letter:).

=item  C<Cwd::sys_is_relative(name)>

means changes with current dir.

=item  C<Cwd::sys_cwd(name)>

Interface to cwd from EMX. Used by C<Cwd::cwd>.

=item  C<Cwd::sys_abspath(name, dir)>

Really really odious function to implement. Returns absolute name of
file which would have C<name> if CWD were C<dir>.  C<Dir> defaults to the
current dir.

=item  C<Cwd::extLibpath([type])>

Get current value of extended library search path. If C<type> is
present and positive, works with C<END_LIBPATH>, if negative, works
with C<LIBPATHSTRICT>, otherwise with C<BEGIN_LIBPATH>. 

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

Set current value of extended library search path. If C<type> is
present and positive, works with <END_LIBPATH>, if negative, works
with C<LIBPATHSTRICT>, 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 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.

=item C<OS2::DLLname([how [, \&xsub]])>

Gives the information about the Perl DLL or the DLL containing the C
function bound to by C<&xsub>.  The meaning of C<how> is: default (2):
full name; 0: handle; 1: module name.

=back

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


=head2 Prebuilt variables:

=over 4

=item $OS2::emx_rev

numeric value is the same as _emx_rev of EMX, a string value the same
as _emx_vprt (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>.

=item $OS2::is_aout

true if the Perl library was compiled in AOUT format.

=item $OS2::can_fork

true if the current executable is an AOUT EMX executable, so Perl can
fork.  Do not use this, use the portable check for
$Config::Config{dfork}.

=item $OS2::nsyserror

This variable (default is 1) controls whether to enforce the contents
of $^E to start with C<SYS0003>-like id.  If set to 0, then the string
value of $^E is what is available from the OS/2 message file.  (Some
messages in this file have an C<SYS0003>-like id prepended, some not.)

=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 *

See L<"Text-mode filehandles">.

=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 Perl 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 =