the format.
The C<sv_set*()> functions are not generic enough to operate on values
-that have "magic". See L<Magic Virtual Tables> later in this document.
+that have "magic". See L</Magic Virtual Tables> later in this document.
All SVs that contain strings should be terminated with a C<NUL> character.
If it is not C<NUL>-terminated there is a risk of
to be interpreted as a string.
The C<sv_cat*()> functions are not generic enough to operate on values that
-have "magic". See L<Magic Virtual Tables> later in this document.
+have "magic". See L</Magic Virtual Tables> later in this document.
If you know the name of a scalar variable, you can get a pointer to its SV
by using the following:
So to repeat always use SvOK() to check whether an sv is defined.
Also you have to be careful when using C<&PL_sv_undef> as a value in
-AVs or HVs (see L<AVs, HVs and undefined values>).
+AVs or HVs (see L</AVs, HVs and undefined values>).
There are also the two values C<PL_sv_yes> and C<PL_sv_no>, which contain
boolean TRUE and FALSE values, respectively. Like C<PL_sv_undef>, their
first line and all will be well.
To free an SV that you've created, call C<SvREFCNT_dec(SV*)>. Normally this
-call is not necessary (see L<Reference Counts and Mortality>).
+call is not necessary (see L</Reference Counts and Mortality>).
=head2 Offsets
Notice here the LEN is 10. (It may differ on your platform.) Extend the
length of the string to one less than 10, and do a substitution:
- % ./perl -Ilib -MDevel::Peek -le '$a=""; $a.="123456789"; $a=~s/.//; Dump($a)'
- SV = PV(0x7ffa04008a70) at 0x7ffa04030390
- REFCNT = 1
- FLAGS = (POK,OOK,pPOK)
- OFFSET = 1
- PV = 0x7ffa03c05b61 ( "\1" . ) "23456789"\0
- CUR = 8
- LEN = 9
+ % ./perl -Ilib -MDevel::Peek -le '$a=""; $a.="123456789"; $a=~s/.//; \
+ Dump($a)'
+ SV = PV(0x7ffa04008a70) at 0x7ffa04030390
+ REFCNT = 1
+ FLAGS = (POK,OOK,pPOK)
+ OFFSET = 1
+ PV = 0x7ffa03c05b61 ( "\1" . ) "23456789"\0
+ CUR = 8
+ LEN = 9
Here the number of bytes chopped off (1) is shown next as the OFFSET. The
portion of the string between the "real" and the "fake" beginnings is
This returns NULL if the variable does not exist.
-See L<Understanding the Magic of Tied Hashes and Arrays> for more
+See L</Understanding the Magic of Tied Hashes and Arrays> for more
information on how to use the array access functions on tied arrays.
=head2 Working with HVs
of perl, and the return value may change per invocation, so the value
is only valid for the duration of a single perl process.
-See L<Understanding the Magic of Tied Hashes and Arrays> for more
+See L</Understanding the Magic of Tied Hashes and Arrays> for more
information on how to use the hash access functions on tied hashes.
=head2 Hash API Extensions
The C<sv> argument must be a reference value. The C<stash> argument
specifies which class the reference will belong to. See
-L<Stashes and Globs> for information on converting class names into stashes.
+L</Stashes and Globs> for information on converting class names into stashes.
/* Still under construction */
The sv_magic function uses C<how> to determine which, if any, predefined
"Magic Virtual Table" should be assigned to the C<mg_virtual> field.
-See the L<Magic Virtual Tables> section below. The C<how> argument is also
+See the L</Magic Virtual Tables> section below. The C<how> argument is also
stored in the C<mg_type> field. The value of
C<how> should be chosen from the set of macros
C<PERL_MAGIC_foo> found in F<perl.h>. Note that before
the tie methods. Lastly it ties the two hashes together, and returns a
reference to the new tied hash. Note that the code below does NOT call the
TIEHASH method in the MyTie class -
-see L<Calling Perl Routines from within C Programs> for details on how
+see L</Calling Perl Routines from within C Programs> for details on how
to do this.
SV*
=item C<SAVEFREESV(SV *sv)>
-The refcount of C<sv> would be decremented at the end of
+The refcount of C<sv> will be decremented at the end of
I<pseudo-block>. This is similar to C<sv_2mortal> in that it is also a
mechanism for doing a delayed C<SvREFCNT_dec>. However, while C<sv_2mortal>
extends the lifetime of C<sv> until the beginning of the next statement,
not constantly freed/created.
Each of the targets is created only once (but see
-L<Scratchpads and recursion> below), and when an opcode needs to put
+L</Scratchpads and recursion> below), and when an opcode needs to put
an integer, a double, or a string on stack, it just sets the
corresponding parts of its I<target> and puts the I<target> on stack.
If you are printing addresses of pointers, use UVxf combined
with PTR2UV(), do not use %lx or %p.
+=head2 Formatted Printing of Size_t and SSize_t
+
+The most general way to do this is to cast them to a UV or IV, and
+print as in the
+L<previous section|/Formatted Printing of IVs, UVs, and NVs>.
+
+But if you're using C<PerlIO_printf()>, it's less typing and visual
+clutter to use the C<"%z"> length modifier (for I<siZe>):
+
+ PerlIO_printf("STRLEN is %zu\n", len);
+
+This modifier is not portable, so its use should be restricted to
+C<PerlIO_printf()>.
+
=head2 Pointer-To-Integer and Integer-To-Pointer
Because pointer size does not necessarily equal integer size,
=for apidoc sv_setiv
Copies an integer into the given SV. Does not handle 'set' magic. See
- C<sv_setiv_mg>.
+ L<perlapi/sv_setiv_mg>.
=cut
*/
The main division in the context struct is between a substitution scope
(C<CXt_SUBST>) and block scopes, which are everything else. The former is
-just used to while executing C<s///e>, and won't be discussed further
+just used while executing C<s///e>, and won't be discussed further
here.
All the block scope types share a common base, which corresponds to
following shows a simplified and stripped-down example of a non-XS call,
along with comments showing roughly what each function does.
- dMARK;
- U8 gimme = GIMME_V;
- bool hasargs = cBOOL(PL_op->op_flags & OPf_STACKED);
- OP *retop = PL_op->op_next;
- I32 old_ss_ix = PL_savestack_ix;
- CV *cv = ....;
+ dMARK;
+ U8 gimme = GIMME_V;
+ bool hasargs = cBOOL(PL_op->op_flags & OPf_STACKED);
+ OP *retop = PL_op->op_next;
+ I32 old_ss_ix = PL_savestack_ix;
+ CV *cv = ....;
- /* ... make mortal copies of stack args which are PADTMPs here ... */
+ /* ... make mortal copies of stack args which are PADTMPs here ... */
- /* ... do any additional savestack pushes here ... */
+ /* ... do any additional savestack pushes here ... */
- /* Now push a new context entry of type 'CXt_SUB'; initially just
- * doing the actions common to all block types: */
+ /* Now push a new context entry of type 'CXt_SUB'; initially just
+ * doing the actions common to all block types: */
- cx = cx_pushblock(CXt_SUB, gimme, MARK, old_ss_ix);
+ cx = cx_pushblock(CXt_SUB, gimme, MARK, old_ss_ix);
- /* this does (approximately):
- CXINC; /* cxstack_ix++ (grow if necessary) */
- cx = CX_CUR(); /* and get the address of new frame */
- cx->cx_type = CXt_SUB;
- cx->blk_gimme = gimme;
- cx->blk_oldsp = MARK - PL_stack_base;
- cx->blk_oldsaveix = old_ss_ix;
- cx->blk_oldcop = PL_curcop;
- cx->blk_oldmarksp = PL_markstack_ptr - PL_markstack;
- cx->blk_oldscopesp = PL_scopestack_ix;
- cx->blk_oldpm = PL_curpm;
- cx->blk_old_tmpsfloor = PL_tmps_floor;
+ /* this does (approximately):
+ CXINC; /* cxstack_ix++ (grow if necessary) */
+ cx = CX_CUR(); /* and get the address of new frame */
+ cx->cx_type = CXt_SUB;
+ cx->blk_gimme = gimme;
+ cx->blk_oldsp = MARK - PL_stack_base;
+ cx->blk_oldsaveix = old_ss_ix;
+ cx->blk_oldcop = PL_curcop;
+ cx->blk_oldmarksp = PL_markstack_ptr - PL_markstack;
+ cx->blk_oldscopesp = PL_scopestack_ix;
+ cx->blk_oldpm = PL_curpm;
+ cx->blk_old_tmpsfloor = PL_tmps_floor;
- PL_tmps_floor = PL_tmps_ix;
- */
+ PL_tmps_floor = PL_tmps_ix;
+ */
- /* then update the new context frame with subroutine-specific info,
- * such as the CV about to be executed: */
+ /* then update the new context frame with subroutine-specific info,
+ * such as the CV about to be executed: */
- cx_pushsub(cx, cv, retop, hasargs);
+ cx_pushsub(cx, cv, retop, hasargs);
- /* this does (approximately):
- cx->blk_sub.cv = cv;
- cx->blk_sub.olddepth = CvDEPTH(cv);
- cx->blk_sub.prevcomppad = PL_comppad;
- cx->cx_type |= (hasargs) ? CXp_HASARGS : 0;
- cx->blk_sub.retop = retop;
- SvREFCNT_inc_simple_void_NN(cv);
- */
+ /* this does (approximately):
+ cx->blk_sub.cv = cv;
+ cx->blk_sub.olddepth = CvDEPTH(cv);
+ cx->blk_sub.prevcomppad = PL_comppad;
+ cx->cx_type |= (hasargs) ? CXp_HASARGS : 0;
+ cx->blk_sub.retop = retop;
+ SvREFCNT_inc_simple_void_NN(cv);
+ */
Note that C<cx_pushblock()> sets two new floors: for the args stack (to
C<MARK>) and the temps stack (to C<PL_tmps_ix>). While executing at this
Here is a typical example of context popping, as found in C<pp_leavesub>
(simplified slightly):
- U8 gimme;
- PERL_CONTEXT *cx;
- SV **oldsp;
- OP *retop;
+ U8 gimme;
+ PERL_CONTEXT *cx;
+ SV **oldsp;
+ OP *retop;
- cx = CX_CUR();
+ cx = CX_CUR();
- gimme = cx->blk_gimme;
- oldsp = PL_stack_base + cx->blk_oldsp; /* last arg of previous frame */
+ gimme = cx->blk_gimme;
+ oldsp = PL_stack_base + cx->blk_oldsp; /* last arg of previous frame */
- if (gimme == G_VOID)
- PL_stack_sp = oldsp;
- else
- leave_adjust_stacks(oldsp, oldsp, gimme, 0);
+ if (gimme == G_VOID)
+ PL_stack_sp = oldsp;
+ else
+ leave_adjust_stacks(oldsp, oldsp, gimme, 0);
- CX_LEAVE_SCOPE(cx);
- cx_popsub(cx);
- cx_popblock(cx);
- retop = cx->blk_sub.retop;
- CX_POP(cx);
+ CX_LEAVE_SCOPE(cx);
+ cx_popsub(cx);
+ cx_popblock(cx);
+ retop = cx->blk_sub.retop;
+ CX_POP(cx);
- return retop;
+ return retop;
The steps above are in a very specific order, designed to be the reverse
order of when the context was pushed. The first thing to do is to copy
https://perl5.git.perl.org / perl5.git / blobdiff