summaryrefslogtreecommitdiff
path: root/win32/win32sck.c
Commit message (Collapse)AuthorAgeFilesLines
* Fix Win32 build with MinGW/gcc-4.8+ which define some errno.h values >= 100Steve Hay2013-10-171-11/+37
| | | | | | | | | | | | | | | | | | | | | | | | | | | Commit ea95436966 made changes to how errno.h constants are handled for VC++ 2010 and above, which have added new values in the range 100-140. Some versions of gcc-4.8.0 and above are now catching up and provide some of these new values too (e.g. binaries from http://mingw-w64.sourceforge.net/ but not currently those from http://www.mingw.org/), but they don't provide all of them. EADDRINUSE is provided, so convert_errno_to_wsa_error() gets included, but the compilation fails because the following #defines which VC++ 2010 and above provide are missing: EBADMSG EIDRM ENODATA ENOLINK ENOMSG ENOSR ENOSTR ENOTRECOVERABLE EOTHER ETIME ETXTBSY Simply ignore (#ifdef away) these constants for those compilers that don't provide them.
* Fix the #include of winsock2.h in win32/include/sys/errno2.hSteve Hay2013-09-161-3/+9
| | | | | | | | | | | | | | | | | | | | | | | For some reason (I didn't figure out why) cpan/Win32/Win32.xs did not compile as of the previous commit, but in any case we cannot just blindly include winsock2.h because (a) it is too late if winsock.h has already been included and (b) early WinCE doesn't have it. The definition of _WINSOCKAPI_ was also wrongly not updated to _WINSOCK2API_ but was mistaken in its comment "Don't drag in everything" anyway: it's actually just an old-fashioned "include guard", not a means to include a minimal API from the file. (The mistaken comment came from the original ext/Errno/Errno_pm.PL before this round of $!-related changes. That file also had a redundant "#include <winsock.h>" left in it which should have been removed along with earlier work that removed the other one, so tidy that up too.) Steal a hopefully more correct incantation from win32/include/sys/socket.h instead. Now that we allow for the possibility of winsock.h being used again, we must take care not to make use of WSAECANCELLED if it is not defined. (That is the only WSAExxx constant which we use that was new in winsock2.h.)
* Fix Windows build for compilers other than VC10+Steve Hay2013-09-161-1/+4
| | | | | | | The new errno2.h only ensures that those new Exxx constants which are required by convert_wsa_error_to_errno() have definitions; the other new Exxx constants will remain undefined on compilers other than VC10+, so we must take care not to use them unless we know they are defined.
* Simplify errno2.h slightlySteve Hay2013-09-161-11/+14
| | | | | | | | | | | | | | | | | | | | | There is no need for it to worry about ensuring that standard errno.h values like EINTR are defined. There is no point in it defining dummy constants like EINVALIDPROCTABLE which do not exist in errno.h at all. They would only be given the corresponding WSAExxx values anyway, so the win32sck.c function might just as well return them directly. Other constants like ESOCKTNOSUPPORT which do not exist in errno.h on Windows but presumably exist elsewhere since POSIX tries to exports them are still worth defining (where possible -- it isn't possible for EHOSTDOWN since there is no corresponding WSAEHOSTDOWN); add comments for these for clarity. Also comment which errno.h constants are new in VC10, and mention three of the four that win32/include/sys/socket.h used to redefine because they are used in the perl core (ENOTSOCK, EAFNOSUPPORT and ECONNABORTED) -- the other one (ECONNRESET) does not appear to be used in the perl core as far as I can tell.
* Fix stringification of $! in VC10+ builds where errno > sys_nerrSteve Hay2013-09-161-7/+105
| | | | | | | | | | | | | | | | | | | | | | | | | VC++ 2010 and above define a "POSIX supplement" of errno values ranging from EADDRINUSE (100) to EWOULDBLOCK (140), but sys_nerr is still 43 and strerror() returns "Unknown error" for them. We already avoid using strerror() if errno > sys_nerr, but we treat such values as Windows error codes (i.e. <winerror.h> values) and look up the corresponding system messages for them. There is no better plan for these POSIX supplement errno values, but they must be converted from <errno.h> values to <winerror.h> values first otherwise we will look up the wrong system message. In practice, we only expect to find errno > sys_nerr in the case of Windows sockets errors (we used to assign WSAGetLastError() to errno), so we simply convert Exxx values to WSAExxx values where possible, and use a default <winerror.h> value otherwise (namely, ERROR_INVALID_FUNCTION). This change fixes code such as this: perl -le "$!=107; print $!" which now outputs the expected "No connection could be made because the target machine actively refused it." rather than "The program stopped because an alternate diskette was not inserted." (in VC10+ builds). Also: Fix the spelling of ECANCELED.
* Intercept assignment to $! to translate WSAExxx values to Exxx values on WindowsSteve Hay2013-09-161-17/+22
| | | | | | | | | | | | | | | | | | | | | | | | | Since perl previously assigned WSAExxx values to $! on Windows it is quite possible that (Perl-level) user code may also manually make similar assignments, which will now cause breakage if the value put in $! is subsequently compared to Errno/POSIX constants because the latter are now the corresponding Exxx values where possible. An example of this is in Net::Ping::tcp_connect(), which does the following to fetch a socket-level error code: unpack("i", getsockopt($self->{"fh"}, SOL_SOCKET, SO_ERROR)) and assigns the result (a WSAExxx value such as 10061) to $! and then goes wrong in the subsequent test (in ping_tcp()) for $! == ECONNREFUSED (which is now 107 rather than 10061 if perl is built with VC10 or higher). To avoid this we now intercept assignment to $! and convert any WSAExxx values to Exxx values first. This causes a minor oddity in that this: perl -le "$! = 10061; print 0+$!" will now output 107 (for VC10+ perls) but this is surely preferable to the alternative breakage described above.
* Fix a problem with mod_perl on Windows using VS2010+.Steve Hay2013-09-161-8/+132
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The problem is caused by the following two commits, which sought to deal with new Exxx values (with values >= 100) in errno.h which Microsoft added in VS2010: http://perl5.git.perl.org/perl.git/commit/b59e75b34cef3fedd214c9b6ee744146cf8b3308 http://perl5.git.perl.org/perl.git/commit/912c63ed00375338703043928cac3c740d00cc9d The former commit was mostly a patch to Errno and POSIX, together with some other cleaning up in win32/win32.h and win32/include/sys/socket.h; the latter commit was a fixup to win32/include/sys/socket.h which restored (more aggressively) the ENOTSOCK->WSAENOTSOCK redefinition and added similar redefinitions for ECONNABORTED, ECONNRESET and EAFNOSUPPORT. It is the latter commit which causes this little program to output ECONNABORTED=10053 rather than ECONNABORTED=106 as it ought to do in VC10 (and higher) builds of perl: #include <windows.h> #include "EXTERN.h" #include "perl.h" #include "XSUB.h" void main(void) { printf("ECONNABORTED=%d\n", ECONNABORTED); } That change is now causing problems with mod_perl, in which the (Perl level) APR::Status::is_ECONNABORTED() and the (C level) APR_STATUS_IS_ECONNABORTED() which it calls are failing to recognize an aborted connection (indicated by error code ECONNABORTED set by Apache httpd.exe). The APR_STATUS_IS_ECONNABORTED() macro is picked up by mod_perl from APR's apr_errno.h: #define APR_STATUS_IS_ECONNABORTED(s) ((s) == APR_ECONNABORTED \ || (s) == APR_OS_START_SYSERR + WSAECONNABORTED) where #ifdef ECONNABORTED #define APR_ECONNABORTED ECONNABORTED #else #define APR_ECONNABORTED (APR_OS_START_CANONERR + 18) #endif When this is compiled into httpd.exe ECONNABORTED is 106 (from errno.h) and APR_STATUS_IS_ECONNABORTED(s) amounts to #define APR_STATUS_IS_ECONNABORTED(s) ((s) == 106 || (s) == 730053) but when compiled into APR/Status.dll ECONNABORTED is 10053 (redefined to WSAECONNABORTED as above) so APR_STATUS_IS_ECONNABORTED(s) then amounts to #define APR_STATUS_IS_ECONNABORTED(s) ((s) == 10053 || (s) == 730053) which doesn't pick up an error code of 106 coming from httpd.exe. This could be worked around in mod_perl by redefining ECONNABORTED and the other three back to their original errno.h values to match what httpd.exe is using, but that might just cause problems in the other direction, with those values no longer matching the values which perl.exe is using. Moreoever, this problem could affect other XS interfaces (not just mod_perl), so it really needs to be fixed in perl. This commit implements the alternative solution mentioned the commit message for the first commit cited above. (As noted in that previous commit message, this solution equally has potential problems, missing out on the advantages of the original solution implemented, namely, better backwards compatibility with other perl code having hard-coded numeric error codes, but this will be unavoidable if we want to get to a sane state.) Note that changing the $! values is an incompatible change, so should probably not be done for 5.18.x. That's unfortunate for mod_perl (and anything else similarly affected), but that will just have to either live with the breakage (which was introduced in 5.14.0) until 5.20.0 or else try the workaround mentioned above for 5.14.x, 5.16.x and 5.18.x. The main change is to use a new function throughout win32/win32sck.c to convert WSAGetLastError() values into errno.h constants before assigning to errno. Every possible WSAExxx value (as documented by MSDN) is mapped to an Exxx value, although it is still possible for other WSAxxx values to get assigned to errno unchanged (but that has always been the case, and any non-existent Exxx values get mapped back to WSAExxx values anyway...). We must then ensure that all of those Exxx values are defined, which is now done (in the new file, win32/include/sys/errno2.h) in a friendlier manner, being careful not to redefine any (specifically the new ones in VC++ 2010 and above) which already exist. The rest are defined as the WSAExxx values, as mentioned above. Finally, we need the Errno module to know about these values, which is done by having it include that same new header file to ensure that it gets the same definitions, rather than having to play its own games. The new header is also used in POSIX, which similarly wants definitions of as many as possible of its hard-coded list of Exxx values.
* Update the Win32 miniperl conditional compilation, for the htonl etc changes.Nicholas Clark2013-05-201-14/+6
| | | | | | | | | As of commit 19253ae62cd13079 (Oct 2012), miniperl on Win32 avoids using Winsock. The win32_* wrappers for htonl etc had used the pre-processor macro MYSWAP to conditionally compile in the correct code. However, MYSWAP was defined as a side effect of using the htonl etc wrappers in util.c, which are no longer needed. Hence use the WIN32_NO_SOCKETS macro directly in win32sck.c for the correct conditional compilation.
* more dTHX optimizations in /win32/*Daniel Dragan2012-12-051-2/+4
| | | | | | | | | | In some places, where there is a higher risk of a NULL my_perl happening at an unknown point in the future IMO new scopes were created. In other places dTHXa(NULL) and aTHXa were used to avoid large whitespace changes. win32_rename and win32_getenv I determined would have no benefit from changing them. More context passing was added to static funcs called by win32_kill and win32_waitpid removing the need to move the dTHXs in the 2 funcs.
* remove unused dTHXes in /win32/*Daniel Dragan2012-11-081-1/+0
| | | | | | Remove dTHXes in win32 perl funcs where they were not used, or could be replaced with nocontext croaks/warns. Since Perl_get_context is a function it is not optimized away by the compiler.
* create aTHXa, some unused dTHXs removed in /win32/*Daniel Dragan2012-11-081-1/+0
| | | | | | | | | dTHXes that were unused, or because Newx/Safefree were the only things called were removed. In some places the dTHX turned into dTHXa and aTHXa so the context is not fetched until it is actually used (locality/frees a C stack slot or frees a non-volatile register). Also see http://www.nntp.perl.org/group/perl.perl5.porters/2012/10/msg194414.html and http://www.nntp.perl.org/group/perl.perl5.porters/2012/10/msg194861.html
* "func not implemented" croaks optimizations in /win32/*Daniel Dragan2012-11-081-26/+13
| | | | | | | | | This commit removes a number of "* not implemented" strings from the image. A win32_croak_not_implemented wrapper is created to reduce machine code by not putting the format string on the C stack many times. embed.fnc was used to declare win32_croak_not_implemented for proper cross compiler support of noreturn (noreturn on GCC and VC ok). Tailcalling and noreturn optimizations of the C compiler are heavily used in this commit.
* Win32 miniperl: delay loading for Winsock, and then remove itDaniel Dragan2012-10-311-0/+19
| | | | | | | | | | | | | | | | | | | Slim down the image and speed up start up time for Win32 miniperl by removing Winsock. Also if the build process on Win32 in the future requires sockets, commenting one line in win32.h will turn sockets back on for miniperl, but this time with delay loading on VC Perl. The only casulty of no sockets for Win32 miniperl was figuring out the computer's name in win32/config_sh.PL. A workaround by using an ENV var was implemented. The purpose of this commit is to speed up the build process of Perl. As said in the comment in win32.h, the WIN32_NO_SOCKETS macro is incomplete in implementation. It is only removed winsock from being linked in in miniperl, not full Perl. PERL_IMPLICIT_SYS (specifically PerlSock in win32/perlhost.h) and makedef.pl's hard coded list of win32_* function exports cause winsock to still be linked in with even with WIN32_NO_SOCKETS on full perl. Both PERL_IMPLICIT_SYS (win32/perlhost.h) and makedef.pl would require changes to remove winsock from being linked in on full perl in the future.
* Remove option to build without USE_SOCKETS_AS_HANDLES on WindowsSteve Hay2012-09-281-61/+3
| | | | | | | | | The option is always defined by default and can't be disabled from the makefiles. Manually disabling it causes several tests to fail, which nobody has reported, so we presume nobody does this. The non-default configuration is believed to be historical cruft with no value now, and has clearly bitrotted in recent years (hence the test failures), so remove it to simplify the codebase slightly.
* The Borland Chainsaw MassacreSteve Hay2011-09-101-2/+0
| | | | | Remove support for the Borland C++ compiler on Win32, as agreed here: http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2011-09/msg00034.html
* Get rid of PERL_MSVCRT_READFIXJan Dubois2010-12-061-6/+0
| | | | | | | The code works around a bug in very old versions of MSVCRT.dll. The issue has been fixed a long time ago by Microsoft, so anyone who has installed a Windows Service Pack in the last 10 years or so won't be affected by the problem.
* Windows 95 Chainsaw MassacreJan Dubois2010-12-021-58/+2
| | | | | Remove all supporting code for Windows 9x and Windows NT. The minimum supported version is Windows 2000 now.
* The winsock select() implementation doesn't support all empty 'fd_set's.Jan Dubois2009-10-131-11/+16
| | | | | | | | | | | The code already contained a workaround for the special case select(undef, undef, undef, $sleep); but didn't handle the case when actual bit vectors were passed in that didn't have any bits set. Fixes http://rt.perl.org/rt3/Public/Bug/Display.html?id=54544
* Remove broken links for hip communications inc.Leon Brocard2009-09-131-1/+1
|
* select() generates "Invalid parameter" messages on Windows Vista.Jan Dubois2009-05-131-11/+24
| | | | | | | | | | | | | | | | | | | | | The messages are generated by OutputDebugString() so are only visible inside a debugger, or other debugger viewer applications. The messages are generated by the _get_osfhandle() calls with invalid file ids. This change makes sure it is only called when the corresponding bit in the select() arguments has been set. Related bug reports: http://bugs.activestate.com/show_bug.cgi?id=82995 http://bugs.slimdevices.com/show_bug.cgi?id=11896 http://getpopfile.org/ticket/45 Even with this patch there are still residual "Invalid parameter" messages in the debug output while building Perl itself. They are generated by miniperl in the win32_fclose() function, again calling _get_osfhandle() with an invalid handle. The same messages can be observed when Perl is built *without* USE_PERLIO (just like miniperl).
* [perl #46309] Buffer overflow in win32_select() (PATCH included) Risto Kankkunen2008-06-171-22/+8
| | | | | | From: Risto Kankkunen (via RT) <perlbug-followup@perl.org> Message-ID: <rt-3.6.HEAD-10743-1192009453-1788.46309-75-0@perl.org> p4raw-id: //depot/perl@34067
* [PATCH] Remove dead code from win32/win32sck.cJan Dubois2007-06-261-17/+0
| | | | | | | | | | | | From: "Jan Dubois" <jand@activestate.com> Date: Mon, 25 Jun 2007 17:13:04 -0700 Message-ID: <02bb01c7b786$c42099c0$4c61cd40$@com> Subject: RE: [PATCH] Remove dead code from win32/win32sck.c From: "Jan Dubois" <jand@activestate.com> Date: Mon, 25 Jun 2007 17:26:15 -0700 Message-ID: <02c801c7b788$9bf7ebe0$d3e7c3a0$@com> p4raw-id: //depot/perl@31469
* Re: Net::SMTP can't send large messages with bleadperlYves Orton2007-06-201-3/+7
| | | | | Message-ID: <9b18b3110706200622o344c417apbd50468c6e5eb533@mail.gmail.com> p4raw-id: //depot/perl@31426
* Re: janitorial work ? [patch]Jim Cromie2005-07-081-2/+2
| | | | | | | | Message-ID: <42CC3CE9.5050606@divsol.com> (reverted all dual-lived modules since they must work with older perls too so must wait for a new Devel::PPPort) p4raw-id: //depot/perl@25101
* Fix bug #33664: allow for transport providers with protocol == 0Steve Hay2005-04-181-1/+2
| | | | | | (This indicates that any protocol may be used, so don't bother checking that the requested protocol matches in this case.) p4raw-id: //depot/perl@24242
* A couple more Win32 compilation clean-upsSteve Hay2005-03-301-3/+3
| | | p4raw-id: //depot/perl@24099
* Implement new environment variable to allow the use of non-IFSSteve Hay2004-09-061-0/+5
| | | | | | | | | compatible LSP's on Windows to allow Perl to work in conjunction with a firewall such as McAfee Guardian. Bug report and possible solutions by Ken Fox <kfox@ford.com>; further assistance by Artiom Morozov <artiom@phreaker.net>. p4raw-id: //depot/perl@23275
* Fix [perl #24269] socket() call uses non-IFS providersSteve Hay2004-08-061-19/+65
| | | | | | | | causing subsequent print/read to hang or misbehave Patch supplied by Artiom Morozov <artiom@phreaker.net> in the bug report at http://rt.perl.org/rt3/index.html?q=24269 p4raw-id: //depot/perl@23200
* 5.8.1 / bcc55 / win32 / Enable PerlIO and/ or USE_LARGE_FILESNigel Sandever2003-12-281-0/+8
| | | | | | | From: "Nigel Sandever" <njsandever@hotmail.com> Message-ID: <Law9-F94BdsnvUFcxT500000ea5@hotmail.com> Date: Thu, 25 Sep 2003 21:49:07 +0000 p4raw-id: //depot/perl@21989
* missing init in change#19533Gurusamy Sarathy2003-05-171-1/+1
| | | | | p4raw-link: @19533 on //depot/perl: 1c8780751e85c3ece441fc8ecdff2f1dc99f9906 p4raw-id: //depot/perl@19537
* avoid select() on windows destroying errno (used to typicallyGurusamy Sarathy2003-05-171-1/+4
| | | | | always sets it to EINVAL due to the way it maps the FD_SETs) p4raw-id: //depot/perl@19533
* Happy chainsaw stories; The removal of the 5005 threadsH.Merijn Brand2002-10-191-3/+3
| | | | | Still imcomplete. Configure will follow p4raw-id: //depot/perl@18030
* fixes for all the warnings reported by Visual C (most of thisGurusamy Sarathy2002-04-211-1/+1
| | | | | | change is from change#12026) p4raw-link: @12026 on //depot/maint-5.6/perl: ff42b73b40f5a895aef4bed81c794f468e0609bc p4raw-id: //depot/perl@16048
* Windows 64-bit support:Gurusamy Sarathy2002-04-211-3/+12
| | | | | | | | | | | | | | | | | | | | | | | | | | | * support for building it in the regular makefiles * large files support via the _*i64() functions (this should be portable to the 32-bit universe too, but quite untested and and binary-incompatible, therefore not enabled there) * three additional test failures in addition to the t/end.t one (see README.win32) * sprintf() on Windows gets %I{32,64,}[xoud] format that parallel the ones available from the CRT (needed because Perl uses the UVxf macros in both sprintf() *and* in sv_catpvf() et al.) * add a few 64-bit notes to README.win32 The following general problems were also fixed: * s/struct stat/Stat_t/g * Data::Dumper had some naughty 'long' typecasts * Errno_pm.PL didn't work safe when winsock.h was not in the same directory as errno.h * various tell/seek things were incorrectly prototyped * squelch ugly looking noise when running tests * Embed.t wasn't linking in all the libraries * perl57.dll is now perl58.dll (anticipating 5.8.0-RC1) * re-enable all the disabled warnings (additional fixes may be needed for the warnings uncovered by this) p4raw-id: //depot/perl@16033
* remove deprecated PERL_OBJECT cruft, it has long since stoppedGurusamy Sarathy2001-08-311-23/+18
| | | | | working in 5.7.x p4raw-id: //depot/perl@11803
* Changes USE_THREADS to USE_5005THREADS in the entire source.Artur Bergman2001-08-271-3/+3
| | | | | | Thanks to H. Merijn Brand for the patch. Some of the comments and or guards might be removable in perl.h now. p4raw-id: //depot/perl@11758
* Borland C++ for Win32 fixes; perl@9359 (also perl@9424)Vadim Konovalov2001-03-291-0/+4
| | | | | Message-ID: <001c01c0b7d1$463dd880$5742983e@vad> p4raw-id: //depot/perl@9427
* fix open(FOO, ">&MYSOCK") failure under Windows 9x (problem isGurusamy Sarathy2000-12-051-0/+35
| | | | | | due to the notorious GetFileType() bug in Windows 9x, which fstat() tickles) p4raw-id: //depot/perl@7986
* Configure GCC/Win32 build -DuseperlioNick Ing-Simmons2000-11-191-0/+1
| | | | | | | Fix a couple of gross issues - double-include of ../deb.o in re.dll - win32sck.c needs PerlIO and FILE p4raw-id: //depot/perlio@7752
* Redo #7679 with LFs instead of CRLFs.Jarkko Hietaniemi2000-11-141-37/+37
| | | p4raw-id: //depot/perl@7680
* Get PerlIO building on Win32Benjamin Stuhl2000-11-141-2/+37
| | | | | Message-ID: <20001113230808.18659.qmail@web6305.mail.yahoo.com> p4raw-id: //depot/perl@7679
* tweak for change#7173Gurusamy Sarathy2000-10-091-0/+2
| | | | | p4raw-link: @7173 on //depot/perl: a10b7b7eee64efea010bfdba91243503341ba68d p4raw-id: //depot/perl@7181
* on Windows, avoid potential exception (could happen if MSVCRT isn'tGurusamy Sarathy2000-10-091-0/+1
| | | | | being used) when closing a socket handle p4raw-id: //depot/perl@7173
* change#6328 could make close(SOCKET) return false on windowsGurusamy Sarathy2000-08-161-8/+17
| | | | | | | when it shouldn't p4raw-link: @6328 on //depot/perl: 4e94524934c1af4124b2888d9716e5304ee50ad9 p4raw-id: //depot/perl@6657
* windows build tweaks (op/sprintf.t still fails tests 120-121, 149)Gurusamy Sarathy2000-07-111-1/+1
| | | p4raw-id: //depot/perl@6375
* accept() leaks memory on windows due to incorrect ordering ofGurusamy Sarathy2000-07-101-4/+5
| | | | | closesocket() and fclose() calls p4raw-id: //depot/perl@6328
* winsock options weren't being set in all threads under ithreadsGurusamy Sarathy2000-07-101-4/+4
| | | | | (caused send()s from second and subsequent threads to fail) p4raw-id: //depot/perl@6327
* winsock cleanup never done on Windows (leads to handle leaks)Gurusamy Sarathy2000-07-051-6/+7
| | | p4raw-id: //depot/perl@6317
* win32 internal data must be interpreter-localGurusamy Sarathy1999-11-081-22/+10
| | | p4raw-id: //depot/perl@4536
* yet more cleanups of the PERL_OBJECT, MULTIPLICITY and USE_THREADSGurusamy Sarathy1999-07-121-17/+17
| | | | | | | | | | | | | | | | builds; passing the implicit context is unified among the three flavors; PERL_IMPLICIT_CONTEXT is auto-enabled under all three flavors (see the top of perl.h) for testing; all varargs functions foo() have a va_list-taking variant vfoo() for generating the context-free versions; the PERL_OBJECT build should now be hyper-compatible with CPAN extensions (C++ is totally out of the picture) result has only been tested on Windows TODO: write docs on the THX rationale and idiomatic usage of the Perl API p4raw-id: //depot/perl@3667