Change 23308 by nicholas@no-spam on 2004/09/10 07:28:09
Integrate:
[ 23173]
Fix and update Perl_grok_* docs.
[ 23176]
Add comment to the top of most .c files explaining their purpose
[ 23180]
Add comment to top of reentr.c and fix typos in other files
[ 23187]
more typo fixes for change 3176 (comments at top of .c files)
[ 23195]
Comment describing purpose.
[ 23196]
Document sv_catpvn_nomg, sv_setsv_nomg and sv_catsv_nomg.
[ 23207]
fix minor nit in file description, to keep Jarkko happy
[ 23214]
Subject: api doc fix for SvSetMagicSV_nosteal
From: Stas Bekman <stas@no-spam>
Date: Thu, 12 Aug 2004 18:10:36 -0700
Message-ID: <411C150C.5020602@no-spam>
Affected files ...
... //depot/maint-5.8/perl/deb.c#7 integrate
... //depot/maint-5.8/perl/doio.c#28 integrate
... //depot/maint-5.8/perl/doop.c#13 integrate
... //depot/maint-5.8/perl/dump.c#28 integrate
... //depot/maint-5.8/perl/globals.c#5 integrate
... //depot/maint-5.8/perl/gv.c#19 integrate
... //depot/maint-5.8/perl/hv.c#40 integrate
... //depot/maint-5.8/perl/locale.c#7 integrate
... //depot/maint-5.8/perl/malloc.c#9 integrate
... //depot/maint-5.8/perl/mg.c#45 integrate
... //depot/maint-5.8/perl/miniperlmain.c#6 integrate
... //depot/maint-5.8/perl/numeric.c#9 integrate
... //depot/maint-5.8/perl/op.c#66 integrate
... //depot/maint-5.8/perl/pad.c#22 integrate
... //depot/maint-5.8/perl/perl.c#84 integrate
... //depot/maint-5.8/perl/perlio.c#44 integrate
... //depot/maint-5.8/perl/perly.h#2 integrate
... //depot/maint-5.8/perl/perly.y#5 integrate
... //depot/maint-5.8/perl/pod/perlapi.pod#35 integrate
... //depot/maint-5.8/perl/pp.c#43 integrate
... //depot/maint-5.8/perl/pp_ctl.c#61 integrate
... //depot/maint-5.8/perl/pp_hot.c#51 integrate
... //depot/maint-5.8/perl/pp_pack.c#13 integrate
... //depot/maint-5.8/perl/pp_sort.c#10 integrate
... //depot/maint-5.8/perl/pp_sys.c#44 integrate
... //depot/maint-5.8/perl/reentr.c#12 integrate
... //depot/maint-5.8/perl/reentr.h#11 integrate
... //depot/maint-5.8/perl/reentr.pl#16 integrate
... //depot/maint-5.8/perl/regcomp.c#28 integrate
... //depot/maint-5.8/perl/regexec.c#31 integrate
... //depot/maint-5.8/perl/run.c#5 integrate
... //depot/maint-5.8/perl/scope.c#20 integrate
... //depot/maint-5.8/perl/sv.h#30 integrate
... //depot/maint-5.8/perl/taint.c#6 integrate
... //depot/maint-5.8/perl/universal.c#23 integrate
... //depot/maint-5.8/perl/utf8.c#16 integrate
... //depot/maint-5.8/perl/util.c#44 integrate
Differences ...
==== //depot/maint-5.8/perl/deb.c#7 (text) ====
Index: perl/deb.c
--- perl/deb.c#6~19400~ Sun May 4 01:29:43 2003
+++ perl/deb.c Fri Sep 10 00:28:09 2004
@@no-spam -13,6 +13,11 @@no-spam
* have seen more than thou knowest, Gray Fool." --Denethor
*/
+/*
+ * This file contains various utilities for producing debugging output
+ * (mainly related to displaying the stack)
+ */
+
#include "EXTERN.h"
#define PERL_IN_DEB_C
#include "perl.h"
==== //depot/maint-5.8/perl/doio.c#28 (text) ====
Index: perl/doio.c
--- perl/doio.c#27~23087~ Mon Jul 12 14:36:51 2004
+++ perl/doio.c Fri Sep 10 00:28:09 2004
@@no-spam -15,6 +15,11 @@no-spam
* chattering, into calmer and more level reaches."
*/
+/* This file contains functions that do the actual I/O on behalf of ops.
+ * For example, pp_print() calls the do_print() function in this file for
+ * each argument needing printing.
+ */
+
#include "EXTERN.h"
#define PERL_IN_DOIO_C
#include "perl.h"
==== //depot/maint-5.8/perl/doop.c#13 (text) ====
Index: perl/doop.c
--- perl/doop.c#12~22555~ Mon Mar 22 11:57:32 2004
+++ perl/doop.c Fri Sep 10 00:28:09 2004
@@no-spam -12,6 +12,11 @@no-spam
* "'So that was the job I felt I had to do when I started,' thought Sam."
*/
+/* This file contains some common functions needed to carry out certain
+ * ops. For example both pp_schomp() and pp_chomp() - scalar and array
+ * chomp operations - call the function do_chomp() found in this file.
+ */
+
#include "EXTERN.h"
#define PERL_IN_DOOP_C
#include "perl.h"
==== //depot/maint-5.8/perl/dump.c#28 (text) ====
Index: perl/dump.c
--- perl/dump.c#27~22622~ Wed Mar 31 07:16:49 2004
+++ perl/dump.c Fri Sep 10 00:28:09 2004
@@no-spam -13,6 +13,13 @@no-spam
* it has not been hard for me to read your mind and memory.'"
*/
+/* This file contains utility routines to dump the contents of SV and OP
+ * structures, as used by command-line options like -Dt and -Dx, and
+ * by Devel::Peek.
+ *
+ * It also holds the debugging version of the runops function.
+ */
+
#include "EXTERN.h"
#define PERL_IN_DUMP_C
#include "perl.h"
==== //depot/maint-5.8/perl/globals.c#5 (text) ====
Index: perl/globals.c
--- perl/globals.c#4~19400~ Sun May 4 01:29:43 2003
+++ perl/globals.c Fri Sep 10 00:28:09 2004
@@no-spam -12,6 +12,24 @@no-spam
* Elves, Dwarves, and Men." --Elrond
*/
+/* This file exists to #include "perl.h" _ONCE_ with
+ * PERL_IN_GLOBALS_C defined. That causes various global varaiables
+ * in perl.h and other files it includes to be _defined_ (and initialized)
+ * rather than just declared.
+ *
+ * There is a #include "perlapi.h" which makes use of the fact
+ * that the object file created from this file will be included by linker
+ * (to resolve global variables). perlapi.h mention various other "API"
+ * functions not used by perl itself, but the functions get
+ * pulled into the perl executable via the refrerence here.
+ *
+ * Two printf() like functions have also found their way here.
+ * Most likely by analogy to the API scheme above (as perl doesn't
+ * use them) but they probably belong elsewhere the obvious place
+ * being in perlio.c
+ *
+*/
+
#include "INTERN.h"
#define PERL_IN_GLOBALS_C
#include "perl.h"
==== //depot/maint-5.8/perl/gv.c#19 (text) ====
Index: perl/gv.c
--- perl/gv.c#18~22980~ Wed Jun 23 05:44:49 2004
+++ perl/gv.c Fri Sep 10 00:28:09 2004
@@no-spam -19,6 +19,15 @@no-spam
/*
=head1 GV Functions
+
+A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
+It is a structure that holds a pointer to a scalar, an array, a hash etc,
+corresponding to $foo, @no-spam %foo.
+
+GVs are usually found as values in stashes (symbol table hashes) where
+Perl stores its global variables.
+
+=cut
*/
#include "EXTERN.h"
==== //depot/maint-5.8/perl/hv.c#40 (text) ====
Index: perl/hv.c
--- perl/hv.c#39~23169~ Thu Jul 29 15:05:16 2004
+++ perl/hv.c Fri Sep 10 00:28:09 2004
@@no-spam -14,6 +14,16 @@no-spam
/*
=head1 Hash Manipulation Functions
+
+A HV structure represents a Perl hash. It consists mainly of an array
+of pointers, each of which points to a linked list of HE structures. The
+array is indexed by the hash function of the key, so each linked list
+represents all the hash entries with the same hash value. Each HE contains
+a pointer to the actual value, plus a pointer to a HEK structure which
+holds the key and hash value.
+
+=cut
+
*/
#include "EXTERN.h"
==== //depot/maint-5.8/perl/locale.c#7 (text) ====
Index: perl/locale.c
--- perl/locale.c#6~19400~ Sun May 4 01:29:43 2003
+++ perl/locale.c Fri Sep 10 00:28:09 2004
@@no-spam -18,6 +18,10 @@no-spam
* nef aear, si nef aearon!
*/
+/* utility functions for handling locale-specific stuff like what
+ * character represents the decimal point.
+ */
+
#include "EXTERN.h"
#define PERL_IN_LOCALE_C
#include "perl.h"
@@no-spam -560,6 +564,7 @@no-spam
* The real transformed data begins at offset sizeof(collationix).
* Please see sv_collxfrm() to see how this is used.
*/
+
char *
Perl_mem_collxfrm(pTHX_ const char *s, STRLEN len, STRLEN *xlen)
{
==== //depot/maint-5.8/perl/malloc.c#9 (text) ====
Index: perl/malloc.c
--- perl/malloc.c#8~23306~ Thu Sep 9 23:39:03 2004
+++ perl/malloc.c Fri Sep 10 00:28:09 2004
@@no-spam -6,6 +6,12 @@no-spam
* "'The Chamber of Records,' said Gimli. 'I guess that is where we now stand.'"
*/
+/* This file contains Perl's own implementation of the malloc library.
+ * It is used if Configure decides that, on your platform, Perl's
+ * version is better than the OS's, or if you give Configure the
+ * -Dusemymalloc command-line option.
+ */
+
/*
Here are some notes on configuring Perl's malloc. (For non-perl
usage see below.)
==== //depot/maint-5.8/perl/mg.c#45 (text) ====
Index: perl/mg.c
--- perl/mg.c#44~23264~ Sun Sep 5 11:42:01 2004
+++ perl/mg.c Fri Sep 10 00:28:09 2004
@@no-spam -15,6 +15,24 @@no-spam
/*
=head1 Magical Functions
+
+"Magic" is special data attached to SV structures in order to give them
+"magical" properties. When any Perl code tries to read from, or assign to,
+an SV marked as magical, it calls the 'get' or 'set' function associated
+with that SV's magic. A get is called prior to reading an SV, in order to
+give it a chance to update its internal value (get on $. writes the line
+number of the last read filehandle into to the SV's IV slot), while
+set is called after an SV has been written to, in order to allow it to make
+use of its changed value (set on $/ copies the SV's new value to the
+PL_rs global variable).
+
+Magic is implemented as a linked list of MAGIC structures attached to the
+SV. Each MAGIC struct holds the type of the magic, a pointer to an array
+of functions that implement the get(), set(), length() etc functions,
+plus space for some flags and pointers. For example, a tied variable has
+a MAGIC structure that contains a pointer to the object associated with the
+tie.
+
*/
#include "EXTERN.h"
==== //depot/maint-5.8/perl/miniperlmain.c#6 (text) ====
Index: perl/miniperlmain.c
--- perl/miniperlmain.c#5~19891~ Mon Jun 30 02:39:29 2003
+++ perl/miniperlmain.c Fri Sep 10 00:28:09 2004
@@no-spam -12,9 +12,18 @@no-spam
* "The Road goes ever on and on, down from the door where it began."
*/
+/* This file contains the main() function for the perl interpreter.
+ * Note that miniperlmain.c contains main() for the 'miniperl' binary,
+ * while perlmain.c contains main() for the 'perl' binary.
+ *
+ * Miniperl is like perl except that it does not support dynamic loading,
+ * and in fact is used to build the dynamic modules needed for the 'real'
+ * perl executable.
+ */
+
#ifdef OEMVS
#ifdef MYMALLOC
-/* sbrk is limited to first heap segement so make it big */
+/* sbrk is limited to first heap segment so make it big */
#pragma runopts(HEAP(8M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))
#else
#pragma runopts(HEAP(2M,500K,ANYWHERE,KEEP,8K,4K) STACK(,,ANY,) ALL31(ON))
==== //depot/maint-5.8/perl/numeric.c#9 (text) ====
Index: perl/numeric.c
--- perl/numeric.c#8~19400~ Sun May 4 01:29:43 2003
+++ perl/numeric.c Fri Sep 10 00:28:09 2004
@@no-spam -15,6 +15,12 @@no-spam
/*
=head1 Numeric functions
+
+This file contains all the stuff needed by perl for manipulating numeric
+values, including such things as replacements for the OS's atof() function
+
+=cut
+
*/
#include "EXTERN.h"
@@no-spam -118,8 +124,10 @@no-spam
On entry I<start> and I<*len> give the string to scan, I<*flags> gives
conversion flags, and I<result> should be NULL or a pointer to an NV.
The scan stops at the end of the string, or the first invalid character.
-On return I<*len> is set to the length scanned string, and I<*flags> gives
-output flags.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
@@no-spam -127,7 +135,7 @@no-spam
and writes the value to I<*result> (or the value is discarded if I<result>
is NULL).
-The hex number may optionally be prefixed with "0b" or "b" unless
+The binary number may optionally be prefixed with "0b" or "b" unless
C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
number may use '_' characters to separate digits.
@@no-spam -231,9 +239,11 @@no-spam
On entry I<start> and I<*len> give the string to scan, I<*flags> gives
conversion flags, and I<result> should be NULL or a pointer to an NV.
-The scan stops at the end of the string, or the first non-hex-digit character.
-On return I<*len> is set to the length scanned string, and I<*flags> gives
-output flags.
+The scan stops at the end of the string, or the first invalid character.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
@@no-spam -342,6 +352,24 @@no-spam
/*
=for apidoc grok_oct
+converts a string representing an octal number to numeric form.
+
+On entry I<start> and I<*len> give the string to scan, I<*flags> gives
+conversion flags, and I<result> should be NULL or a pointer to an NV.
+The scan stops at the end of the string, or the first invalid character.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
+
+If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
+returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
+and writes the value to I<*result> (or the value is discarded if I<result>
+is NULL).
+
+If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
+number may use '_' characters to separate digits.
=cut
*/
@@no-spam -396,7 +424,7 @@no-spam
goto redo;
}
/* Allow \octal to work the DWIM way (that is, stop scanning
- * as soon as non-octal characters are seen, complain only iff
+ * as soon as non-octal characters are seen, complain only if
* someone seems to want to use the digits eight and nine). */
if (digit == 8 || digit == 9) {
if (!(*flags & PERL_SCAN_SILENT_ILLDIGIT) && ckWARN(WARN_DIGIT))
==== //depot/maint-5.8/perl/op.c#66 (text) ====
Index: perl/op.c
--- perl/op.c#65~23296~ Thu Sep 9 05:58:00 2004
+++ perl/op.c Fri Sep 10 00:28:09 2004
@@no-spam -16,6 +16,30 @@no-spam
* either way, as the saying is, if you follow me." --the Gaffer
*/
+/* This file contains the functions that create, manipulate and optimize
+ * the OP structures that hold a compiled perl program.
+ *
+ * A Perl program is compiled into a tree of OPs. Each op contains
+ * structural pointers (eg to its siblings and the next op in the
+ * execution sequence), a pointer to the function that would execute the
+ * op, plus any data specific to that op. For example, an OP_CONST op
+ * points to the pp_const() function and to an SV containing the constant
+ * value. When pp_const() is executed, its job is to push that SV onto the
+ * stack.
+ *
+ * OPs are mainly created by the newFOO() functions, which are mainly
+ * called from the parser (in perly.y) as the code is parsed. For example
+ * the Perl code $a + $b * $c would cause the equivalent of the following
+ * to be called (oversimplifying a bit):
+ *
+ * newBINOP(OP_ADD, flags,
+ * newSVREF($a),
+ * newBINOP(OP_MULTIPLY, flags, newSVREF($b), newSVREF($c))
+ * )
+ *
+ * Note that during the build of miniperl, a temporary copy of this file
+ * is made, called opmini.c.
+ */
#include "EXTERN.h"
#define PERL_IN_OP_C
==== //depot/maint-5.8/perl/pad.c#22 (text) ====
Index: perl/pad.c
--- perl/pad.c#21~22980~ Wed Jun 23 05:44:49 2004
+++ perl/pad.c Fri Sep 10 00:28:09 2004
@@no-spam -22,6 +22,11 @@no-spam
/*
=head1 Pad Data Structures
+This file contains the functions that create and manipulate scratchpads,
+which are array-of-array data structures attached to a CV (ie a sub)
+and which store lexical variables and opcode temporary and per-thread
+values.
+
=for apidoc m|AV *|CvPADLIST|CV *cv
CV's can have CvPADLIST(cv) set to point to an AV.
==== //depot/maint-5.8/perl/perl.c#84 (text) ====
Index: perl/perl.c
--- perl/perl.c#83~23306~ Thu Sep 9 23:39:03 2004
+++ perl/perl.c Fri Sep 10 00:28:09 2004
@@no-spam -12,6 +12,12 @@no-spam
* "A ship then new they built for him/of mithril and of elven glass" --Bilbo
*/
+/* This file contains the top-level functions that are used to create, use
+ * and destroy a perl interpreter, plus the functions used by XS code to
+ * call back into perl. Note that it does not contain the actual main()
+ * function of the interpreter; that can be found in perlmain.c
+ */
+
/* PSz 12 Nov 03
*
* Be proud that perl(1) may proclaim:
==== //depot/maint-5.8/perl/perlio.c#44 (text) ====
Index: perl/perlio.c
--- perl/perlio.c#43~22555~ Mon Mar 22 11:57:32 2004
+++ perl/perlio.c Fri Sep 10 00:28:09 2004
@@no-spam -9,6 +9,12 @@no-spam
* over passes, and through long dales, and across many streams.
*/
+/* This file contains the functions needed to implement PerlIO, which
+ * is Perl's private replacement for the C stdio library. This is used
+ * by default unless you compile with -Uuseperlio or run with
+ * PERLIO=:stdio (but don't do this unless you know what you're doing)
+ */
+
/*
* If we have ActivePerl-like PERL_IMPLICIT_SYS then we need a dTHX to get
* at the dispatch tables, even when we do not need it for other reasons.
==== //depot/maint-5.8/perl/perly.y#5 (text) ====
Index: perl/perly.y
--- perl/perly.y#4~22006~ Tue Dec 30 07:23:04 2003
+++ perl/perly.y Fri Sep 10 00:28:09 2004
@@no-spam -12,6 +12,15 @@no-spam
* All that is gold does not glitter, not all those who wander are lost.'
*/
+/* This file holds the grammar for the Perl language. If edited, you need
+ * to run regen_perly.pl, which re-creates the files perly.h, perly.tab
+ * and perly.act which are derived from this.
+ *
+ * The main job of of this grammar is to call the various newFOO()
+ * functions in op.c to build a syntax tree of OP structs.
+ * It relies on the lexer in toke.c to do the tokenizing.
+ */
+
%{
#include "EXTERN.h"
#define PERL_IN_PERLY_C
==== //depot/maint-5.8/perl/pod/perlapi.pod#35 (text+w) ====
Index: perl/pod/perlapi.pod
--- perl/pod/perlapi.pod#34~23306~ Thu Sep 9 23:39:03 2004
+++ perl/pod/perlapi.pod Fri Sep 10 00:28:09 2004
@@no-spam -1479,7 +1479,7 @@no-spam
=item SvSetMagicSV_nosteal
-Like C<SvSetMagicSV>, but does any set magic required afterwards.
+Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
@@no-spam -1891,8 +1891,10 @@no-spam
On entry I<start> and I<*len> give the string to scan, I<*flags> gives
conversion flags, and I<result> should be NULL or a pointer to an NV.
The scan stops at the end of the string, or the first invalid character.
-On return I<*len> is set to the length scanned string, and I<*flags> gives
-output flags.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
@@no-spam -1900,7 +1902,7 @@no-spam
and writes the value to I<*result> (or the value is discarded if I<result>
is NULL).
-The hex number may optionally be prefixed with "0b" or "b" unless
+The binary number may optionally be prefixed with "0b" or "b" unless
C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
number may use '_' characters to separate digits.
@@no-spam -1916,9 +1918,11 @@no-spam
On entry I<start> and I<*len> give the string to scan, I<*flags> gives
conversion flags, and I<result> should be NULL or a pointer to an NV.
-The scan stops at the end of the string, or the first non-hex-digit character.
-On return I<*len> is set to the length scanned string, and I<*flags> gives
-output flags.
+The scan stops at the end of the string, or the first invalid character.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
@@no-spam -1972,6 +1976,24 @@no-spam
=item grok_oct
+converts a string representing an octal number to numeric form.
+
+On entry I<start> and I<*len> give the string to scan, I<*flags> gives
+conversion flags, and I<result> should be NULL or a pointer to an NV.
+The scan stops at the end of the string, or the first invalid character.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
+
+If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
+returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
+and writes the value to I<*result> (or the value is discarded if I<result>
+is NULL).
+
+If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
+number may use '_' characters to separate digits.
UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
@@no-spam -3805,6 +3827,15 @@no-spam
=for hackers
Found in file sv.c
+=item sv_catpvn_nomg
+
+Like C<sv_catpvn> but doesn't process magic.
+
+ void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
=item sv_catpv_mg
Like C<sv_catpv>, but also handles 'set' magic.
@@no-spam -3846,6 +3877,15 @@no-spam
=for hackers
Found in file sv.c
+=item sv_catsv_nomg
+
+Like C<sv_catsv> but doesn't process magic.
+
+ void sv_catsv_nomg(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
=item sv_chop
Efficient removal of characters from the beginning of the string buffer.
@@no-spam -4583,6 +4623,15 @@no-spam
=for hackers
Found in file sv.c
+
+=item sv_setsv_nomg
+
+Like C<sv_setsv> but doesn't process magic.
+
+ void sv_setsv_nomg(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.h
=item sv_setuv
==== //depot/maint-5.8/perl/pp.c#43 (text) ====
Index: perl/pp.c
--- perl/pp.c#42~23302~ Thu Sep 9 14:45:33 2004
+++ perl/pp.c Fri Sep 10 00:28:09 2004
@@no-spam -13,6 +13,13 @@no-spam
* and no knowing what you'll find around a corner. And Elves, sir!" --Samwise
*/
+/* This file contains general pp ("push/pop") functions that execute the
+ * opcodes that make up a perl program. A typical pp function expects to
+ * find its arguments on the stack, and usually pushes its results onto
+ * the stack, hence the 'pp' terminology. Each OP structure contains
+ * a pointer to the relevant pp_foo() function.
+ */
+
#include "EXTERN.h"
#define PERL_IN_PP_C
#include "perl.h"
==== //depot/maint-5.8/perl/pp_ctl.c#61 (text) ====
Index: perl/pp_ctl.c
--- perl/pp_ctl.c#60~23296~ Thu Sep 9 05:58:00 2004
+++ perl/pp_ctl.c Fri Sep 10 00:28:09 2004
@@no-spam -17,6 +17,17 @@no-spam
* And whither then? I cannot say.
*/
+/* This file contains control-oriented pp ("push/pop") functions that
+ * execute the opcodes that make up a perl program. A typical pp function
+ * expects to find its arguments on the stack, and usually pushes its
+ * results onto the stack, hence the 'pp' terminology. Each OP structure
+ * contains a pointer to the relevant pp_foo() function.
+ *
+ * Control-oriented means things like pp_enteriter() and pp_next(), which
+ * alter the flow of control of the program.
+ */
+
+
#include "EXTERN.h"
#define PERL_IN_PP_CTL_C
#include "perl.h"
==== //depot/maint-5.8/perl/pp_hot.c#51 (text) ====
Index: perl/pp_hot.c
--- perl/pp_hot.c#50~23296~ Thu Sep 9 05:58:00 2004
+++ perl/pp_hot.c Fri Sep 10 00:28:09 2004
@@no-spam -16,6 +16,19 @@no-spam
* Fire, Foes! Awake!
*/
+/* This file contains 'hot' pp ("push/pop") functions that
+ * execute the opcodes that make up a perl program. A typical pp function
+ * expects to find its arguments on the stack, and usually pushes its
+ * results onto the stack, hence the 'pp' terminology. Each OP structure
+ * contains a pointer to the relevant pp_foo() function.
+ *
+ * By 'hot', we mean common ops whose execution speed is critical.
+ * By gathering them together into a single file, we encourage
+ * CPU cache hits on hot code. Also it could be taken as a warning not to
+ * change any code in this file unless you're sure it won't affect
+ * performance.
+ */
+
#include "EXTERN.h"
#define PERL_IN_PP_HOT_C
#include "perl.h"
==== //depot/maint-5.8/perl/pp_pack.c#13 (text) ====
Index: perl/pp_pack.c
--- perl/pp_pack.c#12~22795~ Thu May 6 09:06:17 2004
+++ perl/pp_pack.c Fri Sep 10 00:28:09 2004
@@no-spam -16,6 +16,17 @@no-spam
* some salt.
*/
+/* This file contains pp ("push/pop") functions that
+ * execute the opcodes that make up a perl program. A typical pp function
+ * expects to find its arguments on the stack, and usually pushes its
+ * results onto the stack, hence the 'pp' terminology. Each OP structure
+ * contains a pointer to the relevant pp_foo() function.
+ *
+ * This particular file just contains pp_pack() and pp_unpack(). See the
+ * other pp*.c files for the rest of the pp_ functions.
+ */
+
+
#include "EXTERN.h"
#define PERL_IN_PP_PACK_C
#include "perl.h"
==== //depot/maint-5.8/perl/pp_sort.c#10 (text) ====
Index: perl/pp_sort.c
--- perl/pp_sort.c#9~23292~ Thu Sep 9 02:55:09 2004
+++ perl/pp_sort.c Fri Sep 10 00:28:09 2004
@@no-spam -13,6 +13,17 @@no-spam
* rear!' the slave-driver shouted. 'Three files up. And stay there...
*/
+/* This file contains pp ("push/pop") functions that
+ * execute the opcodes that make up a perl program. A typical pp function
+ * expects to find its arguments on the stack, and usually pushes its
+ * results onto the stack, hence the 'pp' terminology. Each OP structure
+ * contains a pointer to the relevant pp_foo() function.
+ *
+ * This particular file just contains pp_sort(), which is complex
+ * enough to merit its own file! See the other pp*.c files for the rest of
+ * the pp_ functions.
+ */
+
#include "EXTERN.h"
#define PERL_IN_PP_SORT_C
#include "perl.h"
==== //depot/maint-5.8/perl/pp_sys.c#44 (text) ====
Index: perl/pp_sys.c
--- perl/pp_sys.c#43~22555~ Mon Mar 22 11:57:32 2004
+++ perl/pp_sys.c Fri Sep 10 00:28:09 2004
@@no-spam -15,6 +15,15 @@no-spam
* a rumour and a trouble as of great engines throbbing and labouring.
*/
+/* This file contains system pp ("push/pop") functions that
+ * execute the opcodes that make up a perl program. A typical pp function
+ * expects to find its arguments on the stack, and usually pushes its
+ * results onto the stack, hence the 'pp' terminology. Each OP structure
+ * contains a pointer to the relevant pp_foo() function.
+ *
+ * By 'system', we mean ops which interact with the OS, such as pp_open().
+ */
+
#include "EXTERN.h"
#define PERL_IN_PP_SYS_C
#include "perl.h"
==== //depot/maint-5.8/perl/reentr.c#12 (text) ====
Index: perl/reentr.c
--- perl/reentr.c#11~21601~ Sat Nov 1 04:34:09 2003
+++ perl/reentr.c Fri Sep 10 00:28:09 2004
@@no-spam -7,11 +7,17 @@no-spam
* License or the Artistic License, as specified in the README file.
*
* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
- * This file is built by reentrl.pl from data in reentr.pl.
+ * This file is built by reentr.pl from data in reentr.pl.
*
* "Saruman," I said, standing away from him, "only one hand at a time can
* wield the One, and you know that well, so do not trouble to say we!"
*
+ * This file contains a collection of automatically created wrappers
+ * (created by running reentr.pl) for reentrant (thread-safe) versions of
+ * various library calls, such as getpwent_r. The wrapping is done so
+ * that other files like pp_sys.c calling those library functions need not
+ * care about the differences between various platforms' idiosyncrasies
+ * regarding these reentrant interfaces.
*/
#include "EXTERN.h"
==== //depot/maint-5.8/perl/reentr.h#11 (text) ====
Index: perl/reentr.h
--- perl/reentr.h#10~21658~ Wed Nov 5 00:12:08 2003
+++ perl/reentr.h Fri Sep 10 00:28:09 2004
@@no-spam -7,7 +7,7 @@no-spam
* License or the Artistic License, as specified in the README file.
*
* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
- * This file is built by reentrl.pl from data in reentr.pl.
+ * This file is built by reentr.pl from data in reentr.pl.
*/
#ifndef REENTR_H
==== //depot/maint-5.8/perl/reentr.pl#16 (text) ====
Index: perl/reentr.pl
--- perl/reentr.pl#15~21943~ Sun Dec 21 14:41:21 2003
+++ perl/reentr.pl Fri Sep 10 00:28:09 2004
@@no-spam -47,7 +47,7 @@no-spam
* License or the Artistic License, as specified in the README file.
*
* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
- * This file is built by reentrl.pl from data in reentr.pl.
+ * This file is built by reentr.pl from data in reentr.pl.
*/
#ifndef REENTR_H
@@no-spam -839,11 +839,17 @@no-spam
* License or the Artistic License, as specified in the README file.
*
* !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
- * This file is built by reentrl.pl from data in reentr.pl.
+ * This file is built by reentr.pl from data in reentr.pl.
*
* "Saruman," I said, standing away from him, "only one hand at a time can
* wield the One, and you know that well, so do not trouble to say we!"
*
+ * This file contains a collection of automatically created wrappers
+ * (created by running reentr.pl) for reentrant (thread-safe) versions of
+ * various library calls, such as getpwent_r. The wrapping is done so
+ * that other files like pp_sys.c calling those library functions need not
+ * care about the differences between various platforms' idiosyncrasies
+ * regarding these reentrant interfaces.
*/
#include "EXTERN.h"
==== //depot/maint-5.8/perl/regcomp.c#28 (text) ====
Index: perl/regcomp.c
--- perl/regcomp.c#27~23036~ Sun Jul 4 13:59:30 2004
+++ perl/regcomp.c Fri Sep 10 00:28:09 2004
@@no-spam -5,6 +5,11 @@no-spam
* "A fair jaw-cracker dwarf-language must be." --Samwise Gamgee
*/
+/* This file contains functions for compiling a regular expression. See
+ * also regexec.c which funnily enough, contains functions for executing
+ * a regular expression.
+ */
+
/* NOTE: this is derived from Henry Spencer's regexp code, and should not
* confused with the original package (see point 3 below). Thanks, Henry!
*/
==== //depot/maint-5.8/perl/regexec.c#31 (text) ====
Index: perl/regexec.c
--- perl/regexec.c#30~23261~ Sat Sep 4 13:30:30 2004
+++ perl/regexec.c Fri Sep 10 00:28:09 2004
@@no-spam -5,6 +5,11 @@no-spam
* "One Ring to rule them all, One Ring to find them..."
*/
+/* This file contains functions for executing a regular expression. See
+ * also regcomp.c which funnily enough, contains functions for compiling
+ * a regular expression.
+ */
+
/* NOTE: this is derived from Henry Spencer's regexp code, and should not
* confused with the original package (see point 3 below). Thanks, Henry!
*/
==== //depot/maint-5.8/perl/run.c#5 (text) ====
Index: perl/run.c
--- perl/run.c#4~19400~ Sun May 4 01:29:43 2003
+++ perl/run.c Fri Sep 10 00:28:09 2004
@@no-spam -8,6 +8,19 @@no-spam
*
*/
+/* This file contains the main Perl opcode execution loop. It just
+ * calls the pp_foo() function associated with each op, and expects that
+ * function to return a pointer to the next op to be executed, or null if
+ * it's the end of the sub or program or whatever.
+ *
+ * There is a similar loop in dump.c, Perl_runops_debug(), which does
+ * the same, but also checks for various debug flags each time round the
+ * loop.
+ *
+ * Why this function requires a file all of its own is anybody's guess.
+ * DAPM.
+ */
+
#include "EXTERN.h"
#define PERL_IN_RUN_C
#include "perl.h"
==== //depot/maint-5.8/perl/scope.c#20 (text) ====
Index: perl/scope.c
--- perl/scope.c#19~23302~ Thu Sep 9 14:45:33 2004
+++ perl/scope.c Fri Sep 10 00:28:09 2004
@@no-spam -13,6 +13,13 @@no-spam
* levels..."
*/
+/* This file contains functions to manipulate several of Perl's stacks;
+ * in particular it contains code to push various types of things onto
+ * the savestack, then to pop them off and perform the correct restorative
+ * action for each one. This corresponds to the cleanup Perl does at
+ * each scope exit.
+ */
+
#include "EXTERN.h"
#define PERL_IN_SCOPE_C
#include "perl.h"
==== //depot/maint-5.8/perl/sv.h#30 (text) ====
Index: perl/sv.h
--- perl/sv.h#29~22864~ Sun May 30 05:38:30 2004
+++ perl/sv.h Fri Sep 10 00:28:09 2004
@@no-spam -954,6 +954,15 @@no-spam
Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
scalar.
+=for apidoc Am|void|sv_catpvn_nomg|SV* sv|const char* ptr|STRLEN len
+Like C<sv_catpvn> but doesn't process magic.
+
+=for apidoc Am|void|sv_setsv_nomg|SV* dsv|SV* ssv
+Like C<sv_setsv> but doesn't process magic.
+
+=for apidoc Am|void|sv_catsv_nomg|SV* dsv|SV* ssv
+Like C<sv_catsv> but doesn't process magic.
+
=cut
*/
@@no-spam -1169,7 +1178,7 @@no-spam
Like C<SvSetSV>, but does any set magic required afterwards.
=for apidoc Am|void|SvSetMagicSV_nosteal|SV* dsv|SV* ssv
-Like C<SvSetMagicSV>, but does any set magic required afterwards.
+Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
=for apidoc Am|void|SvSHARE|SV* sv
Arranges for sv to be shared between threads if a suitable module
==== //depot/maint-5.8/perl/taint.c#6 (text) ====
Index: perl/taint.c
--- perl/taint.c#5~19400~ Sun May 4 01:29:43 2003
+++ perl/taint.c Fri Sep 10 00:28:09 2004
@@no-spam -14,6 +14,9 @@no-spam
* liar, Saruman, and a corrupter of men's hearts." --Theoden
*/
+/* This file contains a few functions for handling data tainting in Perl
+ */
+
#include "EXTERN.h"
#define PERL_IN_TAINT_C
#include "perl.h"
==== //depot/maint-5.8/perl/universal.c#23 (text) ====
Index: perl/universal.c
--- perl/universal.c#22~22555~ Mon Mar 22 11:57:32 2004
+++ perl/universal.c Fri Sep 10 00:28:09 2004
@@no-spam -14,6 +14,10 @@no-spam
* beginning." --Gandalf, relating Gollum's story
*/
+/* This file contains the code that implements the functions in Perl's
+ * UNIVERSAL package, such as UNIVERSAL->can().
+ */
+
#include "EXTERN.h"
#define PERL_IN_UNIVERSAL_C
#include "perl.h"
==== //depot/maint-5.8/perl/utf8.c#16 (text) ====
Index: perl/utf8.c
--- perl/utf8.c#15~23087~ Mon Jul 12 14:36:51 2004
+++ perl/utf8.c Fri Sep 10 00:28:09 2004
@@no-spam -29,6 +29,12 @@no-spam
/*
=head1 Unicode Support
+This file contains various utility functions for manipulating UTF8-encoded
+strings. For the uninitiated, this is a method of representing arbitrary
+Unicode characters as a variable number of bytes, in such a way that
+characters in the ASCII range are unmodified, and a zero byte never appears
+within non-zero characters.
+
=for apidoc A|U8 *|uvuni_to_utf8_flags|U8 *d|UV uv|UV flags
Adds the UTF-8 representation of the Unicode codepoint C<uv> to the end
==== //depot/maint-5.8/perl/util.c#44 (text) ====
Index: perl/util.c
--- perl/util.c#43~23306~ Thu Sep 9 23:39:03 2004
+++ perl/util.c Fri Sep 10 00:28:09 2004
@@no-spam -13,6 +13,12 @@no-spam
* not content." --Gandalf
*/
+/* This file contains assorted utility routines.
+ * Which is a polite way of saying any stuff that people couldn't think of
+ * a better place for. Amongst other things, it includes the warning and
+ * dieing stuff, plus wrappers for malloc code.
+ */
+
#include "EXTERN.h"
#define PERL_IN_UTIL_C
#include "perl.h"
End of Patch.