Commit | Line | Data |
---|---|---|
3f98fbb3 RGS |
1 | -*- buffer-read-only: t -*- |
2 | ||
3 | !!!!!!! DO NOT EDIT THIS FILE !!!!!!! | |
4 | This file is built by autodoc.pl extracting documentation from the C source | |
5 | files. | |
6 | ||
954c1994 GS |
7 | =head1 NAME |
8 | ||
1c846c1f | 9 | perlintern - autogenerated documentation of purely B<internal> |
954c1994 GS |
10 | Perl functions |
11 | ||
12 | =head1 DESCRIPTION | |
d8c40edc | 13 | X<internal Perl functions> X<interpreter functions> |
954c1994 | 14 | |
1c846c1f | 15 | This file is the autogenerated documentation of functions in the |
4375e838 | 16 | Perl interpreter that are documented using Perl's internal documentation |
1c846c1f | 17 | format but are not marked as part of the Perl API. In other words, |
954c1994 GS |
18 | B<they are not for use in extensions>! |
19 | ||
a8586c98 | 20 | |
7dafbf52 DM |
21 | =head1 CV reference counts and CvOUTSIDE |
22 | ||
23 | =over 8 | |
24 | ||
25 | =item CvWEAKOUTSIDE | |
d8c40edc | 26 | X<CvWEAKOUTSIDE> |
7dafbf52 DM |
27 | |
28 | Each CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing | |
29 | CV (if any). Because pointers to anonymous sub prototypes are | |
30 | stored in C<&> pad slots, it is a possible to get a circular reference, | |
31 | with the parent pointing to the child and vice-versa. To avoid the | |
32 | ensuing memory leak, we do not increment the reference count of the CV | |
33 | pointed to by C<CvOUTSIDE> in the I<one specific instance> that the parent | |
34 | has a C<&> pad slot pointing back to us. In this case, we set the | |
35 | C<CvWEAKOUTSIDE> flag in the child. This allows us to determine under what | |
36 | circumstances we should decrement the refcount of the parent when freeing | |
37 | the child. | |
38 | ||
28a5cf3b | 39 | There is a further complication with non-closure anonymous subs (i.e. those |
7dafbf52 DM |
40 | that do not refer to any lexicals outside that sub). In this case, the |
41 | anonymous prototype is shared rather than being cloned. This has the | |
42 | consequence that the parent may be freed while there are still active | |
43 | children, eg | |
44 | ||
45 | BEGIN { $a = sub { eval '$x' } } | |
46 | ||
47 | In this case, the BEGIN is freed immediately after execution since there | |
48 | are no active references to it: the anon sub prototype has | |
49 | C<CvWEAKOUTSIDE> set since it's not a closure, and $a points to the same | |
50 | CV, so it doesn't contribute to BEGIN's refcount either. When $a is | |
51 | executed, the C<eval '$x'> causes the chain of C<CvOUTSIDE>s to be followed, | |
52 | and the freed BEGIN is accessed. | |
53 | ||
54 | To avoid this, whenever a CV and its associated pad is freed, any | |
55 | C<&> entries in the pad are explicitly removed from the pad, and if the | |
56 | refcount of the pointed-to anon sub is still positive, then that | |
57 | child's C<CvOUTSIDE> is set to point to its grandparent. This will only | |
58 | occur in the single specific case of a non-closure anon prototype | |
59 | having one or more active references (such as C<$a> above). | |
60 | ||
61 | One other thing to consider is that a CV may be merely undefined | |
62 | rather than freed, eg C<undef &foo>. In this case, its refcount may | |
63 | not have reached zero, but we still delete its pad and its C<CvROOT> etc. | |
64 | Since various children may still have their C<CvOUTSIDE> pointing at this | |
65 | undefined CV, we keep its own C<CvOUTSIDE> for the time being, so that | |
66 | the chain of lexical scopes is unbroken. For example, the following | |
67 | should print 123: | |
68 | ||
69 | my $x = 123; | |
70 | sub tmp { sub { eval '$x' } } | |
71 | my $a = tmp(); | |
72 | undef &tmp; | |
73 | print $a->(); | |
74 | ||
75 | bool CvWEAKOUTSIDE(CV *cv) | |
76 | ||
77 | =for hackers | |
78 | Found in file cv.h | |
79 | ||
80 | ||
81 | =back | |
82 | ||
dd2155a4 DM |
83 | =head1 Functions in file pad.h |
84 | ||
85 | ||
86 | =over 8 | |
87 | ||
88 | =item CX_CURPAD_SAVE | |
d8c40edc | 89 | X<CX_CURPAD_SAVE> |
dd2155a4 DM |
90 | |
91 | Save the current pad in the given context block structure. | |
92 | ||
93 | void CX_CURPAD_SAVE(struct context) | |
94 | ||
95 | =for hackers | |
96 | Found in file pad.h | |
97 | ||
98 | =item CX_CURPAD_SV | |
d8c40edc | 99 | X<CX_CURPAD_SV> |
dd2155a4 DM |
100 | |
101 | Access the SV at offset po in the saved current pad in the given | |
102 | context block structure (can be used as an lvalue). | |
103 | ||
f3548bdc | 104 | SV * CX_CURPAD_SV(struct context, PADOFFSET po) |
dd2155a4 DM |
105 | |
106 | =for hackers | |
107 | Found in file pad.h | |
108 | ||
d8c40edc AT |
109 | =item PAD_BASE_SV |
110 | X<PAD_BASE_SV> | |
dd2155a4 DM |
111 | |
112 | Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist | |
113 | ||
d8c40edc | 114 | SV * PAD_BASE_SV(PADLIST padlist, PADOFFSET po) |
dd2155a4 DM |
115 | |
116 | =for hackers | |
117 | Found in file pad.h | |
118 | ||
119 | =item PAD_CLONE_VARS | |
d8c40edc | 120 | X<PAD_CLONE_VARS> |
dd2155a4 | 121 | |
dd2155a4 DM |
122 | Clone the state variables associated with running and compiling pads. |
123 | ||
d77cdebf | 124 | void PAD_CLONE_VARS(PerlInterpreter *proto_perl, CLONE_PARAMS* param) |
dd2155a4 DM |
125 | |
126 | =for hackers | |
127 | Found in file pad.h | |
128 | ||
129 | =item PAD_COMPNAME_FLAGS | |
d8c40edc | 130 | X<PAD_COMPNAME_FLAGS> |
dd2155a4 DM |
131 | |
132 | Return the flags for the current compiling pad name | |
133 | at offset C<po>. Assumes a valid slot entry. | |
134 | ||
135 | U32 PAD_COMPNAME_FLAGS(PADOFFSET po) | |
136 | ||
137 | =for hackers | |
138 | Found in file pad.h | |
139 | ||
140 | =item PAD_COMPNAME_GEN | |
d8c40edc | 141 | X<PAD_COMPNAME_GEN> |
dd2155a4 DM |
142 | |
143 | The generation number of the name at offset C<po> in the current | |
00a0d662 | 144 | compiling pad (lvalue). Note that C<SvUVX> is hijacked for this purpose. |
dd2155a4 DM |
145 | |
146 | STRLEN PAD_COMPNAME_GEN(PADOFFSET po) | |
147 | ||
148 | =for hackers | |
149 | Found in file pad.h | |
150 | ||
27da23d5 | 151 | =item PAD_COMPNAME_GEN_set |
d8c40edc | 152 | X<PAD_COMPNAME_GEN_set> |
27da23d5 JH |
153 | |
154 | Sets the generation number of the name at offset C<po> in the current | |
00a0d662 | 155 | ling pad (lvalue) to C<gen>. Note that C<SvUV_set> is hijacked for this purpose. |
27da23d5 JH |
156 | |
157 | STRLEN PAD_COMPNAME_GEN_set(PADOFFSET po, int gen) | |
158 | ||
159 | =for hackers | |
160 | Found in file pad.h | |
161 | ||
dd2155a4 | 162 | =item PAD_COMPNAME_OURSTASH |
d8c40edc | 163 | X<PAD_COMPNAME_OURSTASH> |
dd2155a4 DM |
164 | |
165 | Return the stash associated with an C<our> variable. | |
166 | Assumes the slot entry is a valid C<our> lexical. | |
167 | ||
168 | HV * PAD_COMPNAME_OURSTASH(PADOFFSET po) | |
169 | ||
170 | =for hackers | |
171 | Found in file pad.h | |
172 | ||
173 | =item PAD_COMPNAME_PV | |
d8c40edc | 174 | X<PAD_COMPNAME_PV> |
dd2155a4 DM |
175 | |
176 | Return the name of the current compiling pad name | |
177 | at offset C<po>. Assumes a valid slot entry. | |
178 | ||
179 | char * PAD_COMPNAME_PV(PADOFFSET po) | |
180 | ||
181 | =for hackers | |
182 | Found in file pad.h | |
183 | ||
184 | =item PAD_COMPNAME_TYPE | |
d8c40edc | 185 | X<PAD_COMPNAME_TYPE> |
dd2155a4 DM |
186 | |
187 | Return the type (stash) of the current compiling pad name at offset | |
188 | C<po>. Must be a valid name. Returns null if not typed. | |
189 | ||
190 | HV * PAD_COMPNAME_TYPE(PADOFFSET po) | |
191 | ||
192 | =for hackers | |
193 | Found in file pad.h | |
194 | ||
195 | =item PAD_DUP | |
d8c40edc | 196 | X<PAD_DUP> |
dd2155a4 DM |
197 | |
198 | Clone a padlist. | |
199 | ||
200 | void PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param) | |
201 | ||
202 | =for hackers | |
203 | Found in file pad.h | |
204 | ||
f3548bdc | 205 | =item PAD_RESTORE_LOCAL |
d8c40edc | 206 | X<PAD_RESTORE_LOCAL> |
f3548bdc DM |
207 | |
208 | Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL() | |
209 | ||
210 | void PAD_RESTORE_LOCAL(PAD *opad) | |
211 | ||
212 | =for hackers | |
213 | Found in file pad.h | |
214 | ||
215 | =item PAD_SAVE_LOCAL | |
d8c40edc | 216 | X<PAD_SAVE_LOCAL> |
f3548bdc DM |
217 | |
218 | Save the current pad to the local variable opad, then make the | |
219 | current pad equal to npad | |
220 | ||
221 | void PAD_SAVE_LOCAL(PAD *opad, PAD *npad) | |
222 | ||
223 | =for hackers | |
224 | Found in file pad.h | |
225 | ||
dd2155a4 | 226 | =item PAD_SAVE_SETNULLPAD |
d8c40edc | 227 | X<PAD_SAVE_SETNULLPAD> |
dd2155a4 DM |
228 | |
229 | Save the current pad then set it to null. | |
230 | ||
231 | void PAD_SAVE_SETNULLPAD() | |
232 | ||
233 | =for hackers | |
234 | Found in file pad.h | |
235 | ||
d8c40edc AT |
236 | =item PAD_SETSV |
237 | X<PAD_SETSV> | |
dd2155a4 DM |
238 | |
239 | Set the slot at offset C<po> in the current pad to C<sv> | |
240 | ||
d8c40edc | 241 | SV * PAD_SETSV(PADOFFSET po, SV* sv) |
dd2155a4 DM |
242 | |
243 | =for hackers | |
244 | Found in file pad.h | |
245 | ||
d8c40edc AT |
246 | =item PAD_SET_CUR |
247 | X<PAD_SET_CUR> | |
dd2155a4 DM |
248 | |
249 | Set the current pad to be pad C<n> in the padlist, saving | |
f54ba1c2 DM |
250 | the previous current pad. NB currently this macro expands to a string too |
251 | long for some compilers, so it's best to replace it with | |
252 | ||
253 | SAVECOMPPAD(); | |
254 | PAD_SET_CUR_NOSAVE(padlist,n); | |
255 | ||
dd2155a4 | 256 | |
d8c40edc | 257 | void PAD_SET_CUR(PADLIST padlist, I32 n) |
dd2155a4 DM |
258 | |
259 | =for hackers | |
260 | Found in file pad.h | |
261 | ||
d8c40edc AT |
262 | =item PAD_SET_CUR_NOSAVE |
263 | X<PAD_SET_CUR_NOSAVE> | |
bf9cdc68 RG |
264 | |
265 | like PAD_SET_CUR, but without the save | |
266 | ||
d8c40edc | 267 | void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n) |
bf9cdc68 RG |
268 | |
269 | =for hackers | |
270 | Found in file pad.h | |
271 | ||
d8c40edc AT |
272 | =item PAD_SV |
273 | X<PAD_SV> | |
dd2155a4 DM |
274 | |
275 | Get the value at offset C<po> in the current pad | |
276 | ||
d8c40edc | 277 | void PAD_SV(PADOFFSET po) |
dd2155a4 DM |
278 | |
279 | =for hackers | |
280 | Found in file pad.h | |
281 | ||
d8c40edc AT |
282 | =item PAD_SVl |
283 | X<PAD_SVl> | |
dd2155a4 DM |
284 | |
285 | Lightweight and lvalue version of C<PAD_SV>. | |
286 | Get or set the value at offset C<po> in the current pad. | |
287 | Unlike C<PAD_SV>, does not print diagnostics with -DX. | |
288 | For internal use only. | |
289 | ||
d8c40edc | 290 | SV * PAD_SVl(PADOFFSET po) |
dd2155a4 DM |
291 | |
292 | =for hackers | |
293 | Found in file pad.h | |
294 | ||
d8c40edc AT |
295 | =item SAVECLEARSV |
296 | X<SAVECLEARSV> | |
dd2155a4 | 297 | |
28a5cf3b | 298 | Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my') |
dd2155a4 | 299 | |
d8c40edc | 300 | void SAVECLEARSV(SV **svp) |
dd2155a4 DM |
301 | |
302 | =for hackers | |
303 | Found in file pad.h | |
304 | ||
305 | =item SAVECOMPPAD | |
d8c40edc | 306 | X<SAVECOMPPAD> |
dd2155a4 DM |
307 | |
308 | save PL_comppad and PL_curpad | |
309 | ||
dd2155a4 | 310 | |
dd2155a4 DM |
311 | |
312 | ||
313 | ||
f3548bdc | 314 | void SAVECOMPPAD() |
dd2155a4 DM |
315 | |
316 | =for hackers | |
317 | Found in file pad.h | |
318 | ||
d8c40edc AT |
319 | =item SAVEPADSV |
320 | X<SAVEPADSV> | |
dd2155a4 DM |
321 | |
322 | Save a pad slot (used to restore after an iteration) | |
323 | ||
f3548bdc | 324 | XXX DAPM it would make more sense to make the arg a PADOFFSET |
d8c40edc | 325 | void SAVEPADSV(PADOFFSET po) |
dd2155a4 DM |
326 | |
327 | =for hackers | |
328 | Found in file pad.h | |
329 | ||
330 | ||
331 | =back | |
332 | ||
a4f1a029 NIS |
333 | =head1 GV Functions |
334 | ||
335 | =over 8 | |
336 | ||
337 | =item is_gv_magical | |
d8c40edc | 338 | X<is_gv_magical> |
a4f1a029 NIS |
339 | |
340 | Returns C<TRUE> if given the name of a magical GV. | |
341 | ||
342 | Currently only useful internally when determining if a GV should be | |
343 | created even in rvalue contexts. | |
344 | ||
345 | C<flags> is not used at present but available for future extension to | |
346 | allow selecting particular classes of magical variable. | |
347 | ||
766f8916 MHM |
348 | Currently assumes that C<name> is NUL terminated (as well as len being valid). |
349 | This assumption is met by all callers within the perl core, which all pass | |
350 | pointers returned by SvPV. | |
351 | ||
7fc63493 AL |
352 | bool is_gv_magical(const char *name, STRLEN len, U32 flags) |
353 | ||
354 | =for hackers | |
355 | Found in file gv.c | |
356 | ||
357 | =item is_gv_magical_sv | |
d8c40edc | 358 | X<is_gv_magical_sv> |
7fc63493 AL |
359 | |
360 | Returns C<TRUE> if given the name of a magical GV. Calls is_gv_magical. | |
361 | ||
362 | bool is_gv_magical_sv(SV *name, U32 flags) | |
645c22ef DM |
363 | |
364 | =for hackers | |
a4f1a029 NIS |
365 | Found in file gv.c |
366 | ||
367 | ||
368 | =back | |
369 | ||
b3ca2e83 NC |
370 | =head1 Hash Manipulation Functions |
371 | ||
372 | =over 8 | |
373 | ||
bd95ae50 SH |
374 | =item refcounted_he_chain_2hv |
375 | X<refcounted_he_chain_2hv> | |
376 | ||
8a0be661 | 377 | Generates and returns a C<HV *> by walking up the tree starting at the passed |
bd95ae50 SH |
378 | in C<struct refcounted_he *>. |
379 | ||
380 | HV * refcounted_he_chain_2hv(const struct refcounted_he *c) | |
381 | ||
382 | =for hackers | |
383 | Found in file hv.c | |
384 | ||
b3ca2e83 NC |
385 | =item refcounted_he_free |
386 | X<refcounted_he_free> | |
387 | ||
388 | Decrements the reference count of the passed in C<struct refcounted_he *> | |
389 | by one. If the reference count reaches zero the structure's memory is freed, | |
390 | and C<refcounted_he_free> iterates onto the parent node. | |
391 | ||
392 | void refcounted_he_free(struct refcounted_he *he) | |
393 | ||
394 | =for hackers | |
395 | Found in file hv.c | |
396 | ||
397 | =item refcounted_he_new | |
398 | X<refcounted_he_new> | |
399 | ||
ec2a1de7 NC |
400 | Creates a new C<struct refcounted_he>. As S<key> is copied, and value is |
401 | stored in a compact form, all references remain the property of the caller. | |
402 | The C<struct refcounted_he> is returned with a reference count of 1. | |
b3ca2e83 | 403 | |
b46c265e | 404 | struct refcounted_he * refcounted_he_new(struct refcounted_he *const parent, SV *const key, SV *const value) |
b3ca2e83 NC |
405 | |
406 | =for hackers | |
407 | Found in file hv.c | |
408 | ||
409 | ||
410 | =back | |
411 | ||
a4f1a029 NIS |
412 | =head1 IO Functions |
413 | ||
414 | =over 8 | |
645c22ef | 415 | |
a8586c98 | 416 | =item start_glob |
d8c40edc | 417 | X<start_glob> |
a8586c98 JH |
418 | |
419 | Function called by C<do_readline> to spawn a glob (or do the glob inside | |
420 | perl on VMS). This code used to be inline, but now perl uses C<File::Glob> | |
bd16a5f0 | 421 | this glob starter is only used by miniperl during the build process. |
a8586c98 JH |
422 | Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up. |
423 | ||
424 | PerlIO* start_glob(SV* pattern, IO *io) | |
425 | ||
426 | =for hackers | |
427 | Found in file doio.c | |
428 | ||
a4f1a029 NIS |
429 | |
430 | =back | |
431 | ||
0cbee0a4 DM |
432 | =head1 Magical Functions |
433 | ||
434 | =over 8 | |
435 | ||
b3ca2e83 NC |
436 | =item magic_sethint |
437 | X<magic_sethint> | |
438 | ||
c28fe1ec NC |
439 | Triggered by a delete from %^H, records the key to |
440 | C<PL_compiling.cop_hints_hash>. | |
b3ca2e83 NC |
441 | |
442 | int magic_sethint(SV* sv, MAGIC* mg) | |
443 | ||
444 | =for hackers | |
445 | Found in file mg.c | |
446 | ||
0cbee0a4 | 447 | =item mg_localize |
d8c40edc | 448 | X<mg_localize> |
0cbee0a4 DM |
449 | |
450 | Copy some of the magic from an existing SV to new localized version of | |
451 | that SV. Container magic (eg %ENV, $1, tie) gets copied, value magic | |
452 | doesn't (eg taint, pos). | |
453 | ||
454 | void mg_localize(SV* sv, SV* nsv) | |
455 | ||
456 | =for hackers | |
457 | Found in file mg.c | |
458 | ||
459 | ||
460 | =back | |
461 | ||
47c9dd14 BB |
462 | =head1 MRO Functions |
463 | ||
464 | =over 8 | |
465 | ||
c74c7a1e NC |
466 | =item mro_get_linear_isa_c3 |
467 | X<mro_get_linear_isa_c3> | |
468 | ||
469 | Returns the C3 linearization of @ISA | |
470 | the given stash. The return value is a read-only AV*. | |
471 | C<level> should be 0 (it is used internally in this | |
472 | function's recursion). | |
473 | ||
474 | You are responsible for C<SvREFCNT_inc()> on the | |
475 | return value if you plan to store it anywhere | |
476 | semi-permanently (otherwise it might be deleted | |
477 | out from under you the next time the cache is | |
478 | invalidated). | |
479 | ||
480 | AV* mro_get_linear_isa_c3(HV* stash, I32 level) | |
481 | ||
482 | =for hackers | |
483 | Found in file mro.c | |
484 | ||
485 | =item mro_get_linear_isa_dfs | |
486 | X<mro_get_linear_isa_dfs> | |
487 | ||
488 | Returns the Depth-First Search linearization of @ISA | |
489 | the given stash. The return value is a read-only AV*. | |
490 | C<level> should be 0 (it is used internally in this | |
491 | function's recursion). | |
492 | ||
493 | You are responsible for C<SvREFCNT_inc()> on the | |
494 | return value if you plan to store it anywhere | |
495 | semi-permanently (otherwise it might be deleted | |
496 | out from under you the next time the cache is | |
497 | invalidated). | |
498 | ||
499 | AV* mro_get_linear_isa_dfs(HV* stash, I32 level) | |
500 | ||
501 | =for hackers | |
502 | Found in file mro.c | |
503 | ||
47c9dd14 BB |
504 | =item mro_isa_changed_in |
505 | X<mro_isa_changed_in> | |
506 | ||
507 | Takes the necessary steps (cache invalidations, mostly) | |
508 | when the @ISA of the given package has changed. Invoked | |
509 | by the C<setisa> magic, should not need to invoke directly. | |
510 | ||
511 | void mro_isa_changed_in(HV* stash) | |
512 | ||
513 | =for hackers | |
514 | Found in file mro.c | |
515 | ||
516 | ||
517 | =back | |
518 | ||
a4f1a029 NIS |
519 | =head1 Pad Data Structures |
520 | ||
521 | =over 8 | |
522 | ||
523 | =item CvPADLIST | |
d8c40edc | 524 | X<CvPADLIST> |
a4f1a029 NIS |
525 | |
526 | CV's can have CvPADLIST(cv) set to point to an AV. | |
527 | ||
528 | For these purposes "forms" are a kind-of CV, eval""s are too (except they're | |
529 | not callable at will and are always thrown away after the eval"" is done | |
b5c19bd7 DM |
530 | executing). Require'd files are simply evals without any outer lexical |
531 | scope. | |
a4f1a029 NIS |
532 | |
533 | XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad, | |
534 | but that is really the callers pad (a slot of which is allocated by | |
535 | every entersub). | |
536 | ||
537 | The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items | |
f3548bdc | 538 | is managed "manual" (mostly in pad.c) rather than normal av.c rules. |
a4f1a029 NIS |
539 | The items in the AV are not SVs as for a normal AV, but other AVs: |
540 | ||
541 | 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather | |
542 | the "static type information" for lexicals. | |
543 | ||
544 | The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that | |
545 | depth of recursion into the CV. | |
546 | The 0'th slot of a frame AV is an AV which is @_. | |
547 | other entries are storage for variables and op targets. | |
548 | ||
549 | During compilation: | |
a6d05634 TM |
550 | C<PL_comppad_name> is set to the names AV. |
551 | C<PL_comppad> is set to the frame AV for the frame CvDEPTH == 1. | |
552 | C<PL_curpad> is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)). | |
a4f1a029 | 553 | |
f3548bdc DM |
554 | During execution, C<PL_comppad> and C<PL_curpad> refer to the live |
555 | frame of the currently executing sub. | |
556 | ||
557 | Iterating over the names AV iterates over all possible pad | |
a4f1a029 NIS |
558 | items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having |
559 | &PL_sv_undef "names" (see pad_alloc()). | |
560 | ||
561 | Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names. | |
562 | The rest are op targets/GVs/constants which are statically allocated | |
563 | or resolved at compile time. These don't have names by which they | |
564 | can be looked up from Perl code at run time through eval"" like | |
565 | my/our variables can be. Since they can't be looked up by "name" | |
566 | but only by their index allocated at compile time (which is usually | |
567 | in PL_op->op_targ), wasting a name SV for them doesn't make sense. | |
568 | ||
569 | The SVs in the names AV have their PV being the name of the variable. | |
00a0d662 NC |
570 | xlow+1..xhigh inclusive in the NV union is a range of cop_seq numbers for |
571 | which the name is valid. For typed lexicals name SV is SVt_PVMG and SvSTASH | |
572 | points at the type. For C<our> lexicals, the type is also SVt_PVMG, with the | |
44a2ac75 | 573 | SvOURSTASH slot pointing at the stash of the associated global (so that |
00a0d662 NC |
574 | duplicate C<our> declarations in the same package can be detected). SvUVX is |
575 | sometimes hijacked to store the generation number during compilation. | |
a4f1a029 | 576 | |
b5c19bd7 DM |
577 | If SvFAKE is set on the name SV, then that slot in the frame AV is |
578 | a REFCNT'ed reference to a lexical from "outside". In this case, | |
00a0d662 NC |
579 | the name SV does not use xlow and xhigh to store a cop_seq range, since it is |
580 | in scope throughout. Instead xhigh stores some flags containing info about | |
b5c19bd7 | 581 | the real lexical (is it declared in an anon, and is it capable of being |
00a0d662 | 582 | instantiated multiple times?), and for fake ANONs, xlow contains the index |
b5c19bd7 DM |
583 | within the parent's pad where the lexical's value is stored, to make |
584 | cloning quicker. | |
a4f1a029 | 585 | |
a6d05634 | 586 | If the 'name' is '&' the corresponding entry in frame AV |
a4f1a029 NIS |
587 | is a CV representing a possible closure. |
588 | (SvFAKE and name of '&' is not a meaningful combination currently but could | |
589 | become so if C<my sub foo {}> is implemented.) | |
590 | ||
5c3943b6 RGS |
591 | Note that formats are treated as anon subs, and are cloned each time |
592 | write is called (if necessary). | |
593 | ||
2814eb74 PJ |
594 | The flag SVf_PADSTALE is cleared on lexicals each time the my() is executed, |
595 | and set on scope exit. This allows the 'Variable $x is not available' warning | |
596 | to be generated in evals, such as | |
597 | ||
598 | { my $x = 1; sub f { eval '$x'} } f(); | |
599 | ||
a4f1a029 NIS |
600 | AV * CvPADLIST(CV *cv) |
601 | ||
602 | =for hackers | |
dd2155a4 DM |
603 | Found in file pad.c |
604 | ||
605 | =item cv_clone | |
d8c40edc | 606 | X<cv_clone> |
dd2155a4 DM |
607 | |
608 | Clone a CV: make a new CV which points to the same code etc, but which | |
ad63d80f | 609 | has a newly-created pad built by copying the prototype pad and capturing |
dd2155a4 DM |
610 | any outer lexicals. |
611 | ||
612 | CV* cv_clone(CV* proto) | |
613 | ||
614 | =for hackers | |
615 | Found in file pad.c | |
616 | ||
617 | =item cv_dump | |
d8c40edc | 618 | X<cv_dump> |
dd2155a4 DM |
619 | |
620 | dump the contents of a CV | |
621 | ||
e1ec3a88 | 622 | void cv_dump(const CV *cv, const char *title) |
dd2155a4 DM |
623 | |
624 | =for hackers | |
625 | Found in file pad.c | |
626 | ||
627 | =item do_dump_pad | |
d8c40edc | 628 | X<do_dump_pad> |
dd2155a4 DM |
629 | |
630 | Dump the contents of a padlist | |
631 | ||
632 | void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full) | |
633 | ||
634 | =for hackers | |
635 | Found in file pad.c | |
636 | ||
637 | =item intro_my | |
d8c40edc | 638 | X<intro_my> |
dd2155a4 DM |
639 | |
640 | "Introduce" my variables to visible status. | |
641 | ||
642 | U32 intro_my() | |
643 | ||
644 | =for hackers | |
645 | Found in file pad.c | |
646 | ||
647 | =item pad_add_anon | |
d8c40edc | 648 | X<pad_add_anon> |
dd2155a4 DM |
649 | |
650 | Add an anon code entry to the current compiling pad | |
651 | ||
652 | PADOFFSET pad_add_anon(SV* sv, OPCODE op_type) | |
653 | ||
654 | =for hackers | |
655 | Found in file pad.c | |
656 | ||
657 | =item pad_add_name | |
d8c40edc | 658 | X<pad_add_name> |
dd2155a4 | 659 | |
b5c19bd7 DM |
660 | Create a new name and associated PADMY SV in the current pad; return the |
661 | offset. | |
dd2155a4 DM |
662 | If C<typestash> is valid, the name is for a typed lexical; set the |
663 | name's stash to that value. | |
664 | If C<ourstash> is valid, it's an our lexical, set the name's | |
44a2ac75 | 665 | SvOURSTASH to that value |
dd2155a4 | 666 | |
dd2155a4 DM |
667 | If fake, it means we're cloning an existing entry |
668 | ||
952306ac | 669 | PADOFFSET pad_add_name(const char *name, HV* typestash, HV* ourstash, bool clone, bool state) |
dd2155a4 DM |
670 | |
671 | =for hackers | |
672 | Found in file pad.c | |
673 | ||
674 | =item pad_alloc | |
d8c40edc | 675 | X<pad_alloc> |
dd2155a4 DM |
676 | |
677 | Allocate a new my or tmp pad entry. For a my, simply push a null SV onto | |
678 | the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards | |
324092c6 | 679 | for a slot which has no name and no active value. |
dd2155a4 DM |
680 | |
681 | PADOFFSET pad_alloc(I32 optype, U32 tmptype) | |
682 | ||
683 | =for hackers | |
684 | Found in file pad.c | |
685 | ||
686 | =item pad_block_start | |
d8c40edc | 687 | X<pad_block_start> |
dd2155a4 DM |
688 | |
689 | Update the pad compilation state variables on entry to a new block | |
690 | ||
691 | void pad_block_start(int full) | |
692 | ||
693 | =for hackers | |
694 | Found in file pad.c | |
695 | ||
696 | =item pad_check_dup | |
d8c40edc | 697 | X<pad_check_dup> |
dd2155a4 DM |
698 | |
699 | Check for duplicate declarations: report any of: | |
700 | * a my in the current scope with the same name; | |
701 | * an our (anywhere in the pad) with the same name and the same stash | |
702 | as C<ourstash> | |
703 | C<is_our> indicates that the name to check is an 'our' declaration | |
704 | ||
e1ec3a88 | 705 | void pad_check_dup(const char* name, bool is_our, const HV* ourstash) |
dd2155a4 DM |
706 | |
707 | =for hackers | |
708 | Found in file pad.c | |
709 | ||
710 | =item pad_findlex | |
d8c40edc | 711 | X<pad_findlex> |
dd2155a4 DM |
712 | |
713 | Find a named lexical anywhere in a chain of nested pads. Add fake entries | |
b5c19bd7 DM |
714 | in the inner pads if it's found in an outer one. |
715 | ||
716 | Returns the offset in the bottom pad of the lex or the fake lex. | |
717 | cv is the CV in which to start the search, and seq is the current cop_seq | |
718 | to match against. If warn is true, print appropriate warnings. The out_* | |
719 | vars return values, and so are pointers to where the returned values | |
720 | should be stored. out_capture, if non-null, requests that the innermost | |
721 | instance of the lexical is captured; out_name_sv is set to the innermost | |
722 | matched namesv or fake namesv; out_flags returns the flags normally | |
723 | associated with the IVX field of a fake namesv. | |
724 | ||
725 | Note that pad_findlex() is recursive; it recurses up the chain of CVs, | |
726 | then comes back down, adding fake entries as it goes. It has to be this way | |
00a0d662 | 727 | because fake namesvs in anon protoypes have to store in xlow the index into |
b5c19bd7 DM |
728 | the parent pad. |
729 | ||
e1ec3a88 | 730 | PADOFFSET pad_findlex(const char *name, const CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags) |
dd2155a4 DM |
731 | |
732 | =for hackers | |
733 | Found in file pad.c | |
734 | ||
735 | =item pad_findmy | |
d8c40edc | 736 | X<pad_findmy> |
dd2155a4 | 737 | |
ad63d80f | 738 | Given a lexical name, try to find its offset, first in the current pad, |
dd2155a4 | 739 | or failing that, in the pads of any lexically enclosing subs (including |
ad63d80f JP |
740 | the complications introduced by eval). If the name is found in an outer pad, |
741 | then a fake entry is added to the current pad. | |
dd2155a4 DM |
742 | Returns the offset in the current pad, or NOT_IN_PAD on failure. |
743 | ||
e1ec3a88 | 744 | PADOFFSET pad_findmy(const char* name) |
dd2155a4 DM |
745 | |
746 | =for hackers | |
747 | Found in file pad.c | |
748 | ||
749 | =item pad_fixup_inner_anons | |
d8c40edc | 750 | X<pad_fixup_inner_anons> |
dd2155a4 DM |
751 | |
752 | For any anon CVs in the pad, change CvOUTSIDE of that CV from | |
7dafbf52 DM |
753 | old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be |
754 | moved to a pre-existing CV struct. | |
dd2155a4 DM |
755 | |
756 | void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv) | |
757 | ||
758 | =for hackers | |
759 | Found in file pad.c | |
760 | ||
761 | =item pad_free | |
d8c40edc | 762 | X<pad_free> |
dd2155a4 | 763 | |
d7f8936a | 764 | Free the SV at offset po in the current pad. |
dd2155a4 DM |
765 | |
766 | void pad_free(PADOFFSET po) | |
767 | ||
768 | =for hackers | |
769 | Found in file pad.c | |
770 | ||
771 | =item pad_leavemy | |
d8c40edc | 772 | X<pad_leavemy> |
dd2155a4 DM |
773 | |
774 | Cleanup at end of scope during compilation: set the max seq number for | |
775 | lexicals in this scope and warn of any lexicals that never got introduced. | |
776 | ||
777 | void pad_leavemy() | |
778 | ||
779 | =for hackers | |
780 | Found in file pad.c | |
781 | ||
782 | =item pad_new | |
d8c40edc | 783 | X<pad_new> |
dd2155a4 | 784 | |
ad63d80f | 785 | Create a new compiling padlist, saving and updating the various global |
dd2155a4 DM |
786 | vars at the same time as creating the pad itself. The following flags |
787 | can be OR'ed together: | |
788 | ||
789 | padnew_CLONE this pad is for a cloned CV | |
790 | padnew_SAVE save old globals | |
791 | padnew_SAVESUB also save extra stuff for start of sub | |
792 | ||
c7c737cb | 793 | PADLIST* pad_new(int flags) |
dd2155a4 DM |
794 | |
795 | =for hackers | |
796 | Found in file pad.c | |
797 | ||
798 | =item pad_push | |
d8c40edc | 799 | X<pad_push> |
dd2155a4 DM |
800 | |
801 | Push a new pad frame onto the padlist, unless there's already a pad at | |
26019298 AL |
802 | this depth, in which case don't bother creating a new one. Then give |
803 | the new pad an @_ in slot zero. | |
dd2155a4 | 804 | |
26019298 | 805 | void pad_push(PADLIST *padlist, int depth) |
dd2155a4 DM |
806 | |
807 | =for hackers | |
808 | Found in file pad.c | |
809 | ||
810 | =item pad_reset | |
d8c40edc | 811 | X<pad_reset> |
dd2155a4 DM |
812 | |
813 | Mark all the current temporaries for reuse | |
814 | ||
815 | void pad_reset() | |
816 | ||
817 | =for hackers | |
818 | Found in file pad.c | |
819 | ||
820 | =item pad_setsv | |
d8c40edc | 821 | X<pad_setsv> |
dd2155a4 DM |
822 | |
823 | Set the entry at offset po in the current pad to sv. | |
824 | Use the macro PAD_SETSV() rather than calling this function directly. | |
825 | ||
826 | void pad_setsv(PADOFFSET po, SV* sv) | |
827 | ||
828 | =for hackers | |
829 | Found in file pad.c | |
830 | ||
831 | =item pad_swipe | |
d8c40edc | 832 | X<pad_swipe> |
dd2155a4 DM |
833 | |
834 | Abandon the tmp in the current pad at offset po and replace with a | |
835 | new one. | |
836 | ||
837 | void pad_swipe(PADOFFSET po, bool refadjust) | |
838 | ||
839 | =for hackers | |
840 | Found in file pad.c | |
841 | ||
842 | =item pad_tidy | |
d8c40edc | 843 | X<pad_tidy> |
dd2155a4 DM |
844 | |
845 | Tidy up a pad after we've finished compiling it: | |
846 | * remove most stuff from the pads of anonsub prototypes; | |
847 | * give it a @_; | |
848 | * mark tmps as such. | |
849 | ||
850 | void pad_tidy(padtidy_type type) | |
851 | ||
852 | =for hackers | |
853 | Found in file pad.c | |
854 | ||
855 | =item pad_undef | |
d8c40edc | 856 | X<pad_undef> |
dd2155a4 DM |
857 | |
858 | Free the padlist associated with a CV. | |
859 | If parts of it happen to be current, we null the relevant | |
860 | PL_*pad* global vars so that we don't have any dangling references left. | |
861 | We also repoint the CvOUTSIDE of any about-to-be-orphaned | |
a3985cdc | 862 | inner subs to the outer of this cv. |
dd2155a4 | 863 | |
7dafbf52 DM |
864 | (This function should really be called pad_free, but the name was already |
865 | taken) | |
866 | ||
a3985cdc | 867 | void pad_undef(CV* cv) |
dd2155a4 DM |
868 | |
869 | =for hackers | |
870 | Found in file pad.c | |
a4f1a029 NIS |
871 | |
872 | ||
873 | =back | |
874 | ||
907b3e23 DM |
875 | =head1 Per-Interpreter Variables |
876 | ||
877 | =over 8 | |
878 | ||
879 | =item PL_DBsingle | |
880 | X<PL_DBsingle> | |
881 | ||
882 | When Perl is run in debugging mode, with the B<-d> switch, this SV is a | |
883 | boolean which indicates whether subs are being single-stepped. | |
884 | Single-stepping is automatically turned on after every step. This is the C | |
885 | variable which corresponds to Perl's $DB::single variable. See | |
886 | C<PL_DBsub>. | |
887 | ||
888 | SV * PL_DBsingle | |
889 | ||
890 | =for hackers | |
891 | Found in file intrpvar.h | |
892 | ||
893 | =item PL_DBsub | |
894 | X<PL_DBsub> | |
895 | ||
896 | When Perl is run in debugging mode, with the B<-d> switch, this GV contains | |
897 | the SV which holds the name of the sub being debugged. This is the C | |
898 | variable which corresponds to Perl's $DB::sub variable. See | |
899 | C<PL_DBsingle>. | |
900 | ||
901 | GV * PL_DBsub | |
902 | ||
903 | =for hackers | |
904 | Found in file intrpvar.h | |
905 | ||
906 | =item PL_DBtrace | |
907 | X<PL_DBtrace> | |
908 | ||
909 | Trace variable used when Perl is run in debugging mode, with the B<-d> | |
910 | switch. This is the C variable which corresponds to Perl's $DB::trace | |
911 | variable. See C<PL_DBsingle>. | |
912 | ||
913 | SV * PL_DBtrace | |
914 | ||
915 | =for hackers | |
916 | Found in file intrpvar.h | |
917 | ||
918 | =item PL_dowarn | |
919 | X<PL_dowarn> | |
920 | ||
921 | The C variable which corresponds to Perl's $^W warning variable. | |
922 | ||
923 | bool PL_dowarn | |
924 | ||
925 | =for hackers | |
926 | Found in file intrpvar.h | |
927 | ||
928 | =item PL_last_in_gv | |
929 | X<PL_last_in_gv> | |
930 | ||
931 | The GV which was last used for a filehandle input operation. (C<< <FH> >>) | |
932 | ||
933 | GV* PL_last_in_gv | |
934 | ||
935 | =for hackers | |
936 | Found in file intrpvar.h | |
937 | ||
938 | =item PL_ofs_sv | |
939 | X<PL_ofs_sv> | |
940 | ||
941 | The output field separator - C<$,> in Perl space. | |
942 | ||
943 | SV* PL_ofs_sv | |
944 | ||
945 | =for hackers | |
946 | Found in file intrpvar.h | |
947 | ||
948 | =item PL_rs | |
949 | X<PL_rs> | |
950 | ||
951 | The input record separator - C<$/> in Perl space. | |
952 | ||
953 | SV* PL_rs | |
954 | ||
955 | =for hackers | |
956 | Found in file intrpvar.h | |
957 | ||
958 | ||
959 | =back | |
960 | ||
a4f1a029 NIS |
961 | =head1 Stack Manipulation Macros |
962 | ||
963 | =over 8 | |
964 | ||
965 | =item djSP | |
d8c40edc | 966 | X<djSP> |
a4f1a029 NIS |
967 | |
968 | Declare Just C<SP>. This is actually identical to C<dSP>, and declares | |
969 | a local copy of perl's stack pointer, available via the C<SP> macro. | |
970 | See C<SP>. (Available for backward source code compatibility with the | |
971 | old (Perl 5.005) thread model.) | |
972 | ||
973 | djSP; | |
974 | ||
975 | =for hackers | |
976 | Found in file pp.h | |
977 | ||
978 | =item LVRET | |
d8c40edc | 979 | X<LVRET> |
a4f1a029 NIS |
980 | |
981 | True if this op will be the return value of an lvalue subroutine | |
982 | ||
983 | =for hackers | |
984 | Found in file pp.h | |
985 | ||
986 | ||
987 | =back | |
988 | ||
989 | =head1 SV Manipulation Functions | |
990 | ||
991 | =over 8 | |
992 | ||
645c22ef | 993 | =item sv_add_arena |
d8c40edc | 994 | X<sv_add_arena> |
645c22ef DM |
995 | |
996 | Given a chunk of memory, link it to the head of the list of arenas, | |
997 | and split it into a list of free SVs. | |
998 | ||
999 | void sv_add_arena(char* ptr, U32 size, U32 flags) | |
1000 | ||
1001 | =for hackers | |
1002 | Found in file sv.c | |
1003 | ||
1004 | =item sv_clean_all | |
d8c40edc | 1005 | X<sv_clean_all> |
645c22ef DM |
1006 | |
1007 | Decrement the refcnt of each remaining SV, possibly triggering a | |
1008 | cleanup. This function may have to be called multiple times to free | |
8fb26106 | 1009 | SVs which are in complex self-referential hierarchies. |
645c22ef DM |
1010 | |
1011 | I32 sv_clean_all() | |
1012 | ||
1013 | =for hackers | |
1014 | Found in file sv.c | |
1015 | ||
1016 | =item sv_clean_objs | |
d8c40edc | 1017 | X<sv_clean_objs> |
645c22ef DM |
1018 | |
1019 | Attempt to destroy all objects not yet freed | |
1020 | ||
1021 | void sv_clean_objs() | |
1022 | ||
1023 | =for hackers | |
1024 | Found in file sv.c | |
1025 | ||
1026 | =item sv_free_arenas | |
d8c40edc | 1027 | X<sv_free_arenas> |
645c22ef DM |
1028 | |
1029 | Deallocate the memory used by all arenas. Note that all the individual SV | |
1030 | heads and bodies within the arenas must already have been freed. | |
1031 | ||
1032 | void sv_free_arenas() | |
1033 | ||
1034 | =for hackers | |
1035 | Found in file sv.c | |
1036 | ||
a4f1a029 | 1037 | |
954c1994 GS |
1038 | =back |
1039 | ||
800401ee JH |
1040 | =head1 SV-Body Allocation |
1041 | ||
1042 | =over 8 | |
1043 | ||
1044 | =item sv_2num | |
1045 | X<sv_2num> | |
1046 | ||
1047 | Return an SV with the numeric value of the source SV, doing any necessary | |
a196a5fa JH |
1048 | reference or overload conversion. You must use the C<SvNUM(sv)> macro to |
1049 | access this function. | |
800401ee JH |
1050 | |
1051 | SV* sv_2num(SV* sv) | |
1052 | ||
1053 | =for hackers | |
1054 | Found in file sv.c | |
1055 | ||
1056 | ||
1057 | =back | |
1058 | ||
979f2922 ST |
1059 | =head1 Unicode Support |
1060 | ||
1061 | =over 8 | |
1062 | ||
1063 | =item find_uninit_var | |
1064 | X<find_uninit_var> | |
1065 | ||
1066 | Find the name of the undefined variable (if any) that caused the operator o | |
1067 | to issue a "Use of uninitialized value" warning. | |
1068 | If match is true, only return a name if it's value matches uninit_sv. | |
1069 | So roughly speaking, if a unary operator (such as OP_COS) generates a | |
1070 | warning, then following the direct child of the op may yield an | |
1071 | OP_PADSV or OP_GV that gives the name of the undefined variable. On the | |
1072 | other hand, with OP_ADD there are two branches to follow, so we only print | |
1073 | the variable name if we get an exact match. | |
1074 | ||
1075 | The name is returned as a mortal SV. | |
1076 | ||
1077 | Assumes that PL_op is the op that originally triggered the error, and that | |
1078 | PL_comppad/PL_curpad points to the currently executing pad. | |
1079 | ||
1080 | SV* find_uninit_var(OP* obase, SV* uninit_sv, bool top) | |
1081 | ||
1082 | =for hackers | |
1083 | Found in file sv.c | |
1084 | ||
1085 | =item report_uninit | |
1086 | X<report_uninit> | |
1087 | ||
1088 | Print appropriate "Use of uninitialized variable" warning | |
1089 | ||
1090 | void report_uninit(SV* uninit_sv) | |
1091 | ||
1092 | =for hackers | |
1093 | Found in file sv.c | |
1094 | ||
1095 | ||
1096 | =back | |
1097 | ||
954c1994 GS |
1098 | =head1 AUTHORS |
1099 | ||
1c846c1f NIS |
1100 | The autodocumentation system was originally added to the Perl core by |
1101 | Benjamin Stuhl. Documentation is by whoever was kind enough to | |
954c1994 GS |
1102 | document their functions. |
1103 | ||
1104 | =head1 SEE ALSO | |
1105 | ||
1106 | perlguts(1), perlapi(1) | |
1107 | ||
3f98fbb3 RGS |
1108 | =cut |
1109 | ||
1110 | ex: set ro: |