| blob | 7ca7315615e892b9eb96bb6d03f7e59c5b03f535 |
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4 <head>
8 </head>
13 <big><strong><span class="block"> perlguts - Introduction to the Perl API</span></strong></big>
14 </td></tr>
15 </table>
18 <!-- INDEX BEGIN -->
20 <ul>
25 <ul>
37 <li><a href="#blessed_references_and_class_objects">Blessed References and Class Objects</a></li>
46 <li><a href="#understanding_the_magic_of_tied_hashes_and_arrays">Understanding the Magic of Tied Hashes and Arrays</a></li>
48 </ul>
51 <ul>
54 <li><a href="#calling_perl_routines_from_within_c_programs">Calling Perl Routines from within C Programs</a></li>
56 <ul>
61 </ul>
67 </ul>
70 <ul>
77 <li><a href="#compile_pass_3__peephole_optimization">Compile pass 3: peephole optimization</a></li>
79 </ul>
81 <li><a href="#examining_internal_data_structures_with_the_dump_functions">Examining internal data structures with the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_dump"><code>dump</code></a> functions</a></li>
82 <li><a href="#how_multiple_interpreters_and_concurrency_are_supported">How multiple interpreters and concurrency are supported</a></li>
83 <ul>
85 <li><a href="#background_and_perl_implicit_context">Background and PERL_IMPLICIT_CONTEXT</a></li>
88 <li><a href="#should_i_do_anything_special_if_i_call_perl_from_multiple_threads">Should I do anything special if I call perl from multiple threads?</a></li>
90 </ul>
93 <ul>
95 <li><a href="#formatted_printing_of_ivs__uvs__and_nvs">Formatted Printing of IVs, UVs, and NVs</a></li>
96 <li><a href="#pointertointeger_and_integertopointer">Pointer-To-Integer and Integer-To-Pointer</a></li>
99 </ul>
102 <ul>
106 <li><a href="#how_does_utf8_represent_unicode_characters">How does UTF-8 represent Unicode characters?</a></li>
109 <li><a href="#is_there_anything_else_i_need_to_know">Is there anything else I need to know?</a></li>
110 </ul>
115 </ul>
116 <!-- INDEX END -->
118 <hr />
119 <p>
120 </p>
123 <p>
124 </p>
125 <hr />
127 <p>This document attempts to describe how to use the Perl API, as well as
128 to provide some info on the basic workings of the Perl core. It is far
129 from complete and probably contains many errors. Please refer any
130 questions or comments to the author below.</p>
131 <p>
132 </p>
133 <hr />
135 <p>
136 </p>
139 <pre>
140 SV Scalar Value
141 AV Array Value
142 HV Hash Value</pre>
144 <p>
145 </p>
147 <p>Perl uses a special typedef IV which is a simple signed integer type that is
148 guaranteed to be large enough to hold a pointer (as well as an integer).
149 Additionally, there is the UV, which is simply an unsigned IV.</p>
150 <p>Perl also uses two special typedefs, I32 and I16, which will always be at
154 <p>
155 </p>
157 <p>An SV can be created and loaded with one command. There are five types of
158 values that can be loaded: an integer value (IV), an unsigned integer
159 value (UV), a double (NV), a string (PV), and another scalar (SV).</p>
161 <pre>
162 SV* newSViv(IV);
163 SV* newSVuv(UV);
164 SV* newSVnv(double);
165 SV* newSVpv(const char*, STRLEN);
166 SV* newSVpvn(const char*, STRLEN);
167 SV* newSVpvf(const char*, ...);
168 SV* newSVsv(SV*);</pre>
171 any string that perl can handle.</p>
172 <p>In the unlikely case of a SV requiring more complex initialisation, you
174 type NULL is returned, else an SV of type PV is returned with len + 1 (for
175 the NUL) bytes of storage allocated, accessible via SvPVX. In both cases
176 the SV has value undef.</p>
177 <pre>
178 SV *sv = newSV(0); /* no storage allocated */
181 <pre>
182 void sv_setiv(SV*, IV);
183 void sv_setuv(SV*, UV);
184 void sv_setnv(SV*, double);
185 void sv_setpv(SV*, const char*);
186 void sv_setpvn(SV*, const char*, STRLEN)
187 void sv_setpvf(SV*, const char*, ...);
188 void sv_vsetpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool *);
189 void sv_setsv(SV*, SV*);</pre>
190 <p>Notice that you can choose to specify the length of the string to be
191 assigned by using <code>sv_setpvn</code>, <code>newSVpvn</code>, or <code>newSVpv</code>, or you may
195 string terminating with a NUL character.</p>
197 formatted output becomes the value.</p>
198 <p><code>sv_vsetpvfn</code> is an analogue of <code>vsprintf</code>, but it allows you to specify
199 either a pointer to a variable argument list or the address and length of
200 an array of SVs. The last argument points to a boolean; on return, if that
201 boolean is true, then locale-specific information has been used to format
202 the string, and the string's contents are therefore untrustworthy (see
203 <a href="file://C|\msysgit\mingw\html/pod/perlsec.html">the perlsec manpage</a>). This pointer may be NULL if that information is not
204 important. Note that this function requires you to specify the length of
205 the format.</p>
207 that have ``magic''. See <a href="#magic_virtual_tables">Magic Virtual Tables</a> later in this document.</p>
208 <p>All SVs that contain strings should be terminated with a NUL character.
209 If it is not NUL-terminated there is a risk of
210 core dumps and corruptions from code which passes the string to C
211 functions or system calls which expect a NUL-terminated string.
212 Perl's own functions typically add a trailing NUL for this reason.
213 Nevertheless, you should be very careful when you pass a string stored
214 in an SV to a C function or system call.</p>
216 <pre>
217 SvIV(SV*)
218 SvUV(SV*)
219 SvNV(SV*)
220 SvPV(SV*, STRLEN len)
221 SvPV_nolen(SV*)</pre>
222 <p>which will automatically coerce the actual scalar type into an IV, UV, double,
223 or string.</p>
225 variable <code>len</code> (this is a macro, so you do <em>not</em> use <code>&len</code>). If you do
229 be accessed in thread-local storage in threaded Perl. In any case, remember
230 that Perl allows arbitrary strings of data that may both contain NULs and
231 might not be terminated by a NUL.</p>
233 len);</code>. It might work with your compiler, but it won't work for everyone.
234 Break this sort of statement up into separate assignments:</p>
235 <pre>
236 SV *s;
237 STRLEN len;
238 char * ptr;
239 ptr = SvPV(s, len);
240 foo(ptr, len);</pre>
242 <pre>
243 SvTRUE(SV*)</pre>
244 <p>Although Perl will automatically grow strings for you, if you need to force
245 Perl to allocate more memory for your SV, you can use the macro</p>
246 <pre>
247 SvGROW(SV*, STRLEN newlen)</pre>
248 <p>which will determine if more memory needs to be allocated. If so, it will
250 decrease, the allocated memory of an SV and that it does not automatically
251 add a byte for the a trailing NUL (perl's own string functions typically do
253 <p>If you have an SV and want to know what kind of data Perl thinks is stored
254 in it, you can use the following macros to check the type of SV you have.</p>
255 <pre>
256 SvIOK(SV*)
257 SvNOK(SV*)
258 SvPOK(SV*)</pre>
259 <p>You can get and set the current length of the string stored in an SV with
260 the following macros:</p>
261 <pre>
262 SvCUR(SV*)
263 SvCUR_set(SV*, I32 val)</pre>
264 <p>You can also get a pointer to the end of the string stored in the SV
265 with the macro:</p>
266 <pre>
267 SvEND(SV*)</pre>
270 you can use the following functions:</p>
271 <pre>
272 void sv_catpv(SV*, const char*);
273 void sv_catpvn(SV*, const char*, STRLEN);
274 void sv_catpvf(SV*, const char*, ...);
275 void sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
276 void sv_catsv(SV*, SV*);</pre>
277 <p>The first function calculates the length of the string to be appended by
281 You can specify the address and length of an array of SVs instead of the
282 va_list argument. The fifth function extends the string stored in the first
283 SV with the string stored in the second SV. It also forces the second SV
284 to be interpreted as a string.</p>
286 have ``magic''. See <a href="#magic_virtual_tables">Magic Virtual Tables</a> later in this document.</p>
287 <p>If you know the name of a scalar variable, you can get a pointer to its SV
288 by using the following:</p>
289 <pre>
292 <p>If you want to know if this variable (or any other SV) is actually <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_defined"><code>defined</code></a>,
293 you can call:</p>
294 <pre>
295 SvOK(SV*)</pre>
296 <p>The scalar <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> value is stored in an SV instance called <code>PL_sv_undef</code>.</p>
299 when interfacing Perl code, it'll work correctly for:</p>
300 <pre>
301 foo(undef);</pre>
303 <pre>
304 $x = undef;
305 foo($x);</pre>
308 AVs or HVs (see <a href="#avs__hvs_and_undefined_values">AVs, HVs and undefined values</a>).</p>
309 <p>There are also the two values <code>PL_sv_yes</code> and <code>PL_sv_no</code>, which contain
312 <p>Do not be fooled into thinking that <code>(SV *) 0</code> is the same as <code>&PL_sv_undef</code>.
313 Take this code:</p>
314 <pre>
315 SV* sv = (SV*) 0;
316 if (I-am-to-return-a-real-value) {
317 sv = sv_2mortal(newSViv(42));
318 }
321 return a real value, or undef otherwise. Instead it has returned a NULL
322 pointer which, somewhere down the line, will cause a segmentation violation,
324 first line and all will be well.</p>
326 call is not necessary (see <a href="#reference_counts_and_mortality">Reference Counts and Mortality</a>).</p>
327 <p>
328 </p>
331 from the beginning of a string; you give it an SV and a pointer to
332 somewhere inside the PV, and it discards everything before the
333 pointer. The efficiency comes by means of a little hack: instead of
335 (offset OK) to signal to other functions that the offset hack is in
336 effect, and it puts the number of bytes chopped off into the IV field
339 <p>Hence, at this point, the start of the buffer that we allocated lives
341 into the middle of this allocated storage.</p>
343 <pre>
346 REFCNT = 1
347 FLAGS = (POK,OOK,pPOK)
348 IV = 1 (OFFSET)
350 CUR = 4
354 portion of the string between the ``real'' and the ``fake'' beginnings is
356 the fake beginning, not the real one.</p>
357 <p>Something similar to the offset hack is performed on AVs to enable
358 efficient shifting and splicing off the beginning of the array; while
361 usually the same, but a <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_shift"><code>shift</code></a> operation can be carried out by
362 increasing <code>AvARRAY</code> by one and decreasing <code>AvFILL</code> and <code>AvLEN</code>.
363 Again, the location of the real start of the C array only comes into
365 <p>
366 </p>
368 <p>Recall that the usual method of determining the type of scalar you have is
371 macros will do the appropriate conversion of string to integer/double or
372 integer/double to string.</p>
374 pointer in an SV, you can use the following three macros instead:</p>
375 <pre>
376 SvIOKp(SV*)
377 SvNOKp(SV*)
378 SvPOKp(SV*)</pre>
379 <p>These will tell you if you truly have an integer, double, or string pointer
380 stored in your SV. The ``p'' stands for private.</p>
381 <p>The are various ways in which the private and public flags may differ.
382 For example, a tied SV may have a valid underlying value in the IV slot
383 (so SvIOKp is true), but the data should be accessed via the FETCH
384 routine rather than directly, so SvIOK is false. Another is when
385 numeric conversion has occurred and precision has been lost: only the
386 private flag is set on 'lossy' values. So when an NV is converted to an
387 IV with loss, SvIOKp, SvNOKp and SvNOK will be set, while SvIOK wont be.</p>
389 <p>
390 </p>
392 <p>There are two ways to create and load an AV. The first method creates an
393 empty AV:</p>
394 <pre>
395 AV* newAV();</pre>
397 <pre>
398 AV* av_make(I32 num, SV **ptr);</pre>
399 <p>The second argument points to an array containing <code>num</code> <code>SV*</code>'s. Once the
400 AV has been created, the SVs can be destroyed, if so desired.</p>
402 <pre>
403 void av_push(AV*, SV*);
404 SV* av_pop(AV*);
405 SV* av_shift(AV*);
406 void av_unshift(AV*, I32 num);</pre>
408 This routine adds <code>num</code> elements at the front of the array with the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a>
410 to these new elements.</p>
412 <pre>
413 I32 av_len(AV*);
414 SV** av_fetch(AV*, I32 key, I32 lval);
415 SV** av_store(AV*, I32 key, SV* val);</pre>
417 like $#array in Perl). If the array is empty, -1 is returned. The
418 <code>av_fetch</code> function returns the value at index <code>key</code>, but if <code>lval</code>
420 The <code>av_store</code> function stores the value <code>val</code> at index <code>key</code>, and does
423 have to decrement the reference count to avoid a memory leak. Note that
424 <code>av_fetch</code> and <code>av_store</code> both return <code>SV**</code>'s, not <code>SV*</code>'s as their
425 return value.</p>
426 <pre>
427 void av_clear(AV*);
428 void av_undef(AV*);
429 void av_extend(AV*, I32 key);</pre>
432 delete all the elements in the array plus the array itself. The
433 <code>av_extend</code> function extends the array so that it contains at least <code>key+1</code>
435 then nothing is done.</p>
436 <p>If you know the name of an array variable, you can get a pointer to its AV
437 by using the following:</p>
438 <pre>
441 <p>See <a href="#understanding_the_magic_of_tied_hashes_and_arrays">Understanding the Magic of Tied Hashes and Arrays</a> for more
442 information on how to use the array access functions on tied arrays.</p>
443 <p>
444 </p>
447 <pre>
448 HV* newHV();</pre>
450 <pre>
451 SV** hv_store(HV*, const char* key, U32 klen, SV* val, U32 hash);
452 SV** hv_fetch(HV*, const char* key, U32 klen, I32 lval);</pre>
458 indicates whether this fetch is actually a part of a store operation, in
459 which case a new undefined value will be added to the HV with the supplied
461 <p>Remember that <code>hv_store</code> and <code>hv_fetch</code> return <code>SV**</code>'s and not just
463 value. However, you should check to make sure that the return value is
464 not NULL before dereferencing it.</p>
466 <pre>
467 bool hv_exists(HV*, const char* key, U32 klen);
468 SV* hv_delete(HV*, const char* key, U32 klen, I32 flags);</pre>
469 <p>If <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_flags"><code>flags</code></a> does not include the <code>G_DISCARD</code> flag then <code>hv_delete</code> will
470 create and return a mortal copy of the deleted value.</p>
472 <pre>
473 void hv_clear(HV*);
474 void hv_undef(HV*);</pre>
477 both the entries and the hash table itself.</p>
478 <p>Perl keeps the actual data in linked list of structures with a typedef of HE.
479 These contain the actual key and value pointers (plus extra administrative
482 specified below.</p>
483 <pre>
484 I32 hv_iterinit(HV*);
485 /* Prepares starting point to traverse hash table */
486 HE* hv_iternext(HV*);
487 /* Get the next entry, and return a pointer to a
488 structure that has both the key and value */
489 char* hv_iterkey(HE* entry, I32* retlen);
490 /* Get the key from an HE structure and also return
491 the length of the key string */
492 SV* hv_iterval(HV*, HE* entry);
493 /* Return an SV pointer to the value of the HE
494 structure */
495 SV* hv_iternextsv(HV*, char** key, I32* retlen);
496 /* This convenience routine combines hv_iternext,
497 hv_iterkey, and hv_iterval. The key and retlen
498 arguments are return values for the key and its
499 length. The value is returned in the SV* argument */</pre>
500 <p>If you know the name of a hash variable, you can get a pointer to its HV
501 by using the following:</p>
502 <pre>
506 <pre>
507 hash = 0;
508 while (klen--)
509 hash = (hash * 33) + *key++;
512 lower bits in the resulting hash value.</p>
513 <p>See <a href="#understanding_the_magic_of_tied_hashes_and_arrays">Understanding the Magic of Tied Hashes and Arrays</a> for more
514 information on how to use the hash access functions on tied hashes.</p>
515 <p>
516 </p>
519 <pre>
520 HE* hv_fetch_ent (HV* tb, SV* key, I32 lval, U32 hash);
521 HE* hv_store_ent (HV* tb, SV* key, SV* val, U32 hash);</pre>
522 <pre>
523 bool hv_exists_ent (HV* tb, SV* key, U32 hash);
524 SV* hv_delete_ent (HV* tb, SV* key, I32 flags, U32 hash);</pre>
525 <pre>
526 SV* hv_iterkeysv (HE* entry);</pre>
528 of extension code that deals with hash structures. These functions
530 you to stringify the keys (unlike the previous set of functions).</p>
532 use more efficient (since the hash number for a particular string
533 doesn't have to be recomputed every time). See <a href="file://C|\msysgit\mingw\html/pod/perlapi.html">the perlapi manpage</a> for detailed
534 descriptions.</p>
535 <p>The following macros must always be used to access the contents of hash
536 entries. Note that the arguments to these macros must be simple
537 variables, since they may get evaluated more than once. See
538 <a href="file://C|\msysgit\mingw\html/pod/perlapi.html">the perlapi manpage</a> for detailed descriptions of these macros.</p>
539 <pre>
540 HePV(HE* he, STRLEN len)
541 HeVAL(HE* he)
542 HeHASH(HE* he)
543 HeSVKEY(HE* he)
544 HeSVKEY_force(HE* he)
545 HeSVKEY_set(HE* he, SV* sv)</pre>
546 <p>These two lower level macros are defined, but must only be used when
548 <pre>
549 HeKEY(HE* he)
550 HeKLEN(HE* he)</pre>
553 If these functions return a NULL value, the caller will usually have to
555 <p>
556 </p>
558 <p>Sometimes you have to store undefined values in AVs or HVs. Although
559 this may be a rare case, it can be tricky. That's because you're
562 <pre>
563 AV *av = newAV();
566 <pre>
567 my @av;
570 for indicating that an array element has not yet been initialized.
572 false for the array generated by the XS code.</p>
574 <pre>
576 <p>This will indeed make the value <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a>, but if you try to modify
578 <pre>
579 Modification of non-creatable hash value attempted</pre>
581 in restricted hashes. This caused such hash entries not to appear
582 when iterating over the hash or when checking for the keys
586 will give you the following error:</p>
587 <pre>
588 Modification of a read-only value attempted</pre>
589 <p>To make a long story short, you can use the special variables
590 <code>&PL_sv_undef</code>, <code>&PL_sv_true</code> and <code>&PL_sv_false</code> with AVs and
591 HVs, but you have to make sure you know what you're doing.</p>
592 <p>Generally, if you want to store an undefined value in an AV
595 <pre>
598 <p>
599 </p>
601 <p>References are a special type of scalar that point to other data types
602 (including references).</p>
604 <pre>
605 SV* newRV_inc((SV*) thing);
606 SV* newRV_noinc((SV*) thing);</pre>
607 <p>The <code>thing</code> argument can be any of an <code>SV*</code>, <code>AV*</code>, or <code>HV*</code>. The
611 <p>Once you have a reference, you can use the following macro to dereference
612 the reference:</p>
613 <pre>
614 SvRV(SV*)</pre>
618 <pre>
619 SvROK(SV*)</pre>
620 <p>To discover what type of value the reference refers to, use the following
621 macro and then check the return value.</p>
622 <pre>
623 SvTYPE(SvRV(SV*))</pre>
625 <pre>
626 SVt_IV Scalar
627 SVt_NV Scalar
628 SVt_PV Scalar
629 SVt_RV Scalar
630 SVt_PVAV Array
631 SVt_PVHV Hash
632 SVt_PVCV Code
633 SVt_PVGV Glob (possible a file handle)
634 SVt_PVMG Blessed or Magical Scalar</pre>
635 <pre>
636 See the sv.h header file for more details.</pre>
637 <p>
638 </p>
639 <h2><a name="blessed_references_and_class_objects">Blessed References and Class Objects</a></h2>
640 <p>References are also used to support object-oriented programming. In perl's
641 OO lexicon, an object is simply a reference that has been blessed into a
642 package (or class). Once blessed, the programmer may now use the reference
643 to access the various methods in the class.</p>
645 <pre>
646 SV* sv_bless(SV* sv, HV* stash);</pre>
648 specifies which class the reference will belong to. See
649 <a href="#stashes_and_globs">Stashes and Globs</a> for information on converting class names into stashes.</p>
651 <p>Upgrades rv to reference if not already one. Creates new SV for rv to
653 class. SV is returned.</p>
654 <pre>
655 SV* newSVrv(SV* rv, const char* classname);</pre>
656 <p>Copies integer, unsigned integer or double into an SV whose reference is <code>rv</code>. SV is blessed
658 <pre>
659 SV* sv_setref_iv(SV* rv, const char* classname, IV iv);
660 SV* sv_setref_uv(SV* rv, const char* classname, UV uv);
661 SV* sv_setref_nv(SV* rv, const char* classname, NV iv);</pre>
664 <pre>
665 SV* sv_setref_pv(SV* rv, const char* classname, PV iv);</pre>
668 <pre>
669 SV* sv_setref_pvn(SV* rv, const char* classname, PV iv, STRLEN length);</pre>
670 <p>Tests whether the SV is blessed into the specified class. It does not
671 check inheritance relationships.</p>
672 <pre>
673 int sv_isa(SV* sv, const char* name);</pre>
675 <pre>
676 int sv_isobject(SV* sv);</pre>
677 <p>Tests whether the SV is derived from the specified class. SV can be either
678 a reference to a blessed object or a string containing a class name. This
680 <pre>
681 bool sv_derived_from(SV* sv, const char* name);</pre>
682 <p>To check if you've got an object derived from a specific class you have
683 to write:</p>
684 <pre>
686 <p>
687 </p>
689 <p>To create a new Perl variable with an undef value which can be accessed from
690 your Perl script, use the following routines, depending on the variable type.</p>
691 <pre>
695 <p>Notice the use of TRUE as the second parameter. The new variable can now
696 be set, using the routines appropriate to the data type.</p>
697 <p>There are additional macros whose values may be bitwise OR'ed with the
699 <dl>
702 <dd>
704 </dd>
705 <dd>
706 <pre>
708 </dd>
709 <dd>
711 </dd>
712 </li>
715 <dd>
717 </dd>
718 <dd>
719 <pre>
721 </dd>
722 <dd>
724 </dd>
725 </li>
726 </dl>
727 <p>If you do not specify a package name, the variable is created in the current
728 package.</p>
729 <p>
730 </p>
732 <p>Perl uses a reference count-driven garbage collection mechanism. SVs,
733 AVs, or HVs (xV for short in the following) start their life with a
735 then it will be destroyed and its memory made available for reuse.</p>
736 <p>This normally doesn't happen at the Perl level unless a variable is
737 undef'ed or the last variable holding a reference to it is changed or
738 overwritten. At the internal level, however, reference counts can be
739 manipulated with the following macros:</p>
740 <pre>
741 int SvREFCNT(SV* sv);
742 SV* SvREFCNT_inc(SV* sv);
743 void SvREFCNT_dec(SV* sv);</pre>
744 <p>However, there is one other function which manipulates the reference
746 creates a reference to the specified argument. As a side effect,
747 it increments the argument's reference count. If this is not what
749 <p>For example, imagine you want to return a reference from an XSUB function.
750 Inside the XSUB routine, you create an SV which initially has a reference
752 This returns the reference as a new SV, but the reference count of the
754 return the reference from the XSUB routine and forget about the SV.
755 But Perl hasn't! Whenever the returned reference is destroyed, the
756 reference count of the original SV is decreased to one and nothing happens.
757 The SV will hang around without any way to access it until Perl itself
758 terminates. This is a memory leak.</p>
761 the reference count of the SV will go to zero and it will be destroyed,
762 stopping any memory leak.</p>
763 <p>There are some convenience functions available that can help with the
764 destruction of xVs. These functions introduce the concept of ``mortality''.
765 An xV that is mortal has had its reference count marked to be decremented,
766 but not actually decremented, until ``a short time later''. Generally the
767 term ``short time later'' means a single Perl statement, such as a call to
768 an XSUB function. The actual determinant for when mortal xVs have their
769 reference count decremented depends on two macros, SAVETMPS and FREETMPS.
770 See <a href="file://C|\msysgit\mingw\html/pod/perlcall.html">the perlcall manpage</a> and <a href="file://C|\msysgit\mingw\html/pod/perlxs.html">the perlxs manpage</a> for more details on these macros.</p>
772 However, if you mortalize a variable twice, the reference count will
773 later be decremented twice.</p>
774 <p>``Mortal'' SVs are mainly used for SVs that are placed on perl's stack.
775 For example an SV which is created just to pass a number to a called sub
776 is made mortal to have it cleaned up automatically when it's popped off
777 the stack. Similarly, results returned by XSUBs (which are pushed on the
778 stack) are often made mortal.</p>
780 <pre>
781 SV* sv_newmortal()
782 SV* sv_2mortal(SV*)
783 SV* sv_mortalcopy(SV*)</pre>
784 <p>The first call creates a mortal SV (with no value), the second converts an existing
786 third creates a mortal copy of an existing SV.
789 <pre>
790 SV *tmp = sv_newmortal();
791 sv_setiv(tmp, an_integer);</pre>
793 <pre>
794 SV *tmp = sv_2mortal(newSViv(an_integer));</pre>
795 <p>You should be careful about creating mortal variables. Strange things
796 can happen if you make the same value mortal within multiple contexts,
797 or if you make a variable mortal multiple times. Thinking of ``Mortalization''
800 to survive its use on the stack you need not do any mortalization.
803 <p>The mortal routines are not just for SVs -- AVs and HVs can be
806 <p>
807 </p>
810 within a package. Each key of the stash is a symbol
811 name (shared by all the different types of objects that have the same
812 name), and each value in the hash table is a GV (Glob Value). This GV
813 in turn contains references to the various objects of that name,
814 including (but not limited to) the following:</p>
815 <pre>
816 Scalar Value
817 Array Value
818 Hash Value
819 I/O Handle
820 Format
821 Subroutine</pre>
828 <pre>
829 HV* gv_stashpv(const char* name, I32 create)
830 HV* gv_stashsv(SV*, I32 create)</pre>
831 <p>The first function takes a literal string, the second uses the string stored
832 in the SV. Remember that a stash is just a hash table, so you get back an
836 packages, pass their names to <code>gv_stash*v</code>, separated by <code>::</code> as in the Perl
837 language itself.</p>
838 <p>Alternately, if you have an SV that is a blessed reference, you can find
839 out the stash pointer by using:</p>
840 <pre>
841 HV* SvSTASH(SvRV(SV*));</pre>
843 <pre>
844 char* HvNAME(HV* stash);</pre>
845 <p>If you need to bless or re-bless an object you can use the following
846 function:</p>
847 <pre>
848 SV* sv_bless(SV*, HV* stash)</pre>
851 as any other SV.</p>
852 <p>For more information on references and blessings, consult <a href="file://C|\msysgit\mingw\html/pod/perlref.html">the perlref manpage</a>.</p>
853 <p>
854 </p>
856 <p>Scalar variables normally contain only one type of value, an integer,
857 double, pointer, or reference. Perl will automatically convert the
858 actual scalar data from the stored type into the requested type.</p>
859 <p>Some scalar variables contain more than one type of scalar data. For
860 example, the variable <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item___"><code>$!</code></a> contains either the numeric value of <code>errno</code>
862 <p>To force multiple data values into an SV, you must do two things: use the
864 so that Perl will believe it contains more than one type of data. The
865 four macros to set the flags are:</p>
866 <pre>
867 SvIOK_on
868 SvNOK_on
869 SvPOK_on
870 SvROK_on</pre>
873 only the bit for the particular type of data being set, and turns off
874 all the rest.</p>
875 <p>For example, to create a new Perl variable called ``dberror'' that contains
876 both the numeric and descriptive string error values, you could use the
877 following code:</p>
878 <pre>
879 extern int dberror;
880 extern char *dberror_list;</pre>
881 <pre>
883 sv_setiv(sv, (IV) dberror);
884 sv_setpv(sv, dberror_list[dberror]);
885 SvIOK_on(sv);</pre>
888 <p>
889 </p>
891 <p>[This section still under construction. Ignore everything here. Post no
892 bills. Everything not permitted is forbidden.]</p>
893 <p>Any SV may be magical, that is, it has special features that a normal
894 SV does not have. These features are stored in the SV structure in a
896 <pre>
897 struct magic {
898 MAGIC* mg_moremagic;
899 MGVTBL* mg_virtual;
900 U16 mg_private;
901 char mg_type;
902 U8 mg_flags;
903 SV* mg_obj;
904 char* mg_ptr;
905 I32 mg_len;
906 };</pre>
908 <p>
909 </p>
912 <pre>
913 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen);</pre>
915 feature.</p>
918 to the beginning of the linked list of magical features. Any prior entry
919 of the same type of magic is deleted. Note that this can be overridden,
920 and multiple instances of the same type of magic can be associated with an
921 SV.</p>
924 <code>mg_len</code> field and if <code>name</code> is non-null then either a <code>savepvn</code> copy of
925 <code>name</code> or <code>name</code> itself is stored in the <code>mg_ptr</code> field, depending on
927 special case, if <code>(name && namlen == HEf_SVKEY)</code> then <code>name</code> is assumed
931 See the <a href="#magic_virtual_tables">Magic Virtual Tables</a> section below. The <code>how</code> argument is also
934 these macros were added, Perl internals used to directly use character
935 literals, so you may occasionally come across old code or documentation
937 <p>The <code>obj</code> argument is stored in the <code>mg_obj</code> field of the <code>MAGIC</code>
942 <p>See also <code>sv_magicext</code> in <a href="file://C|\msysgit\mingw\html/pod/perlapi.html">the perlapi manpage</a> for a more flexible way to add magic
943 to an SV.</p>
945 <pre>
946 void hv_magic(HV *hv, GV *gv, int how);</pre>
947 <p>This simply calls <code>sv_magic</code> and coerces the <code>gv</code> argument into an <code>SV</code>.</p>
949 <pre>
950 void sv_unmagic(SV *sv, int type);</pre>
951 <p>The <code>type</code> argument should be equal to the <code>how</code> value when the <code>SV</code>
952 was initially made magical.</p>
953 <p>
954 </p>
958 ``Magic Virtual Table'' to handle the various operations that might be
959 applied to that variable.</p>
961 <pre>
962 int (*svt_get)(SV* sv, MAGIC* mg);
963 int (*svt_set)(SV* sv, MAGIC* mg);
964 U32 (*svt_len)(SV* sv, MAGIC* mg);
965 int (*svt_clear)(SV* sv, MAGIC* mg);
966 int (*svt_free)(SV* sv, MAGIC* mg);</pre>
969 structures contain pointers to various routines that perform additional
970 actions depending on which function is being called.</p>
971 <pre>
972 Function pointer Action taken
973 ---------------- ------------
974 svt_get Do something before the value of the SV is retrieved.
975 svt_set Do something after the SV is assigned a value.
976 svt_len Report on the SV's length.
977 svt_clear Clear something the SV represents.
978 svt_free Free any extra storage associated with the SV.</pre>
981 <pre>
985 called. All the various routines for the various magical types begin
987 the Perl API, and may not be exported by the Perl library.</p>
989 <pre>
990 mg_type
991 (old-style char and macro) MGVTBL Type of magic
992 -------------------------- ------ ----------------------------
993 \0 PERL_MAGIC_sv vtbl_sv Special scalar variable
994 A PERL_MAGIC_overload vtbl_amagic %OVERLOAD hash
995 a PERL_MAGIC_overload_elem vtbl_amagicelem %OVERLOAD hash element
996 c PERL_MAGIC_overload_table (none) Holds overload table (AMT)
997 on stash
998 B PERL_MAGIC_bm vtbl_bm Boyer-Moore (fast string search)
999 D PERL_MAGIC_regdata vtbl_regdata Regex match position data
1000 (@+ and @- vars)
1001 d PERL_MAGIC_regdatum vtbl_regdatum Regex match position data
1002 element
1003 E PERL_MAGIC_env vtbl_env %ENV hash
1004 e PERL_MAGIC_envelem vtbl_envelem %ENV hash element
1005 f PERL_MAGIC_fm vtbl_fm Formline ('compiled' format)
1006 g PERL_MAGIC_regex_global vtbl_mglob m//g target / study()ed string
1007 I PERL_MAGIC_isa vtbl_isa @ISA array
1008 i PERL_MAGIC_isaelem vtbl_isaelem @ISA array element
1009 k PERL_MAGIC_nkeys vtbl_nkeys scalar(keys()) lvalue
1010 L PERL_MAGIC_dbfile (none) Debugger %_<filename
1011 l PERL_MAGIC_dbline vtbl_dbline Debugger %_<filename element
1012 m PERL_MAGIC_mutex vtbl_mutex ???
1013 o PERL_MAGIC_collxfrm vtbl_collxfrm Locale collate transformation
1014 P PERL_MAGIC_tied vtbl_pack Tied array or hash
1015 p PERL_MAGIC_tiedelem vtbl_packelem Tied array or hash element
1016 q PERL_MAGIC_tiedscalar vtbl_packelem Tied scalar or handle
1017 r PERL_MAGIC_qr vtbl_qr precompiled qr// regex
1018 S PERL_MAGIC_sig vtbl_sig %SIG hash
1019 s PERL_MAGIC_sigelem vtbl_sigelem %SIG hash element
1020 t PERL_MAGIC_taint vtbl_taint Taintedness
1021 U PERL_MAGIC_uvar vtbl_uvar Available for use by extensions
1022 v PERL_MAGIC_vec vtbl_vec vec() lvalue
1023 V PERL_MAGIC_vstring (none) v-string scalars
1024 w PERL_MAGIC_utf8 vtbl_utf8 UTF-8 length+offset cache
1025 x PERL_MAGIC_substr vtbl_substr substr() lvalue
1027 variable / smart parameter
1028 vivification
1029 * PERL_MAGIC_glob vtbl_glob GV (typeglob)
1030 # PERL_MAGIC_arylen vtbl_arylen Array length ($#ary)
1031 . PERL_MAGIC_pos vtbl_pos pos() lvalue
1032 < PERL_MAGIC_backref vtbl_backref ???
1033 ~ PERL_MAGIC_ext (none) Available for use by extensions</pre>
1034 <p>When an uppercase and lowercase letter both exist in the table, then the
1035 uppercase letter is typically used to represent some kind of composite type
1036 (a list or a hash), and the lowercase letter is used to represent an element
1037 of that composite type. Some internals code makes use of this case
1038 relationship. However, 'v' and 'V' (vec and v-string) are in no way related.</p>
1040 specifically for use by extensions and will not be used by perl itself.
1042 to variables (typically objects). This is especially useful because
1043 there is no way for normal perl code to corrupt this private information
1044 (unlike using extra elements of a hash object).</p>
1045 <p>Similarly, <code>PERL_MAGIC_uvar</code> magic can be used much like <code>tie()</code> to call a
1048 <pre>
1049 struct ufuncs {
1050 I32 (*uf_val)(pTHX_ IV, SV*);
1051 I32 (*uf_set)(pTHX_ IV, SV*);
1052 IV uf_index;
1053 };</pre>
1057 magic is shown below. Note that the ufuncs structure is copied by
1058 sv_magic, so you can safely allocate it on the stack.</p>
1059 <pre>
1060 void
1061 Umagic(sv)
1062 SV *sv;
1063 PREINIT:
1064 struct ufuncs uf;
1065 CODE:
1066 uf.uf_val = &my_get_fn;
1067 uf.uf_set = &my_set_fn;
1068 uf.uf_index = 0;
1072 extra care to avoid conflict. Typically only using the magic on
1073 objects blessed into the same class as the extension is sufficient.
1075 'signature' at the top of the private data area and check that.</p>
1082 obtained from external sources in functions that don't handle magic.
1083 See <a href="file://C|\msysgit\mingw\html/pod/perlapi.html">the perlapi manpage</a> for a description of these functions.
1086 since their implementation handles 'get' magic.</p>
1087 <p>
1088 </p>
1090 <pre>
1091 MAGIC* mg_find(SV*, int type); /* Finds the magic pointer of that type */</pre>
1094 if the SV is not of type SVt_PVMG, Perl may core dump.</p>
1095 <pre>
1096 int mg_copy(SV* sv, SV* nsv, const char* key, STRLEN klen);</pre>
1099 the mg_type field is changed to be the lowercase letter.</p>
1100 <p>
1101 </p>
1102 <h2><a name="understanding_the_magic_of_tied_hashes_and_arrays">Understanding the Magic of Tied Hashes and Arrays</a></h2>
1104 magic type.</p>
1106 access functions requires understanding a few caveats. Some
1107 of these caveats are actually considered bugs in the API, to be fixed
1108 in later releases, and are bracketed with [MAYCHANGE] below. If
1109 you find yourself actually applying such information in this section, be
1110 aware that the behavior may change in the future, umm, without warning.</p>
1111 <p>The perl tie function associates a variable with an object that implements
1112 the various GET, SET, etc methods. To perform the equivalent of the perl
1113 tie function from an XSUB, you must mimic this behaviour. The code below
1114 carries out the necessary steps - firstly it creates a new hash, and then
1115 creates a second hash which it blesses into the class which will implement
1116 the tie methods. Lastly it ties the two hashes together, and returns a
1117 reference to the new tied hash. Note that the code below does NOT call the
1118 TIEHASH method in the MyTie class -
1119 see <a href="#calling_perl_routines_from_within_c_programs">Calling Perl Routines from within C Programs</a> for details on how
1120 to do this.</p>
1121 <pre>
1122 SV*
1123 mytie()
1124 PREINIT:
1125 HV *hash;
1126 HV *stash;
1127 SV *tie;
1128 CODE:
1129 hash = newHV();
1130 tie = newRV_noinc((SV*)newHV());
1132 sv_bless(tie, stash);
1133 hv_magic(hash, (GV*)tie, PERL_MAGIC_tied);
1134 RETVAL = newRV_noinc(hash);
1135 OUTPUT:
1136 RETVAL</pre>
1138 copies the magic of the array onto the value to be ``stored'', using
1140 actually need to be stored in the array. [MAYCHANGE] After a call to
1145 leak. [/MAYCHANGE]</p>
1146 <p>The previous paragraph is applicable verbatim to tied hash access using the
1151 need to be deallocated, as it is already mortal. [MAYCHANGE] But you will
1153 the perl level ``FETCH'' method on the underlying TIE object. Similarly,
1156 method on the TIE object. [/MAYCHANGE]</p>
1157 <p>[MAYCHANGE]
1158 In other words, the array or hash fetch/store functions don't really
1159 fetch and store actual values in the case of tied arrays and hashes. They
1162 do the job of invoking the TIE methods on the underlying objects. Thus
1163 the magic mechanism currently implements a kind of lazy access to arrays
1164 and hashes.</p>
1166 functions requires the user to be aware of whether they are operating on
1167 ``normal'' hashes and arrays, or on their tied variants. The API may be
1168 changed to provide more transparent access to both tied and normal data
1169 types in future versions.
1170 [/MAYCHANGE]</p>
1171 <p>You would do well to understand that the TIEARRAY and TIEHASH interfaces
1172 are mere sugar to invoke some perl method calls while using the uniform hash
1173 and array syntax. The use of this sugar imposes some overhead (typically
1174 about two to four extra opcodes per FETCH/STORE operation, in addition to
1175 the creation of all the mortal variables required to invoke the methods).
1176 This overhead will be comparatively small if the TIE methods are themselves
1177 substantial, but if they are only a few statements long, the overhead
1178 will not be insignificant.</p>
1179 <p>
1180 </p>
1183 <pre>
1184 {
1185 local $var = 2;
1186 ...
1187 }</pre>
1189 <pre>
1190 {
1191 my $oldvar = $var;
1192 $var = 2;
1193 ...
1194 $var = $oldvar;
1195 }</pre>
1196 <p>The biggest difference is that the first construction would
1197 reinstate the initial value of $var, irrespective of how control exits
1198 the block: <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_goto"><code>goto</code></a>, <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_return"><code>return</code></a>, <code>die</code>/<a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_eval"><code>eval</code></a>, etc. It is a little bit
1199 more efficient as well.</p>
1200 <p>There is a way to achieve a similar task from C via Perl API: create a
1202 undone at the end of it, either explicit, or via a non-local exit (via
1204 <code>ENTER</code>/<code>LEAVE</code> macros (see <a href="file://C|\msysgit\mingw\html/pod/perlcall.html#returning_a_scalar">Returning a Scalar in the perlcall manpage</a>).
1205 Such a construct may be created specially for some important localized
1206 task, or an existing one (like boundaries of enclosing Perl
1207 subroutine/block, or an existing pair for freeing TMPs) may be
1208 used. (In the second case the overhead of additional localization must
1209 be almost negligible.) Note that any XSUB is automatically enclosed in
1212 <dl>
1221 <dd>
1222 <p>These macros arrange things to restore the value of integer variable
1224 </dd>
1225 </li>
1230 <dd>
1231 <p>These macros arrange things to restore the value of pointers <a href="#item_s"><code>s</code></a> and
1232 <a href="#item_p"><code>p</code></a>. <a href="#item_s"><code>s</code></a> must be a pointer of a type which survives conversion to
1233 <code>SV*</code> and back, <a href="#item_p"><code>p</code></a> should be able to survive conversion to <code>char*</code>
1234 and back.</p>
1235 </dd>
1236 </li>
1239 <dd>
1242 mechanism for doing a delayed <code>SvREFCNT_dec</code>. However, while <code>sv_2mortal</code>
1244 <a href="#item_savefreesv"><code>SAVEFREESV</code></a> extends it until the end of the enclosing scope. These
1245 lifetimes can be wildly different.</p>
1246 </dd>
1247 <dd>
1249 </dd>
1250 </li>
1253 <dd>
1254 <p>Just like <a href="#item_savefreesv"><code>SAVEFREESV</code></a>, but mortalizes <code>sv</code> at the end of the current
1255 scope instead of decrementing its reference count. This usually has the
1257 live scope has finished executing.</p>
1258 </dd>
1259 </li>
1262 <dd>
1264 </dd>
1265 </li>
1268 <dd>
1269 <p>The chunk of memory which is pointed to by <a href="#item_p"><code>p</code></a> is Safefree()ed at the
1271 </dd>
1272 </li>
1275 <dd>
1278 </dd>
1279 </li>
1280 <dt><strong><a name="item_savedelete"><code>SAVEDELETE(HV *hv, char *key, I32 length)</code></a></strong>
1282 <dd>
1283 <p>The key <code>key</code> of <code>hv</code> is deleted at the end of <em>pseudo-block</em>. The
1285 short-lived storage, the corresponding string may be reallocated like
1286 this:</p>
1287 </dd>
1288 <dd>
1289 <pre>
1290 SAVEDELETE(PL_defstash, savepv(tmpbuf), strlen(tmpbuf));</pre>
1291 </dd>
1292 </li>
1293 <dt><strong><a name="item_savedestructor"><code>SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)</code></a></strong>
1295 <dd>
1296 <p>At the end of <em>pseudo-block</em> the function <a href="#item_f"><code>f</code></a> is called with the
1298 </dd>
1299 </li>
1300 <dt><strong><a name="item_savedestructor_x"><code>SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)</code></a></strong>
1302 <dd>
1303 <p>At the end of <em>pseudo-block</em> the function <a href="#item_f"><code>f</code></a> is called with the
1305 </dd>
1306 </li>
1309 <dd>
1312 </dd>
1313 </li>
1314 </dl>
1315 <p>The following API list contains functions, thus one needs to
1316 provide pointers to the modifiable data explicitly (either C pointers,
1317 or Perlish <code>GV *</code>s). Where the above macros take <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_int"><code>int</code></a>, a similar
1319 <dl>
1322 <dd>
1324 </dd>
1325 </li>
1330 <dd>
1331 <p>Similar to <a href="#item_save_scalar"><code>save_scalar</code></a>, but localize <code>@gv</code> and <code>%gv</code>.</p>
1332 </dd>
1333 </li>
1336 <dd>
1338 <code>ENTER</code>/<code>LEAVE</code> <em>pseudo-block</em> will restore the value of <code>SV</code>
1339 using the stored value.</p>
1340 </dd>
1341 </li>
1342 <dt><strong><a name="item_save_list"><code>void save_list(SV **sarg, I32 maxsarg)</code></a></strong>
1344 <dd>
1345 <p>A variant of <a href="#item_save_item"><code>save_item</code></a> which takes multiple arguments via an array
1347 </dd>
1348 </li>
1351 <dd>
1352 <p>Similar to <a href="#item_save_scalar"><code>save_scalar</code></a>, but will reinstate an <code>SV *</code>.</p>
1353 </dd>
1354 </li>
1359 <dd>
1360 <p>Similar to <a href="#item_save_svref"><code>save_svref</code></a>, but localize <code>AV *</code> and <code>HV *</code>.</p>
1361 </dd>
1362 </li>
1363 </dl>
1366 the containing scope should take a look there too.</p>
1367 <p>
1368 </p>
1369 <hr />
1371 <p>
1372 </p>
1374 <p>The XSUB mechanism is a simple way for Perl programs to access C subroutines.
1375 An XSUB routine will have a stack that contains the arguments from the Perl
1376 program, and a way to map from the Perl data structures to a C equivalent.</p>
1378 the <a href="#item_n"><code>n</code></a>'th stack argument. Argument 0 is the first argument passed in the
1381 <p>Most of the time, output from the C routine can be handled through use of
1382 the RETVAL and OUTPUT directives. However, there are some cases where the
1383 argument stack is not already long enough to handle all the return values.
1385 two, the local time zone's standard and summer time abbreviations.</p>
1386 <p>To handle this situation, the PPCODE directive is used and the stack is
1387 extended using the macro:</p>
1388 <pre>
1389 EXTEND(SP, num);</pre>
1393 macro. The pushed values will often need to be ``mortal'' (See
1395 <pre>
1396 PUSHs(sv_2mortal(newSViv(an_integer)))
1397 PUSHs(sv_2mortal(newSVuv(an_unsigned_integer)))
1398 PUSHs(sv_2mortal(newSVnv(a_double)))
1401 as in:</p>
1402 <pre>
1403 ($standard_abbrev, $summer_abbrev) = POSIX::tzname;</pre>
1404 <p>An alternate (and possibly simpler) method to pushing values on the stack is
1405 to use the macro:</p>
1406 <pre>
1407 XPUSHs(SV*)</pre>
1408 <p>This macro automatically adjust the stack for you, if needed. Thus, you
1410 <p>Despite their suggestions in earlier versions of this document the macros
1413 <a href="#item_m"><code>m(X)PUSH[iunp]</code></a> macros instead; see <a href="#putting_a_c_value_on_perl_stack">Putting a C value on Perl stack</a>.</p>
1414 <p>For more information, consult <a href="file://C|\msysgit\mingw\html/pod/perlxs.html">the perlxs manpage</a> and <a href="file://C|\msysgit\mingw\html/pod/perlxstut.html">the perlxstut manpage</a>.</p>
1415 <p>
1416 </p>
1417 <h2><a name="calling_perl_routines_from_within_c_programs">Calling Perl Routines from within C Programs</a></h2>
1418 <p>There are four routines that can be used to call a Perl subroutine from
1419 within a C program. These four are:</p>
1420 <pre>
1421 I32 call_sv(SV*, I32);
1422 I32 call_pv(const char*, I32);
1423 I32 call_method(const char*, I32);
1424 I32 call_argv(const char*, I32, register char**);</pre>
1426 contains either the name of the Perl subroutine to be called, or a
1427 reference to the subroutine. The second argument consists of flags
1428 that control the context in which the subroutine is called, whether
1429 or not the subroutine is being passed arguments, how errors should be
1430 trapped, and how to treat return values.</p>
1431 <p>All four routines return the number of arguments that the subroutine returned
1432 on the Perl stack.</p>
1434 but those names are now deprecated; macros of the same name are provided for
1435 compatibility.</p>
1437 must manipulate the Perl stack. These include the following macros and
1438 functions:</p>
1439 <pre>
1440 dSP
1441 SP
1442 PUSHMARK()
1443 PUTBACK
1444 SPAGAIN
1445 ENTER
1446 SAVETMPS
1447 FREETMPS
1448 LEAVE
1449 XPUSH*()
1450 POP*()</pre>
1451 <p>For a detailed description of calling conventions from C to Perl,
1453 <p>
1454 </p>
1456 <p>
1457 </p>
1459 <p>All memory meant to be used with the Perl API functions should be manipulated
1460 using the macros described in this section. The macros provide the necessary
1461 transparency between differences in the actual malloc implementation that is
1462 used within perl.</p>
1463 <p>It is suggested that you enable the version of malloc that is distributed
1464 with Perl. It keeps pools of various sizes of unallocated memory in
1465 order to satisfy allocation requests more quickly. However, on some
1466 platforms, it may cause spurious malloc or free errors.</p>
1468 <pre>
1469 Newx(pointer, number, type);
1470 Newxc(pointer, number, type, cast);
1471 Newxz(pointer, number, type);</pre>
1473 point to the newly allocated memory.</p>
1474 <p>The second and third arguments <code>number</code> and <code>type</code> specify how many of
1475 the specified type of data structure should be allocated. The argument
1476 <code>type</code> is passed to <code>sizeof</code>. The final argument to <code>Newxc</code>, <code>cast</code>,
1478 argument.</p>
1479 <p>Unlike the <code>Newx</code> and <code>Newxc</code> macros, the <code>Newxz</code> macro calls <code>memzero</code>
1480 to zero out all the newly allocated memory.</p>
1481 <p>
1482 </p>
1484 <pre>
1485 Renew(pointer, number, type);
1486 Renewc(pointer, number, type, cast);
1487 Safefree(pointer)</pre>
1488 <p>These three macros are used to change a memory buffer size or to free a
1491 ``magic cookie'' argument.</p>
1492 <p>
1493 </p>
1495 <pre>
1496 Move(source, dest, number, type);
1497 Copy(source, dest, number, type);
1498 Zero(dest, number, type);</pre>
1499 <p>These three macros are used to move, copy, or zero out previously allocated
1503 function).</p>
1504 <p>
1505 </p>
1507 <p>The most recent development releases of Perl has been experimenting with
1508 removing Perl's dependency on the ``normal'' standard I/O suite and allowing
1509 other stdio implementations to be used. This involves creating a new
1510 abstraction layer that then calls whichever implementation of stdio Perl
1511 was compiled with. All XSUBs should now use the functions in the PerlIO
1512 abstraction layer and not make any assumptions about what kind of stdio
1513 is being used.</p>
1514 <p>For a complete description of the PerlIO abstraction, consult <a href="file://C|\msysgit\mingw\html/pod/perlapio.html">the perlapio manpage</a>.</p>
1515 <p>
1516 </p>
1518 <p>A lot of opcodes (this is an elementary operation in the internal perl
1519 stack machine) put an SV* on the stack. However, as an optimization
1520 the corresponding SV is (usually) not recreated each time. The opcodes
1522 not constantly freed/created.</p>
1523 <p>Each of the targets is created only once (but see
1524 <a href="#scratchpads_and_recursion">Scratchpads and recursion</a> below), and when an opcode needs to put
1525 an integer, a double, or a string on stack, it just sets the
1528 directly used in some opcodes, as well as indirectly in zillions of
1530 <p>Because the target is reused, you must be careful when pushing multiple
1531 values on the stack. The following code will not do what you think:</p>
1532 <pre>
1533 XPUSHi(10);
1537 At the end of the operation, the stack does not contain the values 10
1540 <p>If you need to push multiple different values then you should either use
1541 the <code>(X)PUSHs</code> macros, or else use the new <a href="#item_m"><code>m(X)PUSH[iunp]</code></a> macros,
1543 SV* on the stack, which, as noted under <a href="#xsubs_and_the_argument_stack">XSUBs and the Argument Stack</a>,
1544 will often need to be ``mortal''. The new <a href="#item_m"><code>m(X)PUSH[iunp]</code></a> macros make
1545 this a little easier to achieve by creating a new mortal for you (via
1548 Thus, instead of writing this to ``fix'' the example above:</p>
1549 <pre>
1550 XPUSHs(sv_2mortal(newSViv(10)))
1553 <pre>
1554 mXPUSHi(10)
1560 <p>
1561 </p>
1564 are created. The answer is that they are created when the current unit --
1565 a subroutine or a file (for opcodes for statements outside of
1566 subroutines) -- is compiled. During this time a special anonymous Perl
1567 array is created, which is called a scratchpad for the current
1568 unit.</p>
1569 <p>A scratchpad keeps SVs which are lexicals for the current unit and are
1570 targets for opcodes. One can deduce that an SV lives on a scratchpad
1574 OPs in the compile tree of the unit can use the same target, if this
1575 would not conflict with the expected life of the temporary.</p>
1576 <p>
1577 </p>
1580 the scratchpad AV. In fact it contains a pointer to an AV of
1581 (initially) one element, and this element is the scratchpad AV. Why do
1582 we need an extra level of indirection?</p>
1584 these can create several execution pointers going into the same
1585 subroutine. For the subroutine-child not write over the temporaries
1586 for the subroutine-parent (lifespan of which covers the call to the
1587 child), the parent and the child should have different
1590 On each entry to the subroutine it is checked that the current
1591 depth of the recursion is not more than the length of this array, and
1592 if it is, new scratchpad is created and pushed into the array.</p>
1593 <p>The <em>target</em>s on this scratchpad are <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a>s, but they are already
1594 marked with correct flags.</p>
1595 <p>
1596 </p>
1597 <hr />
1599 <p>
1600 </p>
1602 <p>Here we describe the internal form your code is converted to by
1603 Perl. Start with a simple example:</p>
1604 <pre>
1605 $a = $b + $c;</pre>
1607 <pre>
1608 assign-to
1609 / \
1610 + $a
1611 / \
1612 $b $c</pre>
1613 <p>(but slightly more complicated). This tree reflects the way Perl
1614 parsed your code, but has nothing to do with the execution order.
1615 There is an additional ``thread'' going through the nodes of the tree
1616 which shows the order of execution of the nodes. In our simplified
1617 example above it looks like:</p>
1618 <pre>
1620 <p>But with the actual compile tree for <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__a"><code>$a = $b + $c</code></a> it is different:
1622 contains more nodes than our simplified example, the execution order
1623 is the same as in our example.</p>
1624 <p>
1625 </p>
1627 <p>If you have your perl compiled for debugging (usually done with
1631 this:</p>
1632 <pre>
1634 TARG = 1
1635 FLAGS = (SCALAR,KIDS)
1636 {
1638 (was rv2sv)
1639 FLAGS = (SCALAR,KIDS)
1640 {
1642 FLAGS = (SCALAR)
1643 GV = main::b
1644 }
1645 }
1646 {
1648 (was rv2sv)
1649 FLAGS = (SCALAR,KIDS)
1650 {
1652 FLAGS = (SCALAR)
1653 GV = main::c
1654 }
1655 }</pre>
1657 not optimized away (one per number in the left column). The immediate
1659 of indentation, thus this listing corresponds to the tree:</p>
1660 <pre>
1661 add
1662 / \
1663 null null
1664 | |
1665 gvsv gvsv</pre>
1669 <p>Each of these nodes represents an op, a fundamental operation inside the
1670 Perl core. The code which implements each operation can be found in the
1674 expect, and so has two children. To accommodate the various different
1675 numbers of children, there are various types of op data structure, and
1676 they link together in different ways.</p>
1689 optimization (see <a href="#compile_pass_2__context_propagation">Compile pass 2: context propagation</a>) it will still
1690 have children in accordance with its former type.</p>
1691 <p>Another way to examine the tree is to use a compiler back-end module, such
1693 <p>
1694 </p>
1698 the first pass of perl compilation.</p>
1699 <p>What makes this pass interesting for perl developers is that some
1700 optimization may be performed on this pass. This is optimization by
1701 so-called ``check routines''. The correspondence between node names
1704 <p>A check routine is called when the node is fully constructed except
1705 for the execution-order thread. Since at this time there are no
1706 back-links to the currently constructed node, one can do most any
1707 operation to the top-level node, including freeing it and/or creating
1708 new nodes above/below it.</p>
1709 <p>The check routine returns the node which should be inserted into the
1710 tree (if the top-level node was not modified, check routine returns
1711 its argument).</p>
1715 <p>
1716 </p>
1718 <p>Immediately after the check routine is called the returned node is
1719 checked for being compile-time executable. If it is (the value is
1721 node with the ``return value'' of the corresponding subtree is
1722 substituted instead. The subtree is deleted.</p>
1723 <p>If constant folding was not performed, the execution-order thread is
1724 created.</p>
1725 <p>
1726 </p>
1728 <p>When a context for a part of compile tree is known, it is propagated
1729 down through the tree. At this time the context can have 5 values
1730 (instead of 2 for runtime context): void, boolean, scalar, list, and
1731 lvalue. In contrast with the pass 1 this pass is processed from top
1732 to bottom: a node's context determines the context for its children.</p>
1733 <p>Additional context-dependent optimizations are performed at this time.
1734 Since at this moment the compile tree contains back-references (via
1735 ``thread'' pointers), nodes cannot be free()d now. To allow
1736 optimized-away nodes at this stage, such nodes are null()ified instead
1737 of free()ing (i.e. their type is changed to OP_NULL).</p>
1738 <p>
1739 </p>
1740 <h2><a name="compile_pass_3__peephole_optimization">Compile pass 3: peephole optimization</a></h2>
1741 <p>After the compile tree for a subroutine (or for an <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_eval"><code>eval</code></a> or a file)
1742 is created, an additional pass over the code is performed. This pass
1743 is neither top-down or bottom-up, but in the execution order (with
1744 additional complications for conditionals). These optimizations are
1745 done in the subroutine peep(). Optimizations performed at this stage
1747 <p>
1748 </p>
1750 <p>The compile tree is executed in a runops function. There are two runops
1753 control over the execution of the compile tree it is possible to provide
1754 your own runops function.</p>
1755 <p>It's probably best to copy one of the existing runops functions and
1756 change it to suit your needs. Then, in the BOOT section of your XS
1757 file, add the line:</p>
1758 <pre>
1759 PL_runops = my_runops;</pre>
1760 <p>This function should be as efficient as possible to keep your programs
1761 running as fast as possible.</p>
1762 <p>
1763 </p>
1764 <hr />
1765 <h1><a name="examining_internal_data_structures_with_the_dump_functions">Examining internal data structures with the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_dump"><code>dump</code></a> functions</a></h1>
1767 functions which produce formatted output of internal data structures.</p>
1771 module should already be familiar with its format.</p>
1776 <p>Other useful functions are <code>Perl_dump_sub</code>, which turns a <code>GV</code> into an
1778 subroutines in a package like so: (Thankfully, these are all xsubs, so
1779 there is no op tree)</p>
1780 <pre>
1781 (gdb) print Perl_dump_packsubs(PL_defstash)</pre>
1782 <pre>
1784 <pre>
1786 <pre>
1788 <pre>
1790 <pre>
1793 the op tree of the main root.</p>
1794 <p>
1795 </p>
1796 <hr />
1797 <h1><a name="how_multiple_interpreters_and_concurrency_are_supported">How multiple interpreters and concurrency are supported</a></h1>
1798 <p>
1799 </p>
1800 <h2><a name="background_and_perl_implicit_context">Background and PERL_IMPLICIT_CONTEXT</a></h2>
1801 <p>The Perl interpreter can be regarded as a closed box: it has an API
1802 for feeding it code or otherwise making it do things, but it also has
1803 functions for its own use. This smells a lot like an object, and
1804 there are ways for you to build Perl so that you can have multiple
1805 interpreters, with one interpreter represented either as a C structure,
1806 or inside a thread-specific structure. These structures contain all
1807 the context, the state of that interpreter.</p>
1808 <p>Two macros control the major Perl build flavors: MULTIPLICITY and
1809 USE_5005THREADS. The MULTIPLICITY build has a C structure
1810 that packages all the interpreter state, and there is a similar thread-specific
1811 data structure under USE_5005THREADS. In both cases,
1812 PERL_IMPLICIT_CONTEXT is also normally defined, and enables the
1813 support for passing in a ``hidden'' first argument that represents all three
1814 data structures.</p>
1815 <p>All this obviously requires a way for the Perl internal functions to be
1816 either subroutines taking some kind of structure as the first
1817 argument, or subroutines taking nothing as the first argument. To
1818 enable these two very different ways of building the interpreter,
1819 the Perl source (as it does in so many other situations) makes heavy
1820 use of macros and subroutine naming conventions.</p>
1821 <p>First problem: deciding which functions will be public API functions and
1823 (think ``S'' for ``secret'' or ``static''). All other functions begin with
1824 ``Perl_'', but just because a function begins with ``Perl_'' does not mean it is
1825 part of the API. (See <a href="#internal_functions">Internal Functions</a>.) The easiest way to be <strong>sure</strong> a
1826 function is part of the API is to find its entry in <a href="file://C|\msysgit\mingw\html/pod/perlapi.html">the perlapi manpage</a>.
1827 If it exists in <a href="file://C|\msysgit\mingw\html/pod/perlapi.html">the perlapi manpage</a>, it's part of the API. If it doesn't, and you
1828 think it should be (i.e., you need it for your extension), send mail via
1829 <a href="file://C|\msysgit\mingw\html/utils/perlbug.html">the perlbug manpage</a> explaining why you think it should be.</p>
1830 <p>Second problem: there must be a syntax so that the same subroutine
1831 declarations and calls can pass a structure as their first argument,
1832 or pass nothing. To solve this, the subroutines are named and
1833 declared in a particular way. Here's a typical start of a static
1834 function used within the Perl guts:</p>
1835 <pre>
1836 STATIC void
1837 S_incline(pTHX_ char *s)</pre>
1838 <p>STATIC becomes ``static'' in C, and may be #define'd to nothing in some
1839 configurations in future.</p>
1840 <p>A public function (i.e. part of the internal API, but not necessarily
1841 sanctioned for use in extensions) begins like this:</p>
1842 <pre>
1843 void
1844 Perl_sv_setiv(pTHX_ SV* dsv, IV num)</pre>
1846 details of the interpreter's context. THX stands for ``thread'', ``this'',
1847 or ``thingy'', as the case may be. (And no, George Lucas is not involved. :-)
1848 The first character could be 'p' for a <strong>p</strong>rototype, 'a' for <strong>a</strong>rgument,
1849 or 'd' for <strong>d</strong>eclaration, so we have <code>pTHX</code>, <code>aTHX</code> and <code>dTHX</code>, and
1850 their variants.</p>
1851 <p>When Perl is built without options that set PERL_IMPLICIT_CONTEXT, there is no
1852 first argument containing the interpreter's context. The trailing underscore
1853 in the pTHX_ macro indicates that the macro expansion needs a comma
1854 after the context argument because other arguments follow it. If
1855 PERL_IMPLICIT_CONTEXT is not defined, pTHX_ will be ignored, and the
1856 subroutine is not prototyped to take the extra argument. The form of the
1857 macro without the trailing underscore is used when there are no additional
1858 explicit arguments.</p>
1859 <p>When a core function calls another, it must pass the context. This
1861 something like this:</p>
1862 <pre>
1863 #ifdef PERL_IMPLICIT_CONTEXT
1864 #define sv_setiv(a,b) Perl_sv_setiv(aTHX_ a, b)
1865 /* can't do this for vararg functions, see below */
1866 #else
1867 #define sv_setiv Perl_sv_setiv
1868 #endif</pre>
1870 <pre>
1871 sv_setiv(foo, bar);</pre>
1872 <p>and still have it work under all the modes Perl could have been
1873 compiled with.</p>
1874 <p>This doesn't work so cleanly for varargs functions, though, as macros
1875 imply that the number of arguments is known in advance. Instead we
1877 argument (the Perl core tends to do this with functions like
1878 Perl_warner), or use a context-free version.</p>
1879 <p>The context-free version of Perl_warner is called
1880 Perl_warner_nocontext, and does not take the extra argument. Instead
1881 it does dTHX; to get the context from thread-local storage. We
1883 compatibility at the expense of performance. (Passing an arg is
1884 cheaper than grabbing it from thread-local storage.)</p>
1885 <p>You can ignore [pad]THXx when browsing the Perl headers/sources.
1886 Those are strictly for use within the core. Extensions and embedders
1887 need only be aware of [pad]THX.</p>
1888 <p>
1889 </p>
1894 later still have it for backward source compatibility, but it is defined
1895 to be a no-op.</p>
1896 <p>
1897 </p>
1898 <h2><a name="how_do_i_use_all_this_in_extensions">How do I use all this in extensions?</a></h2>
1899 <p>When Perl is built with PERL_IMPLICIT_CONTEXT, extensions that call
1900 any functions in the Perl API will need to pass the initial context
1901 argument somehow. The kicker is that you will need to write it in
1902 such a way that the extension still compiles when Perl hasn't been
1903 built with PERL_IMPLICIT_CONTEXT enabled.</p>
1904 <p>There are three ways to do this. First, the easy but inefficient way,
1905 which is also the default, in order to maintain source compatibility
1906 with extensions: whenever XSUB.h is #included, it redefines the aTHX
1907 and aTHX_ macros to call a function that will return the context.
1908 Thus, something like:</p>
1909 <pre>
1910 sv_setiv(sv, num);</pre>
1911 <p>in your extension will translate to this when PERL_IMPLICIT_CONTEXT is
1912 in effect:</p>
1913 <pre>
1914 Perl_sv_setiv(Perl_get_context(), sv, num);</pre>
1916 <pre>
1917 Perl_sv_setiv(sv, num);</pre>
1918 <p>You have to do nothing new in your extension to get this; since
1919 the Perl library provides Perl_get_context(), it will all just
1920 work.</p>
1921 <p>The second, more efficient way is to use the following template for
1922 your Foo.xs:</p>
1923 <pre>
1924 #define PERL_NO_GET_CONTEXT /* we want efficiency */
1928 <pre>
1929 static my_private_function(int arg1, int arg2);</pre>
1930 <pre>
1931 static SV *
1932 my_private_function(int arg1, int arg2)
1933 {
1934 dTHX; /* fetch context */
1935 ... call many Perl API functions ...
1936 }</pre>
1937 <pre>
1938 [... etc ...]</pre>
1939 <pre>
1940 MODULE = Foo PACKAGE = Foo</pre>
1941 <pre>
1942 /* typical XSUB */</pre>
1943 <pre>
1944 void
1945 my_xsub(arg)
1946 int arg
1947 CODE:
1949 <p>Note that the only two changes from the normal way of writing an
1952 the start of every function that will call the Perl API. (You'll
1953 know which functions need this, because the C compiler will complain
1954 that there's an undeclared identifier in those functions.) No changes
1956 correctly defined to pass in the implicit context if needed.</p>
1957 <p>The third, even more efficient way is to ape how it is done within
1958 the Perl guts:</p>
1959 <pre>
1960 #define PERL_NO_GET_CONTEXT /* we want efficiency */
1964 <pre>
1965 /* pTHX_ only needed for functions that call Perl API */
1966 static my_private_function(pTHX_ int arg1, int arg2);</pre>
1967 <pre>
1968 static SV *
1969 my_private_function(pTHX_ int arg1, int arg2)
1970 {
1971 /* dTHX; not needed here, because THX is an argument */
1972 ... call Perl API functions ...
1973 }</pre>
1974 <pre>
1975 [... etc ...]</pre>
1976 <pre>
1977 MODULE = Foo PACKAGE = Foo</pre>
1978 <pre>
1979 /* typical XSUB */</pre>
1980 <pre>
1981 void
1982 my_xsub(arg)
1983 int arg
1984 CODE:
1986 <p>This implementation never has to fetch the context using a function
1987 call, since it is always passed as an extra argument. Depending on
1988 your needs for simplicity or efficiency, you may mix the previous
1989 two approaches freely.</p>
1991 macro with the underscore for functions that take explicit arguments,
1992 or the form without the argument for functions with no explicit arguments.</p>
1993 <p>
1994 </p>
1995 <h2><a name="should_i_do_anything_special_if_i_call_perl_from_multiple_threads">Should I do anything special if I call perl from multiple threads?</a></h2>
1996 <p>If you create interpreters in one thread and then proceed to call them in
1997 another, you need to make sure perl's own Thread Local Storage (TLS) slot is
1998 initialized correctly in each of those threads.</p>
1999 <p>The <code>perl_alloc</code> and <code>perl_clone</code> API functions will automatically set
2000 the TLS slot to the interpreter they created, so that there is no need to do
2001 anything special if the interpreter is always accessed in the same thread that
2002 created it, and that thread did not create or call any other interpreters
2003 afterwards. If that is not the case, you have to set the TLS slot of the
2004 thread before calling any functions in the Perl API on that particular
2006 thread as the first thing you do:</p>
2007 <pre>
2008 /* do this before doing anything else with some_perl */
2009 PERL_SET_CONTEXT(some_perl);</pre>
2010 <pre>
2011 ... other Perl API calls on some_perl go here ...</pre>
2012 <p>
2013 </p>
2015 <p>Just as PERL_IMPLICIT_CONTEXT provides a way to bundle up everything
2016 that the interpreter knows about itself and pass it around, so too are
2017 there plans to allow the interpreter to bundle up everything it knows
2018 about the environment it's running on. This is enabled with the
2019 PERL_IMPLICIT_SYS macro. Currently it only works with USE_ITHREADS
2020 and USE_5005THREADS on Windows (see inside iperlsys.h).</p>
2021 <p>This allows the ability to provide an extra pointer (called the ``host''
2022 environment) for all the system calls. This makes it possible for
2023 all the system stuff to maintain their own state, broken down into
2024 seven C structures. These are thin wrappers around the usual system
2025 calls (see win32/perllib.c) for the default perl executable, but for a
2027 the extra work needed to pretend that different interpreters are
2028 actually different ``processes'', would be done here.</p>
2029 <p>The Perl engine/interpreter and the host are orthogonal entities.
2030 There could be one or more interpreters in a process, and one or
2031 more ``hosts'', with free association between them.</p>
2032 <p>
2033 </p>
2034 <hr />
2036 <p>All of Perl's internal functions which will be exposed to the outside
2038 functions or functions used in a program in which Perl is embedded.
2041 <p>Inside the Perl core, you can get at the functions either with or
2045 header files for the internal functions, generates the documentation
2046 and a lot of other bits and pieces. It's important that when you add
2047 a new function to the core or change an existing one, you change the
2049 that table:</p>
2050 <pre>
2051 Apd |SV** |av_fetch |AV* ar|I32 key|I32 lval</pre>
2052 <p>The second column is the return type, the third column the name. Columns
2053 after that are the arguments. The first column is a set of flags:</p>
2054 <dl>
2057 <dd>
2058 <p>This function is a part of the public API. All such functions should also
2059 have 'd', very few do not.</p>
2060 </dd>
2061 </li>
2064 <dd>
2067 </dd>
2068 </li>
2071 <dd>
2073 look at in a second. Some functions have 'd' but not 'A'; docs are good.</p>
2074 </dd>
2075 </li>
2076 </dl>
2078 <dl>
2081 <dd>
2084 </dd>
2085 </li>
2088 <dd>
2089 <p>This does not need a interpreter context, so the definition has no
2091 <a href="file://C|\msysgit\mingw\html/pod/perlguts.html#background_and_perl_implicit_context">Background and PERL_IMPLICIT_CONTEXT in the perlguts manpage</a>.)</p>
2092 </dd>
2093 </li>
2096 <dd>
2097 <p>This function never returns; <code>croak</code>, <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_exit"><code>exit</code></a> and friends.</p>
2098 </dd>
2099 </li>
2102 <dd>
2103 <p>This function takes a variable number of arguments, <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_printf"><code>printf</code></a> style.
2105 </dd>
2106 <dd>
2107 <pre>
2108 Afprd |void |croak |const char* pat|...</pre>
2109 </dd>
2110 </li>
2113 <dd>
2114 <p>This function is part of the experimental development API, and may change
2115 or disappear without notice.</p>
2116 </dd>
2117 </li>
2120 <dd>
2121 <p>This function should not have a compatibility macro to define, say,
2122 <code>Perl_parse</code> to <code>parse</code>. It must be called as <code>Perl_parse</code>.</p>
2123 </dd>
2124 </li>
2127 <dd>
2129 </dd>
2130 </li>
2133 <dd>
2135 </dd>
2136 </li>
2139 <dd>
2141 </dd>
2142 </li>
2145 <dd>
2147 </dd>
2148 </li>
2151 <dd>
2152 <p>Binary backward compatibility; this function is a macro but also has
2154 </dd>
2155 </li>
2158 <dd>
2160 </dd>
2161 </li>
2162 </dl>
2165 auto-generated files.</p>
2166 <p>
2167 </p>
2168 <h2><a name="formatted_printing_of_ivs__uvs__and_nvs">Formatted Printing of IVs, UVs, and NVs</a></h2>
2171 following macros for portability</p>
2172 <pre>
2173 IVdf IV in decimal
2174 UVuf UV in decimal
2175 UVof UV in octal
2176 UVxf UV in hexadecimal
2177 NVef NV %e-like
2178 NVff NV %f-like
2179 NVgf NV %g-like</pre>
2181 For example:</p>
2182 <pre>
2185 <p>If you are printing addresses of pointers, use UVxf combined
2186 with PTR2UV(), do not use %lx or %p.</p>
2187 <p>
2188 </p>
2189 <h2><a name="pointertointeger_and_integertopointer">Pointer-To-Integer and Integer-To-Pointer</a></h2>
2190 <p>Because pointer size does not necessarily equal integer size,
2191 use the follow macros to do it right.</p>
2192 <pre>
2193 PTR2UV(pointer)
2194 PTR2IV(pointer)
2195 PTR2NV(pointer)
2196 INT2PTR(pointertotype, integer)</pre>
2198 <pre>
2199 IV iv = ...;
2200 SV *sv = INT2PTR(SV*, iv);</pre>
2202 <pre>
2203 AV *av = ...;
2204 UV uv = PTR2UV(av);</pre>
2205 <p>
2206 </p>
2208 <p>There's an effort going on to document the internal functions and
2209 automatically produce reference manuals from them - <a href="file://C|\msysgit\mingw\html/pod/perlapi.html">the perlapi manpage</a> is one
2210 such manual which details all the functions which are available to XS
2211 writers. <a href="file://C|\msysgit\mingw\html/pod/perlintern.html">the perlintern manpage</a> is the autogenerated manual for the functions
2212 which are not part of the API and are supposedly for internal use only.</p>
2213 <p>Source documentation is created by putting POD comments into the C
2214 source, like this:</p>
2215 <pre>
2216 /*
2217 =for apidoc sv_setiv</pre>
2218 <pre>
2219 Copies an integer into the given SV. Does not handle 'set' magic. See
2221 <pre>
2222 =cut
2223 */</pre>
2224 <p>Please try and supply some documentation if you add functions to the
2225 Perl core.</p>
2226 <p>
2227 </p>
2229 <p>The Perl API changes over time. New functions are added or the interfaces
2231 provide compatibility code for some of these changes, so XS writers don't
2232 have to code it themselves when supporting multiple versions of Perl.</p>
2235 <pre>
2236 perl -MDevel::PPPort -eDevel::PPPort::WriteFile</pre>
2237 <p>Besides checking existing XS code, the script can also be used to retrieve
2239 command line switch. For example:</p>
2240 <pre>
2241 % perl ppport.h --api-info=sv_magicext</pre>
2243 <p>
2244 </p>
2245 <hr />
2248 writers to understand this support and make sure that the code they
2249 write does not corrupt Unicode data.</p>
2250 <p>
2251 </p>
2253 <p>In the olden, less enlightened times, we all used to use ASCII. Most of
2254 us did, anyway. The big problem with ASCII is that it's American. Well,
2255 no, that's not actually the problem; the problem is that it's not
2256 particularly useful for people who don't use the Roman alphabet. What
2257 used to happen was that particular languages would stick their own
2259 course, we then ended up with plenty of variants that weren't quite
2260 ASCII, and the whole point of it being a standard was lost.</p>
2261 <p>Worse still, if you've got a language like Chinese or
2262 Japanese that has hundreds or thousands of characters, then you really
2263 can't fit them into a mere 256, so they had to forget about ASCII
2264 altogether, and build their own systems using pairs of numbers to refer
2265 to one character.</p>
2266 <p>To fix this, some people formed Unicode, Inc. and
2267 produced a new character set containing all the characters you can
2268 possibly think of and more. There are several ways of representing these
2270 a variable number of bytes to represent a character, instead of just
2271 one. You can learn more about Unicode at <a href="http://www.unicode.org/">http://www.unicode.org/</a></p>
2272 <p>
2273 </p>
2277 capital E with a grave accent, is represented by the two bytes
2278 <code>v196.172</code>. Unfortunately, the non-Unicode string <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_chr"><code>chr(196).chr(172)</code></a>
2279 has that byte sequence as well. So you can't tell just by looking - this
2280 is what makes Unicode input an interesting problem.</p>
2282 contains only valid UTF-8 characters. However, it can't do the work for
2285 <p>
2286 </p>
2287 <h2><a name="how_does_utf8_represent_unicode_characters">How does UTF-8 represent Unicode characters?</a></h2>
2296 <pre>
2298 I32 len;</pre>
2299 <pre>
2300 len = UTF8SKIP(utf); /* len is 2 here */
2301 utf += len;
2305 over. You're on your own about bounds checking, though, so don't use it
2306 lightly.</p>
2308 so you can test if you need to do something special with this
2311 <pre>
2312 U8 *utf;
2313 UV uv; /* Note: a UV, not a U8, not a char */</pre>
2314 <pre>
2315 if (!UTF8_IS_INVARIANT(*utf))
2316 /* Must treat this as UTF-8 */
2317 uv = utf8_to_uv(utf);
2318 else
2319 /* OK to treat this character as a byte */
2320 uv = *utf;</pre>
2324 <pre>
2325 if (!UTF8_IS_INVARIANT(uv))
2326 /* Must treat this as UTF8 */
2327 utf8 = uv_to_utf8(utf8, uv);
2328 else
2329 /* OK to treat this character as a byte */
2330 *utf8++ = uv;</pre>
2333 characters. You may not skip over UTF-8 characters in this case. If you
2334 do this, you'll lose the ability to match hi-bit non-UTF-8 characters;
2336 that character, you can never match a <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_chr"><code>chr(200)</code></a> in a non-UTF-8 string.
2337 So don't do that!</p>
2338 <p>
2339 </p>
2341 <p>Currently, Perl deals with Unicode strings and non-Unicode strings
2342 slightly differently. If a string has been identified as being UTF-8
2344 manipulate this flag with the following macros:</p>
2345 <pre>
2346 SvUTF8(sv)
2347 SvUTF8_on(sv)
2348 SvUTF8_off(sv)</pre>
2349 <p>This flag has an important effect on Perl's treatment of the string: if
2350 Unicode data is not properly distinguished, regular expressions,
2351 <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_length"><code>length</code></a>, <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item_substr"><code>substr</code></a> and other string handling operations will have
2352 undesirable results.</p>
2353 <p>The problem comes when you have, for instance, a string that isn't
2357 need be sure you don't accidentally knock it off while you're
2358 manipulating SVs. More specifically, you cannot expect to do this:</p>
2359 <pre>
2360 SV *sv;
2361 SV *nsv;
2362 STRLEN len;
2363 char *p;</pre>
2364 <pre>
2365 p = SvPV(sv, len);
2366 frobnicate(p);
2367 nsv = newSVpvn(p, len);</pre>
2369 copy or reconstruct an SV just by copying the string value. Check if the
2371 <pre>
2372 p = SvPV(sv, len);
2373 frobnicate(p);
2374 nsv = newSVpvn(p, len);
2375 if (SvUTF8(sv))
2376 SvUTF8_on(nsv);</pre>
2378 not it's dealing with UTF-8 data, so that it can handle the string
2379 appropriately.</p>
2380 <p>Since just passing an SV to an XS function and copying the data of
2381 the SV is not enough to copy the UTF-8 flags, even less right is just
2383 <p>
2384 </p>
2387 to upgrade one of the strings to UTF-8. If you've got an SV, the easiest
2388 way to do this is:</p>
2389 <pre>
2390 sv_utf8_upgrade(sv);</pre>
2392 <pre>
2393 if (!SvUTF8(left))
2394 sv_utf8_upgrade(left);</pre>
2395 <p>If you do this in a binary operator, you will actually change one of the
2396 strings that came into the operator, and, while it shouldn't be noticeable
2397 by the end user, it can cause problems.</p>
2398 <p>Instead, <code>bytes_to_utf8</code> will give you a UTF-8-encoded <strong>copy</strong> of its
2399 string argument. This is useful for having the data available for
2400 comparisons and so on, without harming the original SV. There's also
2402 the string contains any characters above 255 that can't be represented
2403 in a single byte.</p>
2404 <p>
2405 </p>
2406 <h2><a name="is_there_anything_else_i_need_to_know">Is there anything else I need to know?</a></h2>
2408 <ul>
2409 <li>
2412 something should be UTF-8. Treat the flag as part of the PV, even though
2413 it's not - if you pass on the PV to somewhere, pass on the flag too.</p>
2414 </li>
2415 <li>
2416 <p>If a string is UTF-8, <strong>always</strong> use <code>utf8_to_uv</code> to get at the value,
2418 </li>
2419 <li>
2423 </li>
2424 <li>
2426 a new string which is UTF-8 encoded. There are tricks you can use to
2427 delay deciding whether you need to use a UTF-8 string until you get to a
2429 </li>
2430 </ul>
2431 <p>
2432 </p>
2433 <hr />
2435 <p>Custom operator support is a new experimental feature that allows you to
2436 define your own ops. This is primarily to allow the building of
2437 interpreters for other languages in the Perl core, but it also allows
2438 optimizations through the creation of ``macro-ops'' (ops which perform the
2439 functions of multiple ops which are usually executed together, such as
2442 core does not ``know'' anything special about this op type, and so it will
2443 not be involved in any optimizations. This also means that you can
2444 define your custom ops to be any op structure - unary, binary, list and
2445 so on - you like.</p>
2446 <p>It's important to know what custom operators won't do for you. They
2447 won't let you add new syntax to Perl, directly. They won't even let you
2448 add new keywords, directly. In fact, they won't change the way Perl
2449 compiles a program at all. You have to do those changes yourself, after
2450 Perl has compiled the program. You do this either by manipulating the op
2453 <p>When you do this, you replace ordinary Perl ops with custom ops by
2455 PP function. This should be defined in XS code, and should look like
2457 takes the appropriate number of values from the stack, and you are
2458 responsible for adding stack marks if necessary.</p>
2459 <p>You should also ``register'' your op with the Perl interpreter so that it
2460 can produce sensible error and warning messages. Since it is possible to
2464 need to enter a name and description for your op at the appropriate
2467 directly support the creation of custom ops by name.</p>
2468 <p>
2469 </p>
2470 <hr />
2473 <<a href="mailto:okamoto@corp.hp.com">okamoto@corp.hp.com</a>>. It is now maintained as part of Perl
2474 itself by the Perl 5 Porters <<a href="mailto:perl5-porters@perl.org">perl5-porters@perl.org</a>>.</p>
2475 <p>With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
2476 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
2477 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
2478 Stephen McCamant, and Gurusamy Sarathy.</p>
2479 <p>
2480 </p>
2481 <hr />
2486 <big><strong><span class="block"> perlguts - Introduction to the Perl API</span></strong></big>
2487 </td></tr>
2488 </table>
2490 </body>
2492 </html>