Commit | Line | Data |
954c1994 |
1 | =head1 NAME |
2 | |
1c846c1f |
3 | perlintern - autogenerated documentation of purely B<internal> |
954c1994 |
4 | Perl functions |
5 | |
6 | =head1 DESCRIPTION |
7 | |
1c846c1f |
8 | This file is the autogenerated documentation of functions in the |
4375e838 |
9 | Perl interpreter that are documented using Perl's internal documentation |
1c846c1f |
10 | format but are not marked as part of the Perl API. In other words, |
954c1994 |
11 | B<they are not for use in extensions>! |
12 | |
a8586c98 |
13 | |
dd2155a4 |
14 | =head1 Functions in file pad.h |
15 | |
16 | |
17 | =over 8 |
18 | |
19 | =item CX_CURPAD_SAVE |
20 | |
21 | Save the current pad in the given context block structure. |
22 | |
23 | void CX_CURPAD_SAVE(struct context) |
24 | |
25 | =for hackers |
26 | Found in file pad.h |
27 | |
28 | =item CX_CURPAD_SV |
29 | |
30 | Access the SV at offset po in the saved current pad in the given |
31 | context block structure (can be used as an lvalue). |
32 | |
33 | PAD * CX_CURPAD_SV(struct context, PADOFFSET po) |
34 | |
35 | =for hackers |
36 | Found in file pad.h |
37 | |
38 | =item PAD_BASE_SV |
39 | |
40 | Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist |
41 | |
42 | SV * PAD_BASE_SV (PADLIST padlist, PADOFFSET po) |
43 | |
44 | =for hackers |
45 | Found in file pad.h |
46 | |
47 | =item PAD_CLONE_VARS |
48 | |
49 | |CLONE_PARAMS* param |
50 | Clone the state variables associated with running and compiling pads. |
51 | |
52 | void PAD_CLONE_VARS(PerlInterpreter *proto_perl \) |
53 | |
54 | =for hackers |
55 | Found in file pad.h |
56 | |
57 | =item PAD_COMPNAME_FLAGS |
58 | |
59 | Return the flags for the current compiling pad name |
60 | at offset C<po>. Assumes a valid slot entry. |
61 | |
62 | U32 PAD_COMPNAME_FLAGS(PADOFFSET po) |
63 | |
64 | =for hackers |
65 | Found in file pad.h |
66 | |
67 | =item PAD_COMPNAME_GEN |
68 | |
69 | The generation number of the name at offset C<po> in the current |
70 | compiling pad (lvalue). Note that C<SvCUR> is hijacked for this purpose. |
71 | |
72 | STRLEN PAD_COMPNAME_GEN(PADOFFSET po) |
73 | |
74 | =for hackers |
75 | Found in file pad.h |
76 | |
77 | =item PAD_COMPNAME_OURSTASH |
78 | |
79 | Return the stash associated with an C<our> variable. |
80 | Assumes the slot entry is a valid C<our> lexical. |
81 | |
82 | HV * PAD_COMPNAME_OURSTASH(PADOFFSET po) |
83 | |
84 | =for hackers |
85 | Found in file pad.h |
86 | |
87 | =item PAD_COMPNAME_PV |
88 | |
89 | Return the name of the current compiling pad name |
90 | at offset C<po>. Assumes a valid slot entry. |
91 | |
92 | char * PAD_COMPNAME_PV(PADOFFSET po) |
93 | |
94 | =for hackers |
95 | Found in file pad.h |
96 | |
97 | =item PAD_COMPNAME_TYPE |
98 | |
99 | Return the type (stash) of the current compiling pad name at offset |
100 | C<po>. Must be a valid name. Returns null if not typed. |
101 | |
102 | HV * PAD_COMPNAME_TYPE(PADOFFSET po) |
103 | |
104 | =for hackers |
105 | Found in file pad.h |
106 | |
107 | =item PAD_DUP |
108 | |
109 | Clone a padlist. |
110 | |
111 | void PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param) |
112 | |
113 | =for hackers |
114 | Found in file pad.h |
115 | |
116 | =item PAD_SAVE_SETNULLPAD |
117 | |
118 | Save the current pad then set it to null. |
119 | |
120 | void PAD_SAVE_SETNULLPAD() |
121 | |
122 | =for hackers |
123 | Found in file pad.h |
124 | |
125 | =item PAD_SETSV |
126 | |
127 | Set the slot at offset C<po> in the current pad to C<sv> |
128 | |
129 | SV * PAD_SETSV (PADOFFSET po, SV* sv) |
130 | |
131 | =for hackers |
132 | Found in file pad.h |
133 | |
134 | =item PAD_SET_CUR |
135 | |
136 | Set the current pad to be pad C<n> in the padlist, saving |
137 | the previous current pad. |
138 | |
139 | void PAD_SET_CUR (PADLIST padlist, I32 n) |
140 | |
141 | =for hackers |
142 | Found in file pad.h |
143 | |
144 | =item PAD_SV |
145 | |
146 | Get the value at offset C<po> in the current pad |
147 | |
148 | void PAD_SV (PADOFFSET po) |
149 | |
150 | =for hackers |
151 | Found in file pad.h |
152 | |
153 | =item PAD_SVl |
154 | |
155 | Lightweight and lvalue version of C<PAD_SV>. |
156 | Get or set the value at offset C<po> in the current pad. |
157 | Unlike C<PAD_SV>, does not print diagnostics with -DX. |
158 | For internal use only. |
159 | |
160 | SV * PAD_SVl (PADOFFSET po) |
161 | |
162 | =for hackers |
163 | Found in file pad.h |
164 | |
165 | =item PAD_UPDATE_CURPAD |
166 | |
167 | Set PL_curpad from the value of PL_comppad. |
168 | |
169 | void PAD_UPDATE_CURPAD() |
170 | |
171 | =for hackers |
172 | Found in file pad.h |
173 | |
174 | =item SAVECLEARSV |
175 | |
176 | Clear the pointed to pad value on scope exit. (ie the runtime action of 'my') |
177 | |
178 | void SAVECLEARSV (SV **svp) |
179 | |
180 | =for hackers |
181 | Found in file pad.h |
182 | |
183 | =item SAVECOMPPAD |
184 | |
185 | save PL_comppad and PL_curpad |
186 | |
187 | void SAVECOMPPAD() |
188 | |
189 | =for hackers |
190 | Found in file pad.h |
191 | |
192 | =item SAVEFREEOP |
193 | |
194 | Free the op on scope exit. At the same time, reset PL_curpad |
195 | |
196 | |
197 | |
198 | |
199 | void SAVEFREEOP (OP *o) |
200 | |
201 | =for hackers |
202 | Found in file pad.h |
203 | |
204 | =item SAVEPADSV |
205 | |
206 | Save a pad slot (used to restore after an iteration) |
207 | |
208 | void SAVEPADSV (PADOFFSET po) |
209 | |
210 | =for hackers |
211 | Found in file pad.h |
212 | |
213 | |
214 | =back |
215 | |
a4f1a029 |
216 | =head1 Global Variables |
78f9721b |
217 | |
a4f1a029 |
218 | =over 8 |
78f9721b |
219 | |
2eb25c99 |
220 | =item PL_DBsingle |
221 | |
222 | When Perl is run in debugging mode, with the B<-d> switch, this SV is a |
223 | boolean which indicates whether subs are being single-stepped. |
224 | Single-stepping is automatically turned on after every step. This is the C |
225 | variable which corresponds to Perl's $DB::single variable. See |
226 | C<PL_DBsub>. |
227 | |
228 | SV * PL_DBsingle |
229 | |
230 | =for hackers |
231 | Found in file intrpvar.h |
232 | |
233 | =item PL_DBsub |
234 | |
235 | When Perl is run in debugging mode, with the B<-d> switch, this GV contains |
236 | the SV which holds the name of the sub being debugged. This is the C |
237 | variable which corresponds to Perl's $DB::sub variable. See |
238 | C<PL_DBsingle>. |
239 | |
240 | GV * PL_DBsub |
241 | |
242 | =for hackers |
243 | Found in file intrpvar.h |
244 | |
245 | =item PL_DBtrace |
246 | |
247 | Trace variable used when Perl is run in debugging mode, with the B<-d> |
248 | switch. This is the C variable which corresponds to Perl's $DB::trace |
249 | variable. See C<PL_DBsingle>. |
250 | |
251 | SV * PL_DBtrace |
252 | |
253 | =for hackers |
254 | Found in file intrpvar.h |
255 | |
256 | =item PL_dowarn |
257 | |
258 | The C variable which corresponds to Perl's $^W warning variable. |
259 | |
260 | bool PL_dowarn |
261 | |
262 | =for hackers |
263 | Found in file intrpvar.h |
264 | |
265 | =item PL_last_in_gv |
266 | |
267 | The GV which was last used for a filehandle input operation. (C<< <FH> >>) |
268 | |
269 | GV* PL_last_in_gv |
270 | |
271 | =for hackers |
272 | Found in file thrdvar.h |
273 | |
274 | =item PL_ofs_sv |
275 | |
276 | The output field separator - C<$,> in Perl space. |
277 | |
278 | SV* PL_ofs_sv |
279 | |
280 | =for hackers |
281 | Found in file thrdvar.h |
282 | |
283 | =item PL_rs |
284 | |
285 | The input record separator - C<$/> in Perl space. |
286 | |
287 | SV* PL_rs |
288 | |
289 | =for hackers |
290 | Found in file thrdvar.h |
291 | |
645c22ef |
292 | |
a4f1a029 |
293 | =back |
645c22ef |
294 | |
a4f1a029 |
295 | =head1 GV Functions |
296 | |
297 | =over 8 |
298 | |
299 | =item is_gv_magical |
300 | |
301 | Returns C<TRUE> if given the name of a magical GV. |
302 | |
303 | Currently only useful internally when determining if a GV should be |
304 | created even in rvalue contexts. |
305 | |
306 | C<flags> is not used at present but available for future extension to |
307 | allow selecting particular classes of magical variable. |
308 | |
309 | bool is_gv_magical(char *name, STRLEN len, U32 flags) |
645c22ef |
310 | |
311 | =for hackers |
a4f1a029 |
312 | Found in file gv.c |
313 | |
314 | |
315 | =back |
316 | |
317 | =head1 IO Functions |
318 | |
319 | =over 8 |
645c22ef |
320 | |
a8586c98 |
321 | =item start_glob |
322 | |
323 | Function called by C<do_readline> to spawn a glob (or do the glob inside |
324 | perl on VMS). This code used to be inline, but now perl uses C<File::Glob> |
bd16a5f0 |
325 | this glob starter is only used by miniperl during the build process. |
a8586c98 |
326 | Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up. |
327 | |
328 | PerlIO* start_glob(SV* pattern, IO *io) |
329 | |
330 | =for hackers |
331 | Found in file doio.c |
332 | |
a4f1a029 |
333 | |
334 | =back |
335 | |
336 | =head1 Pad Data Structures |
337 | |
338 | =over 8 |
339 | |
340 | =item CvPADLIST |
341 | |
342 | CV's can have CvPADLIST(cv) set to point to an AV. |
343 | |
344 | For these purposes "forms" are a kind-of CV, eval""s are too (except they're |
345 | not callable at will and are always thrown away after the eval"" is done |
346 | executing). |
347 | |
348 | XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad, |
349 | but that is really the callers pad (a slot of which is allocated by |
350 | every entersub). |
351 | |
352 | The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items |
353 | is managed "manual" (mostly in op.c) rather than normal av.c rules. |
354 | The items in the AV are not SVs as for a normal AV, but other AVs: |
355 | |
356 | 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather |
357 | the "static type information" for lexicals. |
358 | |
359 | The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that |
360 | depth of recursion into the CV. |
361 | The 0'th slot of a frame AV is an AV which is @_. |
362 | other entries are storage for variables and op targets. |
363 | |
364 | During compilation: |
365 | C<PL_comppad_name> is set the the the names AV. |
366 | C<PL_comppad> is set the the frame AV for the frame CvDEPTH == 1. |
367 | C<PL_curpad> is set the body of the frame AV (i.e. AvARRAY(PL_comppad)). |
368 | |
369 | Itterating over the names AV itterates over all possible pad |
370 | items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having |
371 | &PL_sv_undef "names" (see pad_alloc()). |
372 | |
373 | Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names. |
374 | The rest are op targets/GVs/constants which are statically allocated |
375 | or resolved at compile time. These don't have names by which they |
376 | can be looked up from Perl code at run time through eval"" like |
377 | my/our variables can be. Since they can't be looked up by "name" |
378 | but only by their index allocated at compile time (which is usually |
379 | in PL_op->op_targ), wasting a name SV for them doesn't make sense. |
380 | |
381 | The SVs in the names AV have their PV being the name of the variable. |
dd2155a4 |
382 | NV+1..IV inclusive is a range of cop_seq numbers for which the name is |
383 | valid. For typed lexicals name SV is SVt_PVMG and SvSTASH points at the |
384 | type. For C<our> lexicals, the type is SVt_PVGV, and GvSTASH points at the |
385 | stash of the associated global (so that duplicate C<our> delarations in the |
386 | same package can be detected). SvCUR is sometimes hijacked to |
387 | store the generation number during compilation. |
a4f1a029 |
388 | |
389 | If SvFAKE is set on the name SV then slot in the frame AVs are |
390 | a REFCNT'ed references to a lexical from "outside". |
391 | |
392 | If the 'name' is '&' the the corresponding entry in frame AV |
393 | is a CV representing a possible closure. |
394 | (SvFAKE and name of '&' is not a meaningful combination currently but could |
395 | become so if C<my sub foo {}> is implemented.) |
396 | |
397 | AV * CvPADLIST(CV *cv) |
398 | |
399 | =for hackers |
dd2155a4 |
400 | Found in file pad.c |
401 | |
402 | =item cv_clone |
403 | |
404 | Clone a CV: make a new CV which points to the same code etc, but which |
405 | has a newly-created pad done by copying the prototype pad and capturing |
406 | any outer lexicals. |
407 | |
408 | CV* cv_clone(CV* proto) |
409 | |
410 | =for hackers |
411 | Found in file pad.c |
412 | |
413 | =item cv_dump |
414 | |
415 | dump the contents of a CV |
416 | |
417 | void cv_dump(CV *cv, char *title) |
418 | |
419 | =for hackers |
420 | Found in file pad.c |
421 | |
422 | =item do_dump_pad |
423 | |
424 | Dump the contents of a padlist |
425 | |
426 | void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full) |
427 | |
428 | =for hackers |
429 | Found in file pad.c |
430 | |
431 | =item intro_my |
432 | |
433 | "Introduce" my variables to visible status. |
434 | |
435 | U32 intro_my() |
436 | |
437 | =for hackers |
438 | Found in file pad.c |
439 | |
440 | =item pad_add_anon |
441 | |
442 | Add an anon code entry to the current compiling pad |
443 | |
444 | PADOFFSET pad_add_anon(SV* sv, OPCODE op_type) |
445 | |
446 | =for hackers |
447 | Found in file pad.c |
448 | |
449 | =item pad_add_name |
450 | |
451 | Create a new name in the current pad at the specified offset. |
452 | If C<typestash> is valid, the name is for a typed lexical; set the |
453 | name's stash to that value. |
454 | If C<ourstash> is valid, it's an our lexical, set the name's |
455 | GvSTASH to that value |
456 | |
457 | Also, if the name is @.. or %.., create a new array or hash for that slot |
458 | |
459 | If fake, it means we're cloning an existing entry |
460 | |
461 | PADOFFSET pad_add_name(char *name, HV* typestash, HV* ourstash, bool clone) |
462 | |
463 | =for hackers |
464 | Found in file pad.c |
465 | |
466 | =item pad_alloc |
467 | |
468 | Allocate a new my or tmp pad entry. For a my, simply push a null SV onto |
469 | the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards |
470 | for a slot which has no name and and no active value. |
471 | |
472 | PADOFFSET pad_alloc(I32 optype, U32 tmptype) |
473 | |
474 | =for hackers |
475 | Found in file pad.c |
476 | |
477 | =item pad_block_start |
478 | |
479 | Update the pad compilation state variables on entry to a new block |
480 | |
481 | void pad_block_start(int full) |
482 | |
483 | =for hackers |
484 | Found in file pad.c |
485 | |
486 | =item pad_check_dup |
487 | |
488 | Check for duplicate declarations: report any of: |
489 | * a my in the current scope with the same name; |
490 | * an our (anywhere in the pad) with the same name and the same stash |
491 | as C<ourstash> |
492 | C<is_our> indicates that the name to check is an 'our' declaration |
493 | |
494 | |
495 | void pad_check_dup(char* name, bool is_our, HV* ourstash) |
496 | |
497 | =for hackers |
498 | Found in file pad.c |
499 | |
500 | =item pad_findlex |
501 | |
502 | Find a named lexical anywhere in a chain of nested pads. Add fake entries |
503 | in the inner pads if its found in an outer one. |
504 | |
505 | If flags == FINDLEX_NOSEARCH we don't bother searching outer contexts. |
506 | |
507 | PADOFFSET pad_findlex(char* name, PADOFFSET newoff, U32 seq, CV* startcv, I32 cx_ix, I32 saweval, U32 flags) |
508 | |
509 | =for hackers |
510 | Found in file pad.c |
511 | |
512 | =item pad_findmy |
513 | |
514 | Given a lexical name, try to find it's offset, first in the current pad, |
515 | or failing that, in the pads of any lexically enclosing subs (including |
516 | the complications introduced by eval). If the name is found in an outer pad, then a fake entry is added to the current pad. |
517 | Returns the offset in the current pad, or NOT_IN_PAD on failure. |
518 | |
519 | PADOFFSET pad_findmy(char* name) |
520 | |
521 | =for hackers |
522 | Found in file pad.c |
523 | |
524 | =item pad_fixup_inner_anons |
525 | |
526 | For any anon CVs in the pad, change CvOUTSIDE of that CV from |
527 | old_cv to new_cv if necessary. |
528 | |
529 | void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv) |
530 | |
531 | =for hackers |
532 | Found in file pad.c |
533 | |
534 | =item pad_free |
535 | |
536 | Free the SV at offet po in the current pad. |
537 | |
538 | void pad_free(PADOFFSET po) |
539 | |
540 | =for hackers |
541 | Found in file pad.c |
542 | |
543 | =item pad_leavemy |
544 | |
545 | Cleanup at end of scope during compilation: set the max seq number for |
546 | lexicals in this scope and warn of any lexicals that never got introduced. |
547 | |
548 | void pad_leavemy() |
549 | |
550 | =for hackers |
551 | Found in file pad.c |
552 | |
553 | =item pad_new |
554 | |
555 | Create a new comnpiling padlist, saving and updating the various global |
556 | vars at the same time as creating the pad itself. The following flags |
557 | can be OR'ed together: |
558 | |
559 | padnew_CLONE this pad is for a cloned CV |
560 | padnew_SAVE save old globals |
561 | padnew_SAVESUB also save extra stuff for start of sub |
562 | |
563 | PADLIST* pad_new(padnew_flags flags) |
564 | |
565 | =for hackers |
566 | Found in file pad.c |
567 | |
568 | =item pad_push |
569 | |
570 | Push a new pad frame onto the padlist, unless there's already a pad at |
571 | this depth, in which case don't bother creating a new one. |
572 | If has_args is true, give the new pad an @_ in slot zero. |
573 | |
574 | void pad_push(PADLIST *padlist, int depth, int has_args) |
575 | |
576 | =for hackers |
577 | Found in file pad.c |
578 | |
579 | =item pad_reset |
580 | |
581 | Mark all the current temporaries for reuse |
582 | |
583 | void pad_reset() |
584 | |
585 | =for hackers |
586 | Found in file pad.c |
587 | |
588 | =item pad_setsv |
589 | |
590 | Set the entry at offset po in the current pad to sv. |
591 | Use the macro PAD_SETSV() rather than calling this function directly. |
592 | |
593 | void pad_setsv(PADOFFSET po, SV* sv) |
594 | |
595 | =for hackers |
596 | Found in file pad.c |
597 | |
598 | =item pad_swipe |
599 | |
600 | Abandon the tmp in the current pad at offset po and replace with a |
601 | new one. |
602 | |
603 | void pad_swipe(PADOFFSET po, bool refadjust) |
604 | |
605 | =for hackers |
606 | Found in file pad.c |
607 | |
608 | =item pad_tidy |
609 | |
610 | Tidy up a pad after we've finished compiling it: |
611 | * remove most stuff from the pads of anonsub prototypes; |
612 | * give it a @_; |
613 | * mark tmps as such. |
614 | |
615 | void pad_tidy(padtidy_type type) |
616 | |
617 | =for hackers |
618 | Found in file pad.c |
619 | |
620 | =item pad_undef |
621 | |
622 | Free the padlist associated with a CV. |
623 | If parts of it happen to be current, we null the relevant |
624 | PL_*pad* global vars so that we don't have any dangling references left. |
625 | We also repoint the CvOUTSIDE of any about-to-be-orphaned |
626 | inner subs to outercv. |
627 | |
628 | void pad_undef(CV* cv, CV* outercv) |
629 | |
630 | =for hackers |
631 | Found in file pad.c |
a4f1a029 |
632 | |
633 | |
634 | =back |
635 | |
636 | =head1 Stack Manipulation Macros |
637 | |
638 | =over 8 |
639 | |
640 | =item djSP |
641 | |
642 | Declare Just C<SP>. This is actually identical to C<dSP>, and declares |
643 | a local copy of perl's stack pointer, available via the C<SP> macro. |
644 | See C<SP>. (Available for backward source code compatibility with the |
645 | old (Perl 5.005) thread model.) |
646 | |
647 | djSP; |
648 | |
649 | =for hackers |
650 | Found in file pp.h |
651 | |
652 | =item LVRET |
653 | |
654 | True if this op will be the return value of an lvalue subroutine |
655 | |
656 | =for hackers |
657 | Found in file pp.h |
658 | |
659 | |
660 | =back |
661 | |
662 | =head1 SV Manipulation Functions |
663 | |
664 | =over 8 |
665 | |
666 | =item report_uninit |
667 | |
668 | Print appropriate "Use of uninitialized variable" warning |
669 | |
670 | void report_uninit() |
671 | |
672 | =for hackers |
673 | Found in file sv.c |
674 | |
645c22ef |
675 | =item sv_add_arena |
676 | |
677 | Given a chunk of memory, link it to the head of the list of arenas, |
678 | and split it into a list of free SVs. |
679 | |
680 | void sv_add_arena(char* ptr, U32 size, U32 flags) |
681 | |
682 | =for hackers |
683 | Found in file sv.c |
684 | |
685 | =item sv_clean_all |
686 | |
687 | Decrement the refcnt of each remaining SV, possibly triggering a |
688 | cleanup. This function may have to be called multiple times to free |
8fb26106 |
689 | SVs which are in complex self-referential hierarchies. |
645c22ef |
690 | |
691 | I32 sv_clean_all() |
692 | |
693 | =for hackers |
694 | Found in file sv.c |
695 | |
696 | =item sv_clean_objs |
697 | |
698 | Attempt to destroy all objects not yet freed |
699 | |
700 | void sv_clean_objs() |
701 | |
702 | =for hackers |
703 | Found in file sv.c |
704 | |
705 | =item sv_free_arenas |
706 | |
707 | Deallocate the memory used by all arenas. Note that all the individual SV |
708 | heads and bodies within the arenas must already have been freed. |
709 | |
710 | void sv_free_arenas() |
711 | |
712 | =for hackers |
713 | Found in file sv.c |
714 | |
a4f1a029 |
715 | |
954c1994 |
716 | =back |
717 | |
718 | =head1 AUTHORS |
719 | |
1c846c1f |
720 | The autodocumentation system was originally added to the Perl core by |
721 | Benjamin Stuhl. Documentation is by whoever was kind enough to |
954c1994 |
722 | document their functions. |
723 | |
724 | =head1 SEE ALSO |
725 | |
726 | perlguts(1), perlapi(1) |
727 | |