From: Gurusamy Sarathy Date: Wed, 22 Jul 1998 21:00:44 +0000 (+0000) Subject: Update perldelta and Changes; refresh perltoc; newer perlembed.pod X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=9cde0e7fb9816f759feaabc0f640403a7cdbc5c6;p=p5sagit%2Fp5-mst-13.2.git Update perldelta and Changes; refresh perltoc; newer perlembed.pod from Jon Orwant ; update guts documentation to reflect PL_* changes; is this *it* for 5.005? p4raw-id: //depot/perl@1646 --- diff --git a/Changes b/Changes index 3d92c44..1d510a2 100644 --- a/Changes +++ b/Changes @@ -78,6 +78,61 @@ Version 5.005 Production release ------------- ____________________________________________________________________________ +[ 1645] By: gsar on 1998/07/22 19:37:41 + Log: don't use qualify() in class methods + From: Albert Dvornik + Date: 22 Jul 1998 15:14:46 EDT + Message-Id: + Subject: [PATCH 5.005-MAYBE] Bug in IO::Handle->input_record_separator + Branch: perl + ! ext/IO/lib/IO/Handle.pm +____________________________________________________________________________ +[ 1644] By: gsar on 1998/07/22 18:13:31 + Log: newer perlembed.pod + Branch: perl + ! pod/perlembed.pod +____________________________________________________________________________ +[ 1643] By: gsar on 1998/07/22 18:03:42 + Log: From: Andy Dougherty + Date: Wed, 22 Jul 1998 13:42:20 EDT + Message-Id: + Subject: Re: 5.005 - a sneak preview + Branch: perl + ! Porting/pumpkin.pod +____________________________________________________________________________ +[ 1642] By: gsar on 1998/07/22 17:58:42 + Log: add perlmodinstall, regen perltoc + Branch: perl + + pod/perlmodinstall.pod + ! MANIFEST pod/Makefile pod/buildtoc pod/perl.pod + ! pod/perltoc.pod win32/pod.mak +____________________________________________________________________________ +[ 1641] By: gsar on 1998/07/22 17:11:55 + Log: support optional crypt() with PERL_OBJECT + From: "Douglas Lankshear" + Date: Wed, 22 Jul 1998 08:21:10 PDT + Message-Id: <000701bdb584$5b57c070$a32fa8c0@tau.Active> + Subject: [PATCH 5.005 maybe] for crypt with PERL_OBJECT + Branch: perl + ! iperlsys.h pp.c win32/Makefile win32/makefile.mk + ! win32/perlhost.h win32/win32.c win32/win32iop.h +____________________________________________________________________________ +[ 1640] By: gsar on 1998/07/22 17:09:11 + Log: win32 tweaks + Date: Wed, 22 Jul 1998 07:09:09 PDT + Message-Id: <000001bdb57a$4bc9dd00$a32fa8c0@tau.Active> + From: "Douglas Lankshear" + Branch: perl + ! win32/Makefile win32/makefile.mk win32/win32.h +____________________________________________________________________________ +[ 1639] By: gsar on 1998/07/22 17:00:30 + Log: From: d-lewart@uiuc.edu (Daniel S. Lewart) + Date: Wed, 22 Jul 1998 06:20:08 CDT + Message-Id: <199807221120.GAA07962@staff2.cso.uiuc.edu> + Subject: [PATCH] lib/Sys/Syslog.pm doc + Branch: perl + ! Changes lib/Sys/Syslog.pm +____________________________________________________________________________ [ 1638] By: gsar on 1998/07/22 09:12:26 Log: up patchlevel etc (only doc patching from now on, testing in progress) Branch: perl diff --git a/README.win32 b/README.win32 index 3ba6d2e..6d9b015 100644 --- a/README.win32 +++ b/README.win32 @@ -147,12 +147,17 @@ ActiveState Tool Corp.) PERL_OBJECT uses C++, and the binaries are therefore incompatible with the regular C build. However, the PERL_OBJECT build does provide something called the C-API, for linking it with extensions that won't compile under PERL_OBJECT. PERL_OBJECT -cannot be enabled when using GCC or EGCS, yet. +is not yet supported under GCC or EGCS. WARNING: Binaries built with +PERL_OBJECT enabled are B compatible with binaries built without. +Perl installs PERL_OBJECT binaries under a distinct architecture name, +so they B coexist, though. Beginning with version 5.005, there is experimental support for building a perl interpreter that is capable of native threading. Binaries built with thread support enabled are also incompatible with the vanilla C -build. +build. WARNING: Binaries built with threads enabled are B compatible +with binaries built without. Perl installs threads enabled binaries under +a distinct architecture name, so they B coexist, though. At the present time, you cannot enable both threading and PERL_OBJECT. You can get only one of them in a Perl interpreter. @@ -382,6 +387,59 @@ it looks like the extension building support is at fault, report that with full details of how the build failed using the perlbug utility. +=item Command-line Wildcard Expansion + +The default command shells on DOS descendant operating systems (such +as they are) usually do not expand wildcard arguments supplied to +programs. They consider it the application's job to handle that. +This is commonly achieved by linking the application (in our case, +perl) with startup code that the C runtime libraries usually provide. +However, doing that results in incompatible perl versions (since the +behavior of the argv expansion code differs depending on the +compiler, and it is even buggy on some compilers). Besides, it may +be a source of frustration if you use such a perl binary with an +alternate shell that *does* expand wildcards. + +Instead, the following solution works rather well. The nice things +about it: 1) you can start using it right away 2) it is more powerful, +because it will do the right thing with a pattern like */*/*.c +3) you can decide whether you do/don't want to use it 4) you can +extend the method to add any customizations (or even entirely +different kinds of wildcard expansion). + + C:\> copy con c:\perl\lib\Wild.pm + # Wild.pm - emulate shell @ARGV expansion on shells that don't + use File::DosGlob; + @ARGV = map { + my @g = File::DosGlob::glob($_) if /[*?]/; + @g ? @g : $_; + } @ARGV; + 1; + ^Z + C:\> set PERL5OPT=-MWild + C:\> perl -le "for (@ARGV) { print }" */*/perl*.c + p4view/perl/perl.c + p4view/perl/perlio.c + p4view/perl/perly.c + perl5.005/win32/perlglob.c + perl5.005/win32/perllib.c + perl5.005/win32/perlglob.c + perl5.005/win32/perllib.c + perl5.005/win32/perlglob.c + perl5.005/win32/perllib.c + +Note there are two distinct steps there: 1) You'll have to create +Wild.pm and put it in your perl lib directory. 2) You'll need to +set the PERL5OPT environment variable. If you want argv expansion +to be the default, just set PERL5OPT in your default startup +environment. + +If you are using the Visual C compiler, you can get the C runtime's +command line wildcard expansion built into perl binary. The resulting +binary will always expand unquoted command lines, which may not be +what you want if you use a shell that does that for you. The expansion +done is also somewhat less powerful than the approach suggested above. + =item Win32 Specific Extensions A number of extensions specific to the Win32 platform are available diff --git a/patchlevel.h b/patchlevel.h index 21d19a8..0f4e051 100644 --- a/patchlevel.h +++ b/patchlevel.h @@ -39,7 +39,6 @@ */ static char *local_patches[] = { NULL - ,"MAYBE - 5.005, but not just yet" ,NULL }; diff --git a/pod/perlcall.pod b/pod/perlcall.pod index ac60007..7c94d37 100644 --- a/pod/perlcall.pod +++ b/pod/perlcall.pod @@ -969,9 +969,9 @@ and some C to call it SPAGAIN ; /* Check the eval first */ - if (SvTRUE(GvSV(errgv))) + if (SvTRUE(ERRSV)) { - printf ("Uh oh - %s\n", SvPV(GvSV(errgv), na)) ; + printf ("Uh oh - %s\n", SvPV(ERRSV, PL_na)) ; POPs ; } else @@ -1011,9 +1011,9 @@ I. The code - if (SvTRUE(GvSV(errgv))) + if (SvTRUE(ERRSV)) { - printf ("Uh oh - %s\n", SvPV(GvSV(errgv), na)) ; + printf ("Uh oh - %s\n", SvPV(ERRSV, PL_na)) ; POPs ; } @@ -1021,14 +1021,14 @@ is the direct equivalent of this bit of Perl print "Uh oh - $@\n" if $@ ; -C is a perl global of type C that points to the -symbol table entry containing the error. C therefore +C is a perl global of type C that points to the +symbol table entry containing the error. C therefore refers to the C equivalent of C<$@>. =item 3. Note that the stack is popped using C in the block where -C is true. This is necessary because whenever a +C is true. This is necessary because whenever a I function invoked with G_EVAL|G_SCALAR returns an error, the top of the stack holds the value I. Because we want the program to continue after detecting this error, it is essential that @@ -1877,7 +1877,7 @@ of values> recoded to use C instead of C. SPAGAIN ; SP -= count ; - ax = (SP - stack_base) + 1 ; + ax = (SP - PL_stack_base) + 1 ; if (count != 2) croak("Big trouble\n") ; @@ -1907,7 +1907,7 @@ The code SPAGAIN ; SP -= count ; - ax = (SP - stack_base) + 1 ; + ax = (SP - PL_stack_base) + 1 ; sets the stack up so that we can use the C macro. diff --git a/pod/perldelta.pod b/pod/perldelta.pod index 0cbba50..7a371fb 100644 --- a/pod/perldelta.pod +++ b/pod/perldelta.pod @@ -6,11 +6,19 @@ perldelta - what's new for perl5.005 This document describes differences between the 5.004 release and this one. -[XXX this needs more verbose summaries of the sub topics, instead of just -the "See foo." Scheduled for a second iteration. GSAR] - =head1 About the new versioning system +Perl is now developed on two tracks: a maintenance track that makes +small, safe updates to released production versions with emphasis on +compatibility; and a development track that pursues more aggressive +evolution. Maintenance releases (which should be considered production +quality) have subversion numbers that run from C<1> to C<49>, and +development releases (which should be considered "alpha" quality) run +from C<50> to C<99>. + +Perl 5.005 is the combined product of the new dual-track development +scheme. + =head1 Incompatible Changes =head2 WARNING: This version is not binary compatible with Perl 5.004. @@ -31,31 +39,80 @@ discussion of the changes in order to adapt them to your system. =head2 Perl Source Compatibility When none of the experimental features are enabled, there should be -no user-visible Perl source compatibility issue. +very few user-visible Perl source compatibility issues. If threads are enabled, then some caveats apply. C<@_> and C<$_> become lexical variables. The effect of this should be largely transparent to the user, but there are some boundary conditions under which user will -need to be aware of the issues. [XXX Add e.g. here.] +need to be aware of the issues. For example, C results in +a "Can't localize lexical variable @_ ..." message. This may be enabled +in a future version. Some new keywords have been introduced. These are generally expected to -have very little impact on compatibility. See L keyword>, -L keyword>, and L operator>. +have very little impact on compatibility. See L keyword>, +L keyword>, and L operator>. Certain barewords are now reserved. Use of these will provoke a warning if you have asked for them with the C<-w> switch. -See L is now a reserved word>. +See L is now a reserved word>. =head2 C Source Compatibility +There have been a large number of changes in the internals to support +the new features in this release. + +=over 4 + =item Core sources now require ANSI C compiler +An ANSI C compiler is now B to build perl. See F. + +=item All Perl global variables must now be referenced with an explicit prefix + +All Perl global variables that are visible for use by extensions now +have a C prefix. New extensions should C refer to perl globals +by their unqualified names. To preserve sanity, we provide limited +backward compatibility for globals that are being widely used like +C and C (which should now be written as C, +C etc.) + +If you find that your XS extension does not compile anymore because a +perl global is not visible, try adding a C prefix to the global +and rebuild. + +It is strongly recommended that all functions in the Perl API that don't +begin with C be referenced with a C prefix. The bare function +names without the C prefix are supported with macros, but this +support may cease in a future release. + +See L. + =item Enabling threads has source compatibility issues +Perl built with threading enabled requires extensions to use the new +C macro to initialize the handle to access per-thread data. +If you see a compiler error that talks about the variable C not +being declared (when building a module that has XS code), you need +to add C at the beginning of the block that elicited the error. + +The API function C should be used instead of +directly accessing perl globals as C. The API call is +backward compatible with existing perls and provides source compatibility +with threading is enabled. + +See L. + +=back + =head2 Binary Compatibility This version is NOT binary compatible with older versions. All extensions -will need to be recompiled. +will need to be recompiled. Further binaries built with threads enabled +are incompatible with binaries built without. This should largely be +transparent to the user, as all binary incompatible configurations have +their own unique architecture name, and extension binaries get installed at +unique locations. This allows coexistence of several configurations in +the same directory hierarchy. See F. =head2 Security fixes may affect compatibility @@ -78,24 +135,25 @@ features make them less often a problem. See L. Perl has a new Social Contract for contributors. See F. The license included in much of the Perl documentation has changed. -[XXX See where?] +See L and the individual perl man pages listed therein. =head1 Core Changes =head2 Threads -WARNING: Threading is considered an experimental feature. Details of the +WARNING: Threading is considered an B feature. Details of the implementation may change without notice. There are known limitations -and and some bugs. +and some bugs. These are expected to be fixed in future versions. See L. =head2 Compiler -WARNING: The Compiler and related tools are considered experimental. +WARNING: The Compiler and related tools are considered B. Features may change without notice, and there are known limitations -and bugs. +and bugs. Since the compiler is fully external to perl, the default +configuration will build and install it. The Compiler produces three different types of transformations of a perl program. The C backend generates C code that captures perl's state @@ -125,10 +183,87 @@ at a glance. C is a simple frontend for compiling perl. -See C. +See C, L, and the respective compiler modules. =head2 Regular Expressions +Perl's regular expression engine has been seriously overhauled, and +many new constructs are supported. Several bugs have been fixed. + +Here is an itemized summary: + +=over 4 + +=item Many new and improved optimizations + +Changes in the RE engine: + + Unneeded nodes removed; + Substrings merged together; + New types of nodes to process (SUBEXPR)* and similar expressions + quickly, used if the SUBEXPR has no side effects and matches + strings of the same length; + better optimizations by lookup for constant substrings; + Better search for constants substrings anchored by $ ; + +Changes in Perl code using RE engine: + + more optimizations to s/longer/short/; + study() was not working; + /blah/ may be optimized to an analogue of index() if $& $` $' not seen; + Unneeded copying of matched-against string removed; + Only matched part of the string is copying if $` $' were not seen; + +=item Many bug fixes + +Note that only the major bug fixes are listed here. See F for others. + + Backtracking might not restore start of $3. + No feedback if max count for * or + on "complex" subexpression + was reached, similarly (but at compile time) for {3,34567} + Primitive restrictions on max count introduced to decrease a + possibility of a segfault; + (ZERO-LENGTH)* could segfault; + (ZERO-LENGTH)* was prohibited; + Long RE were not allowed; + /RE/g could skip matches at the same position after a + zero-length match; + +=item New regular expression constructs + +The following new syntax elements are supported: + + (?<=RE) + (?RE) + \z + +=item New operator for precompiled regular expressions + +See L operator>. + +=item Other improvements + + better debugging output (possibly with colors), even from non-debugging Perl; + RE engine code now looks like C, not like assembler; + behaviour of RE modifiable by `use re' directive; + Improved documentation; + Test suite significantly extended; + Syntax [:^upper:] etc., reserved inside character classes; + +=item Incompatible changes + + (?i) localized inside enclosing group; + $( is not interpolated into RE any more; + /RE/g may match at the same position (with non-zero length) + after a zero-length match (bug fix). + +=back + See L and L. =head2 Improved malloc() @@ -137,15 +272,24 @@ See banner at the beginning of C for details. =head2 Quicksort is internally implemented +Perl now contains its own highly optimized qsort() routine. The new qsort() +is resistant to inconsistent comparison functions, so Perl's C will +not provoke coredumps any more when given poorly written sort subroutines. +(Some C library Cs that were being used before used to have this +problem.) In our testing, the new C required the minimal number +of pair-wise compares on average, among all known C implementations. + See C. =head2 Reliable signals -Two kinds. +Perl's signal handling is susceptible to random crashes, because signals +arrive asynchronously, and the Perl runtime is not reentrant at arbitrary +times. -Via C. - -Via switched runtime op loop. [XXX Not yet available.] +However, one experimental implementation of reliable signals is available +when threads are enabled. See C. Also see F for +how to build a Perl capable of threads. =head2 Reliable stack pointers @@ -186,11 +330,18 @@ not try to allocate a 1000000-size list anymore. =head2 C can be used as implicitly quoted package name -[XXX See what?] +Barewords caused unintuitive behavior when a subroutine with the same +name as a package happened to be defined. Thus, C, +use the result of the call to C instead of C being treated +as a literal. The recommended way to write barewords in the indirect +object slot is C. Note that the method C is +called with a first argument of C, not C when you do that. =head2 C tests existence of a package -[XXX See what?] +It was impossible to test for the existence of a package without +actually creating it before. Now C can be +used to test if the C namespace has been created. =head2 Better locale support @@ -216,8 +367,7 @@ See L. C now accepts a reference value, and C<$@> gets set to that value in exception traps. This makes it possible to propagate -exception objects. See L. [XXX there's nothing -about this in perlfunc/eval yet.] +exception objects. This is an undocumented B feature. =head2 Re-blessing in DESTROY() supported for chaining DESTROY() methods @@ -233,8 +383,6 @@ C subs are like C and C, but they get run just before the perl runtime begins execution. e.g., the Perl Compiler makes use of C blocks to initialize and resolve pointers to XSUBs. -[XXX Needs to be documented in perlsub or perlmod.] - =head2 New C keyword The C keyword is the fundamental synchronization primitive @@ -253,6 +401,9 @@ other regular expressions. See L. =head2 C is now a reserved word +Calling a subroutine with the name C will now provoke a warning when +using the C<-w> switch. + =head2 Tied arrays are now fully supported See L. @@ -319,12 +470,11 @@ MPE/iX is now supported. See L. Win32 support has been vastly enhanced. Support for Perl Object, a C++ encapsulation of Perl. GCC and EGCS are now supported on Win32. -[XXX Perl Object needs a big explanation elsewhere, and a pointer to -that location here.] +See F, aka L. VMS configuration system has been rewritten. See L. -OpenBSD better supported. [XXX what others?] +The hints files for most Unix platforms have seen incremental improvements. =head1 Modules and Pragmata @@ -334,7 +484,7 @@ OpenBSD better supported. [XXX what others?] =item B -Perl compiler and tools. See [XXX what?]. +Perl compiler and tools. See L. =item Data::Dumper @@ -427,7 +577,7 @@ subtle incompatibilities. =item CPAN -[XXX What?] +See and L. =item Cwd @@ -447,21 +597,20 @@ perlcc, a new experimental front end for the compiler is available. The crude GNU configure emulator is now called configure.gnu. -=head1 API Changes - -=head2 Incompatible Changes - -=head2 Deprecations, Extensions - -=head2 C++ Support - =head1 Documentation Changes Config.pm now has a glossary of variables. -Porting/patching.pod has detailed instructions on how to create and +F has detailed instructions on how to create and submit patches for perl. +L specifies guidelines on how to write portably. + +L describes how to fetch and install modules from C +sites. + +Some more Perl traps are documented now. See L. + =head1 New Diagnostics =over @@ -691,7 +840,6 @@ a B<-e> switch. Maybe your /tmp partition is full, or clobbered. (F) The create routine failed for some reason while trying to process a B<-e> switch. Maybe your /tmp partition is full, or clobbered. - =back =head1 BUGS @@ -719,4 +867,9 @@ The F and F files for copyright information. =head1 HISTORY +Written by Gurusamy Sarathy >, with many contributions +from The Perl Porters. + +Send omissions or corrections to >. + =cut diff --git a/pod/perlembed.pod b/pod/perlembed.pod index 2aadeff..0323fd1 100644 --- a/pod/perlembed.pod +++ b/pod/perlembed.pod @@ -301,7 +301,7 @@ the first, a C from the second, and a C from the third. /** Treat $a as a string **/ perl_eval_pv("$a = 'rekcaH lreP rehtonA tsuJ'; $a = reverse($a);", TRUE); - printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), na)); + printf("a = %s\n", SvPV(perl_get_sv("a", FALSE), PL_na)); perl_destruct(my_perl); perl_free(my_perl); @@ -324,7 +324,7 @@ from I instead. Example: ... SV *val = perl_eval_pv("reverse 'rekcaH lreP rehtonA tsuJ'", TRUE); - printf("%s\n", SvPV(val,na)); + printf("%s\n", SvPV(val,PL_na)); ... This way, we avoid namespace pollution by not creating global @@ -377,8 +377,8 @@ been wrapped here): retval = POPs; PUTBACK; - if (croak_on_error && SvTRUE(GvSV(errgv))) - croak(SvPVx(GvSV(errgv), na)); + if (croak_on_error && SvTRUE(ERRSV)) + croak(SvPVx(ERRSV, PL_na)); return retval; } @@ -395,7 +395,7 @@ been wrapped here): SV *command = NEWSV(1099, 0), *retval; sv_setpvf(command, "my $string = '%s'; $string =~ %s", - SvPV(string,na), pattern); + SvPV(string,PL_na), pattern); retval = my_perl_eval_sv(command, TRUE); SvREFCNT_dec(command); @@ -416,7 +416,7 @@ been wrapped here): SV *command = NEWSV(1099, 0), *retval; sv_setpvf(command, "$string = '%s'; ($string =~ %s)", - SvPV(*string,na), pattern); + SvPV(*string,PL_na), pattern); retval = my_perl_eval_sv(command, TRUE); SvREFCNT_dec(command); @@ -439,7 +439,7 @@ been wrapped here): I32 num_matches; sv_setpvf(command, "my $string = '%s'; @array = ($string =~ %s)", - SvPV(string,na), pattern); + SvPV(string,PL_na), pattern); my_perl_eval_sv(command, TRUE); SvREFCNT_dec(command); @@ -478,7 +478,7 @@ been wrapped here): printf("matches: m/(wi..)/g found %d matches...\n", num_matches); for (i = 0; i < num_matches; i++) - printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),na)); + printf("match: %s\n", SvPV(*av_fetch(match_list, i, FALSE),PL_na)); printf("\n"); /** Remove all vowels from text **/ @@ -486,7 +486,7 @@ been wrapped here): if (num_matches) { printf("substitute: s/[aeiou]//gi...%d substitutions made.\n", num_matches); - printf("Now text is: %s\n\n", SvPV(text,na)); + printf("Now text is: %s\n\n", SvPV(text,PL_na)); } /** Attempt a substitution **/ @@ -495,7 +495,7 @@ been wrapped here): } SvREFCNT_dec(text); - perl_destruct_level = 1; + PL_perl_destruct_level = 1; perl_destruct(my_perl); perl_free(my_perl); } @@ -744,12 +744,12 @@ with L whenever possible. G_DISCARD | G_EVAL, args); /* check $@ */ - if(SvTRUE(GvSV(errgv))) - fprintf(stderr, "eval error: %s\n", SvPV(GvSV(errgv),na)); + if(SvTRUE(ERRSV)) + fprintf(stderr, "eval error: %s\n", SvPV(ERRSV,PL_na)); } } - perl_destruct_level = 0; + PL_perl_destruct_level = 0; perl_destruct(perl); perl_free(perl); exit(exitstatus); @@ -787,16 +787,16 @@ release any resources associated with the interpreter. The program must take care to ensure that this takes place I the next interpreter is constructed. By default, the global variable -C is set to C<0>, since extra cleaning isn't +C is set to C<0>, since extra cleaning isn't needed when a program has only one interpreter. -Setting C to C<1> makes everything squeaky clean: +Setting C to C<1> makes everything squeaky clean: - perl_destruct_level = 1; + PL_perl_destruct_level = 1; while(1) { ... - /* reset global variables here with perl_destruct_level = 1 */ + /* reset global variables here with PL_perl_destruct_level = 1 */ perl_construct(my_perl); ... /* clean and reset _everything_ during perl_destruct */ @@ -812,7 +812,7 @@ and symbol tables are cleaned up, and global variables are reset. Now suppose we have more than one interpreter instance running at the same time. This is feasible, but only if you used the C<-DMULTIPLICITY> flag when building Perl. By default, that sets -C to C<1>. +C to C<1>. Let's give it a try: diff --git a/pod/perlguts.pod b/pod/perlguts.pod index c20e8b5..20a07d3 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -95,7 +95,7 @@ or string. In the C macro, the length of the string returned is placed into the variable C (this is a macro, so you do I use C<&len>). If you do not -care what the length of the data is, use the global variable C. Remember, +care what the length of the data is, use the global variable C. Remember, however, that Perl allows arbitrary strings of data that may both contain NULs and might not be terminated by a NUL. @@ -167,14 +167,14 @@ you can call: SvOK(SV*) -The scalar C value is stored in an SV instance called C. Its +The scalar C value is stored in an SV instance called C. Its address can be used whenever an C is needed. -There are also the two values C and C, which contain Boolean -TRUE and FALSE values, respectively. Like C, their addresses can +There are also the two values C and C, which contain Boolean +TRUE and FALSE values, respectively. Like C, their addresses can be used whenever an C is needed. -Do not be fooled into thinking that C<(SV *) 0> is the same as C<&sv_undef>. +Do not be fooled into thinking that C<(SV *) 0> is the same as C<&PL_sv_undef>. Take this code: SV* sv = (SV*) 0; @@ -186,7 +186,7 @@ Take this code: This code tries to return a new SV (which contains the value 42) if it should return a real value, or undef otherwise. Instead it has returned a NULL pointer which, somewhere down the line, will cause a segmentation violation, -bus error, or just weird results. Change the zero to C<&sv_undef> in the first +bus error, or just weird results. Change the zero to C<&PL_sv_undef> in the first line and all will be well. To free an SV that you've created, call C. Normally this @@ -618,10 +618,10 @@ including (but not limited to) the following: Format Subroutine -There is a single stash called "defstash" that holds the items that exist +There is a single stash called "PL_defstash" that holds the items that exist in the "main" package. To get at the items in other packages, append the string "::" to the package name. The items in the "Foo" package are in -the stash "Foo::" in defstash. The items in the "Bar::Baz" package are +the stash "Foo::" in PL_defstash. The items in the "Bar::Baz" package are in the stash "Baz::" in "Bar::"'s stash. To get the stash pointer for a particular package, use the function: @@ -1041,7 +1041,7 @@ string pointed to by C is Safefree()ed. If one has a I in short-lived storage, the corresponding string may be reallocated like this: - SAVEDELETE(defstash, savepv(tmpbuf), strlen(tmpbuf)); + SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf)); =item C @@ -1451,6 +1451,14 @@ are subject to the same restrictions as in the pass 2. This is a listing of functions, macros, flags, and variables that may be useful to extension writers or that may be found while reading other extensions. + +Note that all Perl API global variables must be referenced with the C +prefix. Some macros are provided for compatibility with the older, +unadorned names, but this support will be removed in a future release. + +It is strongly recommended that all Perl API functions that don't begin +with C be referenced with an explicit C prefix. + The sort order of the listing is case insensitive, with any occurrences of '_' ignored for the the purpose of sorting. @@ -1501,7 +1509,7 @@ will have a reference count of 1. =item av_pop -Pops an SV off the end of the array. Returns C<&sv_undef> if the array is +Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array is empty. SV* av_pop (AV* ar) @@ -1572,27 +1580,27 @@ Returns the stash of the CV. HV* CvSTASH( SV* sv ) -=item DBsingle +=item PL_DBsingle When Perl is run in debugging mode, with the B<-d> switch, this SV is a boolean which indicates whether subs are being single-stepped. Single-stepping is automatically turned on after every step. This is the C -variable which corresponds to Perl's $DB::single variable. See C. +variable which corresponds to Perl's $DB::single variable. See C. -=item DBsub +=item PL_DBsub When Perl is run in debugging mode, with the B<-d> switch, this GV contains the SV which holds the name of the sub being debugged. This is the C -variable which corresponds to Perl's $DB::sub variable. See C. +variable which corresponds to Perl's $DB::sub variable. See C. The sub name can be found by - SvPV( GvSV( DBsub ), na ) + SvPV( GvSV( PL_DBsub ), PL_na ) -=item DBtrace +=item PL_DBtrace Trace variable used when Perl is run in debugging mode, with the B<-d> switch. This is the C variable which corresponds to Perl's $DB::trace -variable. See C. +variable. See C. =item dMARK @@ -1603,7 +1611,7 @@ C. Saves the original stack mark for the XSUB. See C. -=item dowarn +=item PL_dowarn The C variable which corresponds to Perl's $^W warning variable. @@ -1806,7 +1814,7 @@ Returns the key slot of the hash entry as a C value, doing any necessary dereferencing of possibly C keys. The length of the string is placed in C (this is a macro, so do I use C<&len>). If you do not care about what the length of the key is, -you may use the global variable C. Remember though, that hash +you may use the global variable C. Remember though, that hash keys in perl are free to contain embedded nulls, so using C or similar is not a good way to find the length of hash keys. This is very similar to the C macro described elsewhere in @@ -2143,7 +2151,7 @@ the type. Can do overlapping moves. See also C. void Move( s, d, n, t ) -=item na +=item PL_na A variable which may be used with C to tell Perl to calculate the string length. @@ -2878,9 +2886,9 @@ double. Checks the B setting. Use C. int SvNIOKp (SV* SV) -=item sv_no +=item PL_sv_no -This is the C SV. See C. Always refer to this as C<&sv_no>. +This is the C SV. See C. Always refer to this as C<&PL_sv_no>. =item SvNOK @@ -2938,7 +2946,7 @@ for the SvPVX. This hack is used internally to speed up removal of characters from the beginning of a SvPV. When SvOOK is true, then the start of the allocated string buffer is really (SvPVX - SvIVX). - int SvOOK(Sv* sv) + int SvOOK(SV* sv) =item SvPOK @@ -2974,7 +2982,7 @@ Checks the B setting. Use C. =item SvPV Returns a pointer to the string in the SV, or a stringified form of the SV -if the SV does not contain a string. If C is C then Perl will +if the SV does not contain a string. If C is C then Perl will handle the length on its own. Handles 'get' magic. char* SvPV (SV* sv, int len ) @@ -3144,7 +3152,7 @@ will be returned and will have a reference count of 1. Copies a pointer into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to -the new SV. If the C argument is NULL then C will be placed +the new SV. If the C argument is NULL then C will be placed into the SV. The C argument indicates the package for the blessing. Set C to C to avoid the blessing. The new SV will be returned and will have a reference count of 1. @@ -3291,9 +3299,9 @@ Returns the type of the SV. See C. An enum of flags for Perl types. These are found in the file B in the C enum. Test these flags with the C macro. -=item sv_undef +=item PL_sv_undef -This is the C SV. Always refer to this as C<&sv_undef>. +This is the C SV. Always refer to this as C<&PL_sv_undef>. =item sv_unref @@ -3363,9 +3371,9 @@ Returns the unsigned integer which is stored in the SV. UV SvUVX(SV* sv) -=item sv_yes +=item PL_sv_yes -This is the C SV. See C. Always refer to this as C<&sv_yes>. +This is the C SV. See C. Always refer to this as C<&PL_sv_yes>. =item THIS @@ -3449,7 +3457,7 @@ Return an integer from an XSUB immediately. Uses C. =item XSRETURN_NO -Return C<&sv_no> from an XSUB immediately. Uses C. +Return C<&PL_sv_no> from an XSUB immediately. Uses C. XSRETURN_NO; @@ -3467,13 +3475,13 @@ Return a copy of a string from an XSUB immediately. Uses C. =item XSRETURN_UNDEF -Return C<&sv_undef> from an XSUB immediately. Uses C. +Return C<&PL_sv_undef> from an XSUB immediately. Uses C. XSRETURN_UNDEF; =item XSRETURN_YES -Return C<&sv_yes> from an XSUB immediately. Uses C. +Return C<&PL_sv_yes> from an XSUB immediately. Uses C. XSRETURN_YES; @@ -3493,7 +3501,7 @@ stored in a new mortal SV. =item XST_mNO -Place C<&sv_no> into the specified position C on the stack. +Place C<&PL_sv_no> into the specified position C on the stack. XST_mNO( int i ) @@ -3506,13 +3514,13 @@ value is stored in a new mortal SV. =item XST_mUNDEF -Place C<&sv_undef> into the specified position C on the stack. +Place C<&PL_sv_undef> into the specified position C on the stack. XST_mUNDEF( int i ) =item XST_mYES -Place C<&sv_yes> into the specified position C on the stack. +Place C<&PL_sv_yes> into the specified position C on the stack. XST_mYES( int i ) diff --git a/pod/perltoc.pod b/pod/perltoc.pod index 67294b4..04d37e5 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -862,7 +862,8 @@ CGI script to do bad things? =item C Source Compatibility -Core sources now require ANSI C compiler, Enabling threads has source +Core sources now require ANSI C compiler, All Perl global variables must +now be referenced with an explicit prefix, Enabling threads has source compatibility issues =item Binary Compatibility @@ -885,6 +886,10 @@ compatibility issues =item Regular Expressions +Many new and improved optimizations, Many bug fixes, New regular expression +constructs, New operator for precompiled regular expressions, Other +improvements, Incompatible changes + =item Improved malloc() =item Quicksort is internally implemented @@ -973,18 +978,6 @@ CGI, POSIX, DB_File, MakeMaker, CPAN, Cwd, Benchmark =item Utility Changes -=item API Changes - -=over - -=item Incompatible Changes - -=item Deprecations, Extensions - -=item C++ Support - -=back - =item Documentation Changes =item New Diagnostics @@ -2671,21 +2664,22 @@ save_hptr(HV **hptr)> av_clear, av_extend, av_fetch, AvFILL, av_len, av_make, av_pop, av_push, av_shift, av_store, av_undef, av_unshift, CLASS, Copy, croak, CvSTASH, -DBsingle, DBsub, DBtrace, dMARK, dORIGMARK, dowarn, dSP, dXSARGS, dXSI32, -do_binmode, ENTER, EXTEND, fbm_compile, fbm_instr, FREETMPS, G_ARRAY, -G_DISCARD, G_EVAL, GIMME, GIMME_V, G_NOARGS, G_SCALAR, gv_fetchmeth, -gv_fetchmethod, gv_fetchmethod_autoload, G_VOID, gv_stashpv, gv_stashsv, -GvSV, HEf_SVKEY, HeHASH, HeKEY, HeKLEN, HePV, HeSVKEY, HeSVKEY_force, -HeSVKEY_set, HeVAL, hv_clear, hv_delayfree_ent, hv_delete, hv_delete_ent, -hv_exists, hv_exists_ent, hv_fetch, hv_fetch_ent, hv_free_ent, hv_iterinit, -hv_iterkey, hv_iterkeysv, hv_iternext, hv_iternextsv, hv_iterval, hv_magic, -HvNAME, hv_store, hv_store_ent, hv_undef, isALNUM, isALPHA, isDIGIT, -isLOWER, isSPACE, isUPPER, items, ix, LEAVE, looks_like_number, MARK, -mg_clear, mg_copy, mg_find, mg_free, mg_get, mg_len, mg_magical, mg_set, -Move, na, New, newAV, Newc, newCONSTSUB, newHV, newRV_inc, newRV_noinc, -NEWSV, newSViv, newSVnv, newSVpv, newSVpvf, newSVpvn, newSVrv, newSVsv, -newXS, newXSproto, Newz, Nullav, Nullch, Nullcv, Nullhv, Nullsv, ORIGMARK, -perl_alloc, perl_call_argv, perl_call_method, perl_call_pv, perl_call_sv, +PL_DBsingle, PL_DBsub, PL_DBtrace, dMARK, dORIGMARK, PL_dowarn, dSP, +dXSARGS, dXSI32, do_binmode, ENTER, EXTEND, fbm_compile, fbm_instr, +FREETMPS, G_ARRAY, G_DISCARD, G_EVAL, GIMME, GIMME_V, G_NOARGS, G_SCALAR, +gv_fetchmeth, gv_fetchmethod, gv_fetchmethod_autoload, G_VOID, gv_stashpv, +gv_stashsv, GvSV, HEf_SVKEY, HeHASH, HeKEY, HeKLEN, HePV, HeSVKEY, +HeSVKEY_force, HeSVKEY_set, HeVAL, hv_clear, hv_delayfree_ent, hv_delete, +hv_delete_ent, hv_exists, hv_exists_ent, hv_fetch, hv_fetch_ent, +hv_free_ent, hv_iterinit, hv_iterkey, hv_iterkeysv, hv_iternext, +hv_iternextsv, hv_iterval, hv_magic, HvNAME, hv_store, hv_store_ent, +hv_undef, isALNUM, isALPHA, isDIGIT, isLOWER, isSPACE, isUPPER, items, ix, +LEAVE, looks_like_number, MARK, mg_clear, mg_copy, mg_find, mg_free, +mg_get, mg_len, mg_magical, mg_set, Move, PL_na, New, newAV, Newc, +newCONSTSUB, newHV, newRV_inc, newRV_noinc, NEWSV, newSViv, newSVnv, +newSVpv, newSVpvf, newSVpvn, newSVrv, newSVsv, newXS, newXSproto, Newz, +Nullav, Nullch, Nullcv, Nullhv, Nullsv, ORIGMARK, perl_alloc, +perl_call_argv, perl_call_method, perl_call_pv, perl_call_sv, perl_construct, perl_destruct, perl_eval_sv, perl_eval_pv, perl_free, perl_get_av, perl_get_cv, perl_get_hv, perl_get_sv, perl_parse, perl_require_pv, perl_run, POPi, POPl, POPp, POPn, POPs, PUSHMARK, PUSHi, @@ -2697,7 +2691,7 @@ sv_catsv, sv_catsv_mg, sv_chop, sv_cmp, SvCUR, SvCUR_set, sv_dec, sv_derived_from, sv_derived_from, SvEND, sv_eq, SvGETMAGIC, SvGROW, sv_grow, sv_inc, sv_insert, SvIOK, SvIOK_off, SvIOK_on, SvIOK_only, SvIOKp, sv_isa, sv_isobject, SvIV, SvIVX, SvLEN, sv_len, sv_magic, sv_mortalcopy, -sv_newmortal, SvNIOK, SvNIOK_off, SvNIOKp, sv_no, SvNOK, SvNOK_off, +sv_newmortal, SvNIOK, SvNIOK_off, SvNIOKp, PL_sv_no, SvNOK, SvNOK_off, SvNOK_on, SvNOK_only, SvNOKp, SvNV, SvNVX, SvOK, SvOOK, SvPOK, SvPOK_off, SvPOK_on, SvPOK_only, SvPOKp, SvPV, SvPV_force, SvPVX, SvREFCNT, SvREFCNT_dec, SvREFCNT_inc, SvROK, SvROK_off, SvROK_on, SvRV, SvSETMAGIC, @@ -2707,10 +2701,10 @@ sv_setpvf_mg, sv_setref_iv, sv_setref_nv, sv_setref_pv, sv_setref_pvn, SvSetSV, SvSetSV_nosteal, sv_setsv, sv_setsv_mg, sv_setuv, sv_setuv_mg, SvSTASH, SvTAINT, SvTAINTED, SvTAINTED_off, SvTAINTED_on, SVt_IV, SVt_PV, SVt_PVAV, SVt_PVCV, SVt_PVHV, SVt_PVMG, SVt_NV, SvTRUE, SvTYPE, svtype, -sv_undef, sv_unref, SvUPGRADE, sv_upgrade, sv_usepvn, sv_usepvn_mg, +PL_sv_undef, sv_unref, SvUPGRADE, sv_upgrade, sv_usepvn, sv_usepvn_mg, sv_vcatpvfn(sv, pat, patlen, args, svargs, svmax, used_locale), sv_vsetpvfn(sv, pat, patlen, args, svargs, svmax, used_locale), SvUV, -SvUVX, sv_yes, THIS, toLOWER, toUPPER, warn, XPUSHi, XPUSHn, XPUSHp, +SvUVX, PL_sv_yes, THIS, toLOWER, toUPPER, warn, XPUSHi, XPUSHn, XPUSHp, XPUSHs, XPUSHu, XS, XSRETURN, XSRETURN_EMPTY, XSRETURN_IV, XSRETURN_NO, XSRETURN_NV, XSRETURN_PV, XSRETURN_UNDEF, XSRETURN_YES, XST_mIV, XST_mNV, XST_mNO, XST_mPV, XST_mUNDEF, XST_mYES, XS_VERSION, XS_VERSION_BOOTCHECK, diff --git a/pod/perlxs.pod b/pod/perlxs.pod index 1eea753..c578a2e 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -372,7 +372,7 @@ and C<$type> can be used as in typemaps. bool_t rpcb_gettime(host,timep) - char *host = (char *)SvPV($arg,na); + char *host = (char *)SvPV($arg,PL_na); time_t &timep = 0; OUTPUT: timep @@ -396,7 +396,7 @@ initialization. bool_t rpcb_gettime(host,timep) time_t &timep ; /*\$v{time}=@{[$v{time}=$arg]}*/ - char *host + SvOK($v{time}) ? SvPV($arg,na) : NULL; + char *host + SvOK($v{time}) ? SvPV($arg,PL_na) : NULL; OUTPUT: timep @@ -555,7 +555,7 @@ The XS code, with ellipsis, follows. char *host = "localhost"; CODE: if( items > 1 ) - host = (char *)SvPV(ST(1), na); + host = (char *)SvPV(ST(1), PL_na); RETVAL = rpcb_gettime( host, &timep ); OUTPUT: timep @@ -681,7 +681,7 @@ return value, should the need arise. sv_setnv( ST(0), (double)timep); } else{ - ST(0) = &sv_undef; + ST(0) = &PL_sv_undef; } To return an empty list one must use a PPCODE: block and @@ -788,7 +788,7 @@ prototypes. char *host = "localhost"; CODE: if( items > 1 ) - host = (char *)SvPV(ST(1), na); + host = (char *)SvPV(ST(1), PL_na); RETVAL = rpcb_gettime( host, &timep ); OUTPUT: timep