Commit | Line | Data |
3f98fbb3 |
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 |
7 | =head1 NAME |
8 | |
1c846c1f |
9 | perlintern - autogenerated documentation of purely B<internal> |
954c1994 |
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 |
18 | B<they are not for use in extensions>! |
19 | |
a8586c98 |
20 | |
7dafbf52 |
21 | =head1 CV reference counts and CvOUTSIDE |
22 | |
23 | =over 8 |
24 | |
25 | =item CvWEAKOUTSIDE |
d8c40edc |
26 | X<CvWEAKOUTSIDE> |
7dafbf52 |
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 |
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 |
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 |
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 |
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 |
105 | |
106 | =for hackers |
107 | Found in file pad.h |
108 | |
d8c40edc |
109 | =item PAD_BASE_SV |
110 | X<PAD_BASE_SV> |
dd2155a4 |
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 |
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 |
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 |
125 | |
126 | =for hackers |
127 | Found in file pad.h |
128 | |
129 | =item PAD_COMPNAME_FLAGS |
d8c40edc |
130 | X<PAD_COMPNAME_FLAGS> |
dd2155a4 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
236 | =item PAD_SETSV |
237 | X<PAD_SETSV> |
dd2155a4 |
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 |
242 | |
243 | =for hackers |
244 | Found in file pad.h |
245 | |
d8c40edc |
246 | =item PAD_SET_CUR |
247 | X<PAD_SET_CUR> |
dd2155a4 |
248 | |
249 | Set the current pad to be pad C<n> in the padlist, saving |
f54ba1c2 |
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 |
258 | |
259 | =for hackers |
260 | Found in file pad.h |
261 | |
d8c40edc |
262 | =item PAD_SET_CUR_NOSAVE |
263 | X<PAD_SET_CUR_NOSAVE> |
bf9cdc68 |
264 | |
265 | like PAD_SET_CUR, but without the save |
266 | |
d8c40edc |
267 | void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n) |
bf9cdc68 |
268 | |
269 | =for hackers |
270 | Found in file pad.h |
271 | |
d8c40edc |
272 | =item PAD_SV |
273 | X<PAD_SV> |
dd2155a4 |
274 | |
275 | Get the value at offset C<po> in the current pad |
276 | |
d8c40edc |
277 | void PAD_SV(PADOFFSET po) |
dd2155a4 |
278 | |
279 | =for hackers |
280 | Found in file pad.h |
281 | |
d8c40edc |
282 | =item PAD_SVl |
283 | X<PAD_SVl> |
dd2155a4 |
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 |
291 | |
292 | =for hackers |
293 | Found in file pad.h |
294 | |
d8c40edc |
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 |
301 | |
302 | =for hackers |
303 | Found in file pad.h |
304 | |
305 | =item SAVECOMPPAD |
d8c40edc |
306 | X<SAVECOMPPAD> |
dd2155a4 |
307 | |
308 | save PL_comppad and PL_curpad |
309 | |
dd2155a4 |
310 | |
dd2155a4 |
311 | |
312 | |
313 | |
f3548bdc |
314 | void SAVECOMPPAD() |
dd2155a4 |
315 | |
316 | =for hackers |
317 | Found in file pad.h |
318 | |
d8c40edc |
319 | =item SAVEPADSV |
320 | X<SAVEPADSV> |
dd2155a4 |
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 |
326 | |
327 | =for hackers |
328 | Found in file pad.h |
329 | |
330 | |
331 | =back |
332 | |
a4f1a029 |
333 | =head1 GV Functions |
334 | |
335 | =over 8 |
336 | |
337 | =item is_gv_magical |
d8c40edc |
338 | X<is_gv_magical> |
a4f1a029 |
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 |
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 |
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 |
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 |
363 | |
364 | =for hackers |
a4f1a029 |
365 | Found in file gv.c |
366 | |
367 | |
368 | =back |
369 | |
b3ca2e83 |
370 | =head1 Hash Manipulation Functions |
371 | |
372 | =over 8 |
373 | |
bd95ae50 |
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 |
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 |
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 |
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 |
405 | |
406 | =for hackers |
407 | Found in file hv.c |
408 | |
409 | |
410 | =back |
411 | |
a4f1a029 |
412 | =head1 IO Functions |
413 | |
414 | =over 8 |
645c22ef |
415 | |
a8586c98 |
416 | =item start_glob |
d8c40edc |
417 | X<start_glob> |
a8586c98 |
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 |
422 | Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up. |
423 | |
4048f010 |
424 | PerlIO* start_glob(SV *tmpglob, IO *io) |
a8586c98 |
425 | |
426 | =for hackers |
427 | Found in file doio.c |
428 | |
a4f1a029 |
429 | |
430 | =back |
431 | |
0cbee0a4 |
432 | =head1 Magical Functions |
433 | |
434 | =over 8 |
435 | |
f175cff5 |
436 | =item magic_clearhint |
437 | X<magic_clearhint> |
b3ca2e83 |
438 | |
c28fe1ec |
439 | Triggered by a delete from %^H, records the key to |
440 | C<PL_compiling.cop_hints_hash>. |
b3ca2e83 |
441 | |
f175cff5 |
442 | int magic_clearhint(SV* sv, MAGIC* mg) |
443 | |
444 | =for hackers |
445 | Found in file mg.c |
446 | |
447 | =item magic_sethint |
448 | X<magic_sethint> |
449 | |
450 | Triggered by a store to %^H, records the key/value pair to |
451 | C<PL_compiling.cop_hints_hash>. It is assumed that hints aren't storing |
452 | anything that would need a deep copy. Maybe we should warn if we find a |
453 | reference. |
454 | |
b3ca2e83 |
455 | int magic_sethint(SV* sv, MAGIC* mg) |
456 | |
457 | =for hackers |
458 | Found in file mg.c |
459 | |
0cbee0a4 |
460 | =item mg_localize |
d8c40edc |
461 | X<mg_localize> |
0cbee0a4 |
462 | |
64f0785e |
463 | Copy some of the magic from an existing SV to new localized version of that |
464 | SV. Container magic (eg %ENV, $1, tie) gets copied, value magic doesn't (eg |
465 | taint, pos). |
0cbee0a4 |
466 | |
af7df257 |
467 | If setmagic is false then no set magic will be called on the new (empty) SV. |
64f0785e |
468 | This typically means that assignment will soon follow (e.g. 'local $x = $y'), |
469 | and that will handle the magic. |
470 | |
af7df257 |
471 | void mg_localize(SV* sv, SV* nsv, bool setmagic) |
0cbee0a4 |
472 | |
473 | =for hackers |
474 | Found in file mg.c |
475 | |
476 | |
477 | =back |
478 | |
47c9dd14 |
479 | =head1 MRO Functions |
480 | |
481 | =over 8 |
482 | |
c74c7a1e |
483 | =item mro_get_linear_isa_c3 |
484 | X<mro_get_linear_isa_c3> |
485 | |
486 | Returns the C3 linearization of @ISA |
487 | the given stash. The return value is a read-only AV*. |
488 | C<level> should be 0 (it is used internally in this |
489 | function's recursion). |
490 | |
491 | You are responsible for C<SvREFCNT_inc()> on the |
492 | return value if you plan to store it anywhere |
493 | semi-permanently (otherwise it might be deleted |
494 | out from under you the next time the cache is |
495 | invalidated). |
496 | |
497 | AV* mro_get_linear_isa_c3(HV* stash, I32 level) |
498 | |
499 | =for hackers |
500 | Found in file mro.c |
501 | |
502 | =item mro_get_linear_isa_dfs |
503 | X<mro_get_linear_isa_dfs> |
504 | |
505 | Returns the Depth-First Search linearization of @ISA |
506 | the given stash. The return value is a read-only AV*. |
507 | C<level> should be 0 (it is used internally in this |
508 | function's recursion). |
509 | |
510 | You are responsible for C<SvREFCNT_inc()> on the |
511 | return value if you plan to store it anywhere |
512 | semi-permanently (otherwise it might be deleted |
513 | out from under you the next time the cache is |
514 | invalidated). |
515 | |
516 | AV* mro_get_linear_isa_dfs(HV* stash, I32 level) |
517 | |
518 | =for hackers |
519 | Found in file mro.c |
520 | |
47c9dd14 |
521 | =item mro_isa_changed_in |
522 | X<mro_isa_changed_in> |
523 | |
524 | Takes the necessary steps (cache invalidations, mostly) |
525 | when the @ISA of the given package has changed. Invoked |
526 | by the C<setisa> magic, should not need to invoke directly. |
527 | |
528 | void mro_isa_changed_in(HV* stash) |
529 | |
530 | =for hackers |
531 | Found in file mro.c |
532 | |
533 | |
534 | =back |
535 | |
a4f1a029 |
536 | =head1 Pad Data Structures |
537 | |
538 | =over 8 |
539 | |
540 | =item CvPADLIST |
d8c40edc |
541 | X<CvPADLIST> |
a4f1a029 |
542 | |
543 | CV's can have CvPADLIST(cv) set to point to an AV. |
544 | |
545 | For these purposes "forms" are a kind-of CV, eval""s are too (except they're |
546 | not callable at will and are always thrown away after the eval"" is done |
b5c19bd7 |
547 | executing). Require'd files are simply evals without any outer lexical |
548 | scope. |
a4f1a029 |
549 | |
550 | XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad, |
551 | but that is really the callers pad (a slot of which is allocated by |
552 | every entersub). |
553 | |
554 | The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items |
f3548bdc |
555 | is managed "manual" (mostly in pad.c) rather than normal av.c rules. |
a4f1a029 |
556 | The items in the AV are not SVs as for a normal AV, but other AVs: |
557 | |
558 | 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather |
559 | the "static type information" for lexicals. |
560 | |
561 | The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that |
562 | depth of recursion into the CV. |
563 | The 0'th slot of a frame AV is an AV which is @_. |
564 | other entries are storage for variables and op targets. |
565 | |
566 | During compilation: |
a6d05634 |
567 | C<PL_comppad_name> is set to the names AV. |
568 | C<PL_comppad> is set to the frame AV for the frame CvDEPTH == 1. |
569 | C<PL_curpad> is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)). |
a4f1a029 |
570 | |
f3548bdc |
571 | During execution, C<PL_comppad> and C<PL_curpad> refer to the live |
572 | frame of the currently executing sub. |
573 | |
574 | Iterating over the names AV iterates over all possible pad |
a4f1a029 |
575 | items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having |
576 | &PL_sv_undef "names" (see pad_alloc()). |
577 | |
578 | Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names. |
579 | The rest are op targets/GVs/constants which are statically allocated |
580 | or resolved at compile time. These don't have names by which they |
581 | can be looked up from Perl code at run time through eval"" like |
582 | my/our variables can be. Since they can't be looked up by "name" |
583 | but only by their index allocated at compile time (which is usually |
584 | in PL_op->op_targ), wasting a name SV for them doesn't make sense. |
585 | |
586 | The SVs in the names AV have their PV being the name of the variable. |
00a0d662 |
587 | xlow+1..xhigh inclusive in the NV union is a range of cop_seq numbers for |
588 | which the name is valid. For typed lexicals name SV is SVt_PVMG and SvSTASH |
589 | points at the type. For C<our> lexicals, the type is also SVt_PVMG, with the |
44a2ac75 |
590 | SvOURSTASH slot pointing at the stash of the associated global (so that |
00a0d662 |
591 | duplicate C<our> declarations in the same package can be detected). SvUVX is |
592 | sometimes hijacked to store the generation number during compilation. |
a4f1a029 |
593 | |
b5c19bd7 |
594 | If SvFAKE is set on the name SV, then that slot in the frame AV is |
595 | a REFCNT'ed reference to a lexical from "outside". In this case, |
00a0d662 |
596 | the name SV does not use xlow and xhigh to store a cop_seq range, since it is |
597 | in scope throughout. Instead xhigh stores some flags containing info about |
b5c19bd7 |
598 | the real lexical (is it declared in an anon, and is it capable of being |
00a0d662 |
599 | instantiated multiple times?), and for fake ANONs, xlow contains the index |
b5c19bd7 |
600 | within the parent's pad where the lexical's value is stored, to make |
601 | cloning quicker. |
a4f1a029 |
602 | |
a6d05634 |
603 | If the 'name' is '&' the corresponding entry in frame AV |
a4f1a029 |
604 | is a CV representing a possible closure. |
605 | (SvFAKE and name of '&' is not a meaningful combination currently but could |
606 | become so if C<my sub foo {}> is implemented.) |
607 | |
5c3943b6 |
608 | Note that formats are treated as anon subs, and are cloned each time |
609 | write is called (if necessary). |
610 | |
2814eb74 |
611 | The flag SVf_PADSTALE is cleared on lexicals each time the my() is executed, |
612 | and set on scope exit. This allows the 'Variable $x is not available' warning |
613 | to be generated in evals, such as |
614 | |
615 | { my $x = 1; sub f { eval '$x'} } f(); |
616 | |
3134ad69 |
617 | For state vars, SVf_PADSTALE is overloaded to mean 'not yet initialised' |
618 | |
a4f1a029 |
619 | AV * CvPADLIST(CV *cv) |
620 | |
621 | =for hackers |
dd2155a4 |
622 | Found in file pad.c |
623 | |
624 | =item cv_clone |
d8c40edc |
625 | X<cv_clone> |
dd2155a4 |
626 | |
627 | Clone a CV: make a new CV which points to the same code etc, but which |
ad63d80f |
628 | has a newly-created pad built by copying the prototype pad and capturing |
dd2155a4 |
629 | any outer lexicals. |
630 | |
631 | CV* cv_clone(CV* proto) |
632 | |
633 | =for hackers |
634 | Found in file pad.c |
635 | |
636 | =item cv_dump |
d8c40edc |
637 | X<cv_dump> |
dd2155a4 |
638 | |
639 | dump the contents of a CV |
640 | |
e1ec3a88 |
641 | void cv_dump(const CV *cv, const char *title) |
dd2155a4 |
642 | |
643 | =for hackers |
644 | Found in file pad.c |
645 | |
646 | =item do_dump_pad |
d8c40edc |
647 | X<do_dump_pad> |
dd2155a4 |
648 | |
649 | Dump the contents of a padlist |
650 | |
651 | void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full) |
652 | |
653 | =for hackers |
654 | Found in file pad.c |
655 | |
656 | =item intro_my |
d8c40edc |
657 | X<intro_my> |
dd2155a4 |
658 | |
659 | "Introduce" my variables to visible status. |
660 | |
661 | U32 intro_my() |
662 | |
663 | =for hackers |
664 | Found in file pad.c |
665 | |
666 | =item pad_add_anon |
d8c40edc |
667 | X<pad_add_anon> |
dd2155a4 |
668 | |
669 | Add an anon code entry to the current compiling pad |
670 | |
671 | PADOFFSET pad_add_anon(SV* sv, OPCODE op_type) |
672 | |
673 | =for hackers |
674 | Found in file pad.c |
675 | |
676 | =item pad_add_name |
d8c40edc |
677 | X<pad_add_name> |
dd2155a4 |
678 | |
b5c19bd7 |
679 | Create a new name and associated PADMY SV in the current pad; return the |
680 | offset. |
dd2155a4 |
681 | If C<typestash> is valid, the name is for a typed lexical; set the |
682 | name's stash to that value. |
683 | If C<ourstash> is valid, it's an our lexical, set the name's |
44a2ac75 |
684 | SvOURSTASH to that value |
dd2155a4 |
685 | |
dd2155a4 |
686 | If fake, it means we're cloning an existing entry |
687 | |
952306ac |
688 | PADOFFSET pad_add_name(const char *name, HV* typestash, HV* ourstash, bool clone, bool state) |
dd2155a4 |
689 | |
690 | =for hackers |
691 | Found in file pad.c |
692 | |
693 | =item pad_alloc |
d8c40edc |
694 | X<pad_alloc> |
dd2155a4 |
695 | |
696 | Allocate a new my or tmp pad entry. For a my, simply push a null SV onto |
697 | the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards |
324092c6 |
698 | for a slot which has no name and no active value. |
dd2155a4 |
699 | |
700 | PADOFFSET pad_alloc(I32 optype, U32 tmptype) |
701 | |
702 | =for hackers |
703 | Found in file pad.c |
704 | |
705 | =item pad_block_start |
d8c40edc |
706 | X<pad_block_start> |
dd2155a4 |
707 | |
708 | Update the pad compilation state variables on entry to a new block |
709 | |
710 | void pad_block_start(int full) |
711 | |
712 | =for hackers |
713 | Found in file pad.c |
714 | |
715 | =item pad_check_dup |
d8c40edc |
716 | X<pad_check_dup> |
dd2155a4 |
717 | |
718 | Check for duplicate declarations: report any of: |
719 | * a my in the current scope with the same name; |
720 | * an our (anywhere in the pad) with the same name and the same stash |
721 | as C<ourstash> |
722 | C<is_our> indicates that the name to check is an 'our' declaration |
723 | |
e1ec3a88 |
724 | void pad_check_dup(const char* name, bool is_our, const HV* ourstash) |
dd2155a4 |
725 | |
726 | =for hackers |
727 | Found in file pad.c |
728 | |
729 | =item pad_findlex |
d8c40edc |
730 | X<pad_findlex> |
dd2155a4 |
731 | |
732 | Find a named lexical anywhere in a chain of nested pads. Add fake entries |
b5c19bd7 |
733 | in the inner pads if it's found in an outer one. |
734 | |
735 | Returns the offset in the bottom pad of the lex or the fake lex. |
736 | cv is the CV in which to start the search, and seq is the current cop_seq |
737 | to match against. If warn is true, print appropriate warnings. The out_* |
738 | vars return values, and so are pointers to where the returned values |
739 | should be stored. out_capture, if non-null, requests that the innermost |
740 | instance of the lexical is captured; out_name_sv is set to the innermost |
741 | matched namesv or fake namesv; out_flags returns the flags normally |
742 | associated with the IVX field of a fake namesv. |
743 | |
744 | Note that pad_findlex() is recursive; it recurses up the chain of CVs, |
745 | then comes back down, adding fake entries as it goes. It has to be this way |
00a0d662 |
746 | because fake namesvs in anon protoypes have to store in xlow the index into |
b5c19bd7 |
747 | the parent pad. |
748 | |
e1ec3a88 |
749 | PADOFFSET pad_findlex(const char *name, const CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags) |
dd2155a4 |
750 | |
751 | =for hackers |
752 | Found in file pad.c |
753 | |
754 | =item pad_findmy |
d8c40edc |
755 | X<pad_findmy> |
dd2155a4 |
756 | |
ad63d80f |
757 | Given a lexical name, try to find its offset, first in the current pad, |
dd2155a4 |
758 | or failing that, in the pads of any lexically enclosing subs (including |
ad63d80f |
759 | the complications introduced by eval). If the name is found in an outer pad, |
760 | then a fake entry is added to the current pad. |
dd2155a4 |
761 | Returns the offset in the current pad, or NOT_IN_PAD on failure. |
762 | |
e1ec3a88 |
763 | PADOFFSET pad_findmy(const char* name) |
dd2155a4 |
764 | |
765 | =for hackers |
766 | Found in file pad.c |
767 | |
768 | =item pad_fixup_inner_anons |
d8c40edc |
769 | X<pad_fixup_inner_anons> |
dd2155a4 |
770 | |
771 | For any anon CVs in the pad, change CvOUTSIDE of that CV from |
7dafbf52 |
772 | old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be |
773 | moved to a pre-existing CV struct. |
dd2155a4 |
774 | |
775 | void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv) |
776 | |
777 | =for hackers |
778 | Found in file pad.c |
779 | |
780 | =item pad_free |
d8c40edc |
781 | X<pad_free> |
dd2155a4 |
782 | |
d7f8936a |
783 | Free the SV at offset po in the current pad. |
dd2155a4 |
784 | |
785 | void pad_free(PADOFFSET po) |
786 | |
787 | =for hackers |
788 | Found in file pad.c |
789 | |
790 | =item pad_leavemy |
d8c40edc |
791 | X<pad_leavemy> |
dd2155a4 |
792 | |
793 | Cleanup at end of scope during compilation: set the max seq number for |
794 | lexicals in this scope and warn of any lexicals that never got introduced. |
795 | |
796 | void pad_leavemy() |
797 | |
798 | =for hackers |
799 | Found in file pad.c |
800 | |
801 | =item pad_new |
d8c40edc |
802 | X<pad_new> |
dd2155a4 |
803 | |
ad63d80f |
804 | Create a new compiling padlist, saving and updating the various global |
dd2155a4 |
805 | vars at the same time as creating the pad itself. The following flags |
806 | can be OR'ed together: |
807 | |
808 | padnew_CLONE this pad is for a cloned CV |
809 | padnew_SAVE save old globals |
810 | padnew_SAVESUB also save extra stuff for start of sub |
811 | |
c7c737cb |
812 | PADLIST* pad_new(int flags) |
dd2155a4 |
813 | |
814 | =for hackers |
815 | Found in file pad.c |
816 | |
817 | =item pad_push |
d8c40edc |
818 | X<pad_push> |
dd2155a4 |
819 | |
820 | Push a new pad frame onto the padlist, unless there's already a pad at |
26019298 |
821 | this depth, in which case don't bother creating a new one. Then give |
822 | the new pad an @_ in slot zero. |
dd2155a4 |
823 | |
26019298 |
824 | void pad_push(PADLIST *padlist, int depth) |
dd2155a4 |
825 | |
826 | =for hackers |
827 | Found in file pad.c |
828 | |
829 | =item pad_reset |
d8c40edc |
830 | X<pad_reset> |
dd2155a4 |
831 | |
832 | Mark all the current temporaries for reuse |
833 | |
834 | void pad_reset() |
835 | |
836 | =for hackers |
837 | Found in file pad.c |
838 | |
839 | =item pad_setsv |
d8c40edc |
840 | X<pad_setsv> |
dd2155a4 |
841 | |
842 | Set the entry at offset po in the current pad to sv. |
843 | Use the macro PAD_SETSV() rather than calling this function directly. |
844 | |
845 | void pad_setsv(PADOFFSET po, SV* sv) |
846 | |
847 | =for hackers |
848 | Found in file pad.c |
849 | |
850 | =item pad_swipe |
d8c40edc |
851 | X<pad_swipe> |
dd2155a4 |
852 | |
853 | Abandon the tmp in the current pad at offset po and replace with a |
854 | new one. |
855 | |
856 | void pad_swipe(PADOFFSET po, bool refadjust) |
857 | |
858 | =for hackers |
859 | Found in file pad.c |
860 | |
861 | =item pad_tidy |
d8c40edc |
862 | X<pad_tidy> |
dd2155a4 |
863 | |
864 | Tidy up a pad after we've finished compiling it: |
865 | * remove most stuff from the pads of anonsub prototypes; |
866 | * give it a @_; |
867 | * mark tmps as such. |
868 | |
869 | void pad_tidy(padtidy_type type) |
870 | |
871 | =for hackers |
872 | Found in file pad.c |
873 | |
874 | =item pad_undef |
d8c40edc |
875 | X<pad_undef> |
dd2155a4 |
876 | |
877 | Free the padlist associated with a CV. |
878 | If parts of it happen to be current, we null the relevant |
879 | PL_*pad* global vars so that we don't have any dangling references left. |
880 | We also repoint the CvOUTSIDE of any about-to-be-orphaned |
a3985cdc |
881 | inner subs to the outer of this cv. |
dd2155a4 |
882 | |
7dafbf52 |
883 | (This function should really be called pad_free, but the name was already |
884 | taken) |
885 | |
a3985cdc |
886 | void pad_undef(CV* cv) |
dd2155a4 |
887 | |
888 | =for hackers |
889 | Found in file pad.c |
a4f1a029 |
890 | |
891 | |
892 | =back |
893 | |
907b3e23 |
894 | =head1 Per-Interpreter Variables |
895 | |
896 | =over 8 |
897 | |
898 | =item PL_DBsingle |
899 | X<PL_DBsingle> |
900 | |
901 | When Perl is run in debugging mode, with the B<-d> switch, this SV is a |
902 | boolean which indicates whether subs are being single-stepped. |
903 | Single-stepping is automatically turned on after every step. This is the C |
904 | variable which corresponds to Perl's $DB::single variable. See |
905 | C<PL_DBsub>. |
906 | |
907 | SV * PL_DBsingle |
908 | |
909 | =for hackers |
910 | Found in file intrpvar.h |
911 | |
912 | =item PL_DBsub |
913 | X<PL_DBsub> |
914 | |
915 | When Perl is run in debugging mode, with the B<-d> switch, this GV contains |
916 | the SV which holds the name of the sub being debugged. This is the C |
917 | variable which corresponds to Perl's $DB::sub variable. See |
918 | C<PL_DBsingle>. |
919 | |
920 | GV * PL_DBsub |
921 | |
922 | =for hackers |
923 | Found in file intrpvar.h |
924 | |
925 | =item PL_DBtrace |
926 | X<PL_DBtrace> |
927 | |
928 | Trace variable used when Perl is run in debugging mode, with the B<-d> |
929 | switch. This is the C variable which corresponds to Perl's $DB::trace |
930 | variable. See C<PL_DBsingle>. |
931 | |
932 | SV * PL_DBtrace |
933 | |
934 | =for hackers |
935 | Found in file intrpvar.h |
936 | |
937 | =item PL_dowarn |
938 | X<PL_dowarn> |
939 | |
940 | The C variable which corresponds to Perl's $^W warning variable. |
941 | |
942 | bool PL_dowarn |
943 | |
944 | =for hackers |
945 | Found in file intrpvar.h |
946 | |
947 | =item PL_last_in_gv |
948 | X<PL_last_in_gv> |
949 | |
950 | The GV which was last used for a filehandle input operation. (C<< <FH> >>) |
951 | |
952 | GV* PL_last_in_gv |
953 | |
954 | =for hackers |
955 | Found in file intrpvar.h |
956 | |
6a57758b |
957 | =item PL_ofsgv |
958 | X<PL_ofsgv> |
907b3e23 |
959 | |
6a57758b |
960 | The glob containing the output field separator - C<*,> in Perl space. |
907b3e23 |
961 | |
6a57758b |
962 | GV* PL_ofsgv |
907b3e23 |
963 | |
964 | =for hackers |
965 | Found in file intrpvar.h |
966 | |
967 | =item PL_rs |
968 | X<PL_rs> |
969 | |
970 | The input record separator - C<$/> in Perl space. |
971 | |
972 | SV* PL_rs |
973 | |
974 | =for hackers |
975 | Found in file intrpvar.h |
976 | |
977 | |
978 | =back |
979 | |
a4f1a029 |
980 | =head1 Stack Manipulation Macros |
981 | |
982 | =over 8 |
983 | |
984 | =item djSP |
d8c40edc |
985 | X<djSP> |
a4f1a029 |
986 | |
987 | Declare Just C<SP>. This is actually identical to C<dSP>, and declares |
988 | a local copy of perl's stack pointer, available via the C<SP> macro. |
989 | See C<SP>. (Available for backward source code compatibility with the |
990 | old (Perl 5.005) thread model.) |
991 | |
992 | djSP; |
993 | |
994 | =for hackers |
995 | Found in file pp.h |
996 | |
997 | =item LVRET |
d8c40edc |
998 | X<LVRET> |
a4f1a029 |
999 | |
1000 | True if this op will be the return value of an lvalue subroutine |
1001 | |
1002 | =for hackers |
1003 | Found in file pp.h |
1004 | |
1005 | |
1006 | =back |
1007 | |
1008 | =head1 SV Manipulation Functions |
1009 | |
1010 | =over 8 |
1011 | |
645c22ef |
1012 | =item sv_add_arena |
d8c40edc |
1013 | X<sv_add_arena> |
645c22ef |
1014 | |
1015 | Given a chunk of memory, link it to the head of the list of arenas, |
1016 | and split it into a list of free SVs. |
1017 | |
de37a194 |
1018 | void sv_add_arena(char *const ptr, const U32 size, const U32 flags) |
645c22ef |
1019 | |
1020 | =for hackers |
1021 | Found in file sv.c |
1022 | |
1023 | =item sv_clean_all |
d8c40edc |
1024 | X<sv_clean_all> |
645c22ef |
1025 | |
1026 | Decrement the refcnt of each remaining SV, possibly triggering a |
1027 | cleanup. This function may have to be called multiple times to free |
8fb26106 |
1028 | SVs which are in complex self-referential hierarchies. |
645c22ef |
1029 | |
1030 | I32 sv_clean_all() |
1031 | |
1032 | =for hackers |
1033 | Found in file sv.c |
1034 | |
1035 | =item sv_clean_objs |
d8c40edc |
1036 | X<sv_clean_objs> |
645c22ef |
1037 | |
1038 | Attempt to destroy all objects not yet freed |
1039 | |
1040 | void sv_clean_objs() |
1041 | |
1042 | =for hackers |
1043 | Found in file sv.c |
1044 | |
1045 | =item sv_free_arenas |
d8c40edc |
1046 | X<sv_free_arenas> |
645c22ef |
1047 | |
1048 | Deallocate the memory used by all arenas. Note that all the individual SV |
1049 | heads and bodies within the arenas must already have been freed. |
1050 | |
1051 | void sv_free_arenas() |
1052 | |
1053 | =for hackers |
1054 | Found in file sv.c |
1055 | |
a4f1a029 |
1056 | |
954c1994 |
1057 | =back |
1058 | |
800401ee |
1059 | =head1 SV-Body Allocation |
1060 | |
1061 | =over 8 |
1062 | |
1063 | =item sv_2num |
1064 | X<sv_2num> |
1065 | |
1066 | Return an SV with the numeric value of the source SV, doing any necessary |
a196a5fa |
1067 | reference or overload conversion. You must use the C<SvNUM(sv)> macro to |
1068 | access this function. |
800401ee |
1069 | |
5de3775c |
1070 | SV* sv_2num(SV *const sv) |
800401ee |
1071 | |
1072 | =for hackers |
1073 | Found in file sv.c |
1074 | |
1075 | |
1076 | =back |
1077 | |
979f2922 |
1078 | =head1 Unicode Support |
1079 | |
1080 | =over 8 |
1081 | |
1082 | =item find_uninit_var |
1083 | X<find_uninit_var> |
1084 | |
1085 | Find the name of the undefined variable (if any) that caused the operator o |
1086 | to issue a "Use of uninitialized value" warning. |
1087 | If match is true, only return a name if it's value matches uninit_sv. |
1088 | So roughly speaking, if a unary operator (such as OP_COS) generates a |
1089 | warning, then following the direct child of the op may yield an |
1090 | OP_PADSV or OP_GV that gives the name of the undefined variable. On the |
1091 | other hand, with OP_ADD there are two branches to follow, so we only print |
1092 | the variable name if we get an exact match. |
1093 | |
1094 | The name is returned as a mortal SV. |
1095 | |
1096 | Assumes that PL_op is the op that originally triggered the error, and that |
1097 | PL_comppad/PL_curpad points to the currently executing pad. |
1098 | |
87cea99e |
1099 | SV* find_uninit_var(const OP *const obase, const SV *const uninit_sv, bool top) |
979f2922 |
1100 | |
1101 | =for hackers |
1102 | Found in file sv.c |
1103 | |
1104 | =item report_uninit |
1105 | X<report_uninit> |
1106 | |
1107 | Print appropriate "Use of uninitialized variable" warning |
1108 | |
64f0785e |
1109 | void report_uninit(const SV *uninit_sv) |
979f2922 |
1110 | |
1111 | =for hackers |
1112 | Found in file sv.c |
1113 | |
1114 | |
1115 | =back |
1116 | |
954c1994 |
1117 | =head1 AUTHORS |
1118 | |
1c846c1f |
1119 | The autodocumentation system was originally added to the Perl core by |
1120 | Benjamin Stuhl. Documentation is by whoever was kind enough to |
954c1994 |
1121 | document their functions. |
1122 | |
1123 | =head1 SEE ALSO |
1124 | |
1125 | perlguts(1), perlapi(1) |
1126 | |
3f98fbb3 |
1127 | =cut |
1128 | |
1129 | ex: set ro: |