| 1 | =head1 NAME |
| 2 | |
| 3 | perlintern - autogenerated documentation of purely B<internal> |
| 4 | Perl functions |
| 5 | |
| 6 | =head1 DESCRIPTION |
| 7 | X<internal Perl functions> X<interpreter functions> |
| 8 | |
| 9 | This file is the autogenerated documentation of functions in the |
| 10 | Perl interpreter that are documented using Perl's internal documentation |
| 11 | format but are not marked as part of the Perl API. In other words, |
| 12 | B<they are not for use in extensions>! |
| 13 | |
| 14 | |
| 15 | =head1 CV reference counts and CvOUTSIDE |
| 16 | |
| 17 | =over 8 |
| 18 | |
| 19 | =item CvWEAKOUTSIDE |
| 20 | X<CvWEAKOUTSIDE> |
| 21 | |
| 22 | Each CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing |
| 23 | CV (if any). Because pointers to anonymous sub prototypes are |
| 24 | stored in C<&> pad slots, it is a possible to get a circular reference, |
| 25 | with the parent pointing to the child and vice-versa. To avoid the |
| 26 | ensuing memory leak, we do not increment the reference count of the CV |
| 27 | pointed to by C<CvOUTSIDE> in the I<one specific instance> that the parent |
| 28 | has a C<&> pad slot pointing back to us. In this case, we set the |
| 29 | C<CvWEAKOUTSIDE> flag in the child. This allows us to determine under what |
| 30 | circumstances we should decrement the refcount of the parent when freeing |
| 31 | the child. |
| 32 | |
| 33 | There is a further complication with non-closure anonymous subs (i.e. those |
| 34 | that do not refer to any lexicals outside that sub). In this case, the |
| 35 | anonymous prototype is shared rather than being cloned. This has the |
| 36 | consequence that the parent may be freed while there are still active |
| 37 | children, eg |
| 38 | |
| 39 | BEGIN { $a = sub { eval '$x' } } |
| 40 | |
| 41 | In this case, the BEGIN is freed immediately after execution since there |
| 42 | are no active references to it: the anon sub prototype has |
| 43 | C<CvWEAKOUTSIDE> set since it's not a closure, and $a points to the same |
| 44 | CV, so it doesn't contribute to BEGIN's refcount either. When $a is |
| 45 | executed, the C<eval '$x'> causes the chain of C<CvOUTSIDE>s to be followed, |
| 46 | and the freed BEGIN is accessed. |
| 47 | |
| 48 | To avoid this, whenever a CV and its associated pad is freed, any |
| 49 | C<&> entries in the pad are explicitly removed from the pad, and if the |
| 50 | refcount of the pointed-to anon sub is still positive, then that |
| 51 | child's C<CvOUTSIDE> is set to point to its grandparent. This will only |
| 52 | occur in the single specific case of a non-closure anon prototype |
| 53 | having one or more active references (such as C<$a> above). |
| 54 | |
| 55 | One other thing to consider is that a CV may be merely undefined |
| 56 | rather than freed, eg C<undef &foo>. In this case, its refcount may |
| 57 | not have reached zero, but we still delete its pad and its C<CvROOT> etc. |
| 58 | Since various children may still have their C<CvOUTSIDE> pointing at this |
| 59 | undefined CV, we keep its own C<CvOUTSIDE> for the time being, so that |
| 60 | the chain of lexical scopes is unbroken. For example, the following |
| 61 | should print 123: |
| 62 | |
| 63 | my $x = 123; |
| 64 | sub tmp { sub { eval '$x' } } |
| 65 | my $a = tmp(); |
| 66 | undef &tmp; |
| 67 | print $a->(); |
| 68 | |
| 69 | bool CvWEAKOUTSIDE(CV *cv) |
| 70 | |
| 71 | =for hackers |
| 72 | Found in file cv.h |
| 73 | |
| 74 | |
| 75 | =back |
| 76 | |
| 77 | =head1 Functions in file pad.h |
| 78 | |
| 79 | |
| 80 | =over 8 |
| 81 | |
| 82 | =item CX_CURPAD_SAVE |
| 83 | X<CX_CURPAD_SAVE> |
| 84 | |
| 85 | Save the current pad in the given context block structure. |
| 86 | |
| 87 | void CX_CURPAD_SAVE(struct context) |
| 88 | |
| 89 | =for hackers |
| 90 | Found in file pad.h |
| 91 | |
| 92 | =item CX_CURPAD_SV |
| 93 | X<CX_CURPAD_SV> |
| 94 | |
| 95 | Access the SV at offset po in the saved current pad in the given |
| 96 | context block structure (can be used as an lvalue). |
| 97 | |
| 98 | SV * CX_CURPAD_SV(struct context, PADOFFSET po) |
| 99 | |
| 100 | =for hackers |
| 101 | Found in file pad.h |
| 102 | |
| 103 | =item PAD_BASE_SV |
| 104 | X<PAD_BASE_SV> |
| 105 | |
| 106 | Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist |
| 107 | |
| 108 | SV * PAD_BASE_SV(PADLIST padlist, PADOFFSET po) |
| 109 | |
| 110 | =for hackers |
| 111 | Found in file pad.h |
| 112 | |
| 113 | =item PAD_CLONE_VARS |
| 114 | X<PAD_CLONE_VARS> |
| 115 | |
| 116 | |CLONE_PARAMS* param |
| 117 | Clone the state variables associated with running and compiling pads. |
| 118 | |
| 119 | void PAD_CLONE_VARS(PerlInterpreter *proto_perl \) |
| 120 | |
| 121 | =for hackers |
| 122 | Found in file pad.h |
| 123 | |
| 124 | =item PAD_COMPNAME_FLAGS |
| 125 | X<PAD_COMPNAME_FLAGS> |
| 126 | |
| 127 | Return the flags for the current compiling pad name |
| 128 | at offset C<po>. Assumes a valid slot entry. |
| 129 | |
| 130 | U32 PAD_COMPNAME_FLAGS(PADOFFSET po) |
| 131 | |
| 132 | =for hackers |
| 133 | Found in file pad.h |
| 134 | |
| 135 | =item PAD_COMPNAME_GEN |
| 136 | X<PAD_COMPNAME_GEN> |
| 137 | |
| 138 | The generation number of the name at offset C<po> in the current |
| 139 | compiling pad (lvalue). Note that C<SvCUR> is hijacked for this purpose. |
| 140 | |
| 141 | STRLEN PAD_COMPNAME_GEN(PADOFFSET po) |
| 142 | |
| 143 | =for hackers |
| 144 | Found in file pad.h |
| 145 | |
| 146 | =item PAD_COMPNAME_GEN_set |
| 147 | X<PAD_COMPNAME_GEN_set> |
| 148 | |
| 149 | Sets the generation number of the name at offset C<po> in the current |
| 150 | ling pad (lvalue) to C<gen>. Note that C<SvCUR_set> is hijacked for this purpose. |
| 151 | |
| 152 | STRLEN PAD_COMPNAME_GEN_set(PADOFFSET po, int gen) |
| 153 | |
| 154 | =for hackers |
| 155 | Found in file pad.h |
| 156 | |
| 157 | =item PAD_COMPNAME_OURSTASH |
| 158 | X<PAD_COMPNAME_OURSTASH> |
| 159 | |
| 160 | Return the stash associated with an C<our> variable. |
| 161 | Assumes the slot entry is a valid C<our> lexical. |
| 162 | |
| 163 | HV * PAD_COMPNAME_OURSTASH(PADOFFSET po) |
| 164 | |
| 165 | =for hackers |
| 166 | Found in file pad.h |
| 167 | |
| 168 | =item PAD_COMPNAME_PV |
| 169 | X<PAD_COMPNAME_PV> |
| 170 | |
| 171 | Return the name of the current compiling pad name |
| 172 | at offset C<po>. Assumes a valid slot entry. |
| 173 | |
| 174 | char * PAD_COMPNAME_PV(PADOFFSET po) |
| 175 | |
| 176 | =for hackers |
| 177 | Found in file pad.h |
| 178 | |
| 179 | =item PAD_COMPNAME_TYPE |
| 180 | X<PAD_COMPNAME_TYPE> |
| 181 | |
| 182 | Return the type (stash) of the current compiling pad name at offset |
| 183 | C<po>. Must be a valid name. Returns null if not typed. |
| 184 | |
| 185 | HV * PAD_COMPNAME_TYPE(PADOFFSET po) |
| 186 | |
| 187 | =for hackers |
| 188 | Found in file pad.h |
| 189 | |
| 190 | =item PAD_DUP |
| 191 | X<PAD_DUP> |
| 192 | |
| 193 | Clone a padlist. |
| 194 | |
| 195 | void PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param) |
| 196 | |
| 197 | =for hackers |
| 198 | Found in file pad.h |
| 199 | |
| 200 | =item PAD_RESTORE_LOCAL |
| 201 | X<PAD_RESTORE_LOCAL> |
| 202 | |
| 203 | Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL() |
| 204 | |
| 205 | void PAD_RESTORE_LOCAL(PAD *opad) |
| 206 | |
| 207 | =for hackers |
| 208 | Found in file pad.h |
| 209 | |
| 210 | =item PAD_SAVE_LOCAL |
| 211 | X<PAD_SAVE_LOCAL> |
| 212 | |
| 213 | Save the current pad to the local variable opad, then make the |
| 214 | current pad equal to npad |
| 215 | |
| 216 | void PAD_SAVE_LOCAL(PAD *opad, PAD *npad) |
| 217 | |
| 218 | =for hackers |
| 219 | Found in file pad.h |
| 220 | |
| 221 | =item PAD_SAVE_SETNULLPAD |
| 222 | X<PAD_SAVE_SETNULLPAD> |
| 223 | |
| 224 | Save the current pad then set it to null. |
| 225 | |
| 226 | void PAD_SAVE_SETNULLPAD() |
| 227 | |
| 228 | =for hackers |
| 229 | Found in file pad.h |
| 230 | |
| 231 | =item PAD_SETSV |
| 232 | X<PAD_SETSV> |
| 233 | |
| 234 | Set the slot at offset C<po> in the current pad to C<sv> |
| 235 | |
| 236 | SV * PAD_SETSV(PADOFFSET po, SV* sv) |
| 237 | |
| 238 | =for hackers |
| 239 | Found in file pad.h |
| 240 | |
| 241 | =item PAD_SET_CUR |
| 242 | X<PAD_SET_CUR> |
| 243 | |
| 244 | Set the current pad to be pad C<n> in the padlist, saving |
| 245 | the previous current pad. NB currently this macro expands to a string too |
| 246 | long for some compilers, so it's best to replace it with |
| 247 | |
| 248 | SAVECOMPPAD(); |
| 249 | PAD_SET_CUR_NOSAVE(padlist,n); |
| 250 | |
| 251 | |
| 252 | void PAD_SET_CUR(PADLIST padlist, I32 n) |
| 253 | |
| 254 | =for hackers |
| 255 | Found in file pad.h |
| 256 | |
| 257 | =item PAD_SET_CUR_NOSAVE |
| 258 | X<PAD_SET_CUR_NOSAVE> |
| 259 | |
| 260 | like PAD_SET_CUR, but without the save |
| 261 | |
| 262 | void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n) |
| 263 | |
| 264 | =for hackers |
| 265 | Found in file pad.h |
| 266 | |
| 267 | =item PAD_SV |
| 268 | X<PAD_SV> |
| 269 | |
| 270 | Get the value at offset C<po> in the current pad |
| 271 | |
| 272 | void PAD_SV(PADOFFSET po) |
| 273 | |
| 274 | =for hackers |
| 275 | Found in file pad.h |
| 276 | |
| 277 | =item PAD_SVl |
| 278 | X<PAD_SVl> |
| 279 | |
| 280 | Lightweight and lvalue version of C<PAD_SV>. |
| 281 | Get or set the value at offset C<po> in the current pad. |
| 282 | Unlike C<PAD_SV>, does not print diagnostics with -DX. |
| 283 | For internal use only. |
| 284 | |
| 285 | SV * PAD_SVl(PADOFFSET po) |
| 286 | |
| 287 | =for hackers |
| 288 | Found in file pad.h |
| 289 | |
| 290 | =item SAVECLEARSV |
| 291 | X<SAVECLEARSV> |
| 292 | |
| 293 | Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my') |
| 294 | |
| 295 | void SAVECLEARSV(SV **svp) |
| 296 | |
| 297 | =for hackers |
| 298 | Found in file pad.h |
| 299 | |
| 300 | =item SAVECOMPPAD |
| 301 | X<SAVECOMPPAD> |
| 302 | |
| 303 | save PL_comppad and PL_curpad |
| 304 | |
| 305 | |
| 306 | |
| 307 | |
| 308 | |
| 309 | void SAVECOMPPAD() |
| 310 | |
| 311 | =for hackers |
| 312 | Found in file pad.h |
| 313 | |
| 314 | =item SAVEPADSV |
| 315 | X<SAVEPADSV> |
| 316 | |
| 317 | Save a pad slot (used to restore after an iteration) |
| 318 | |
| 319 | XXX DAPM it would make more sense to make the arg a PADOFFSET |
| 320 | void SAVEPADSV(PADOFFSET po) |
| 321 | |
| 322 | =for hackers |
| 323 | Found in file pad.h |
| 324 | |
| 325 | |
| 326 | =back |
| 327 | |
| 328 | =head1 Functions in file pp_ctl.c |
| 329 | |
| 330 | |
| 331 | =over 8 |
| 332 | |
| 333 | =item find_runcv |
| 334 | X<find_runcv> |
| 335 | |
| 336 | Locate the CV corresponding to the currently executing sub or eval. |
| 337 | If db_seqp is non_null, skip CVs that are in the DB package and populate |
| 338 | *db_seqp with the cop sequence number at the point that the DB:: code was |
| 339 | entered. (allows debuggers to eval in the scope of the breakpoint rather |
| 340 | than in the scope of the debugger itself). |
| 341 | |
| 342 | CV* find_runcv(U32 *db_seqp) |
| 343 | |
| 344 | =for hackers |
| 345 | Found in file pp_ctl.c |
| 346 | |
| 347 | |
| 348 | =back |
| 349 | |
| 350 | =head1 Global Variables |
| 351 | |
| 352 | =over 8 |
| 353 | |
| 354 | =item PL_DBsingle |
| 355 | X<PL_DBsingle> |
| 356 | |
| 357 | When Perl is run in debugging mode, with the B<-d> switch, this SV is a |
| 358 | boolean which indicates whether subs are being single-stepped. |
| 359 | Single-stepping is automatically turned on after every step. This is the C |
| 360 | variable which corresponds to Perl's $DB::single variable. See |
| 361 | C<PL_DBsub>. |
| 362 | |
| 363 | SV * PL_DBsingle |
| 364 | |
| 365 | =for hackers |
| 366 | Found in file intrpvar.h |
| 367 | |
| 368 | =item PL_DBsub |
| 369 | X<PL_DBsub> |
| 370 | |
| 371 | When Perl is run in debugging mode, with the B<-d> switch, this GV contains |
| 372 | the SV which holds the name of the sub being debugged. This is the C |
| 373 | variable which corresponds to Perl's $DB::sub variable. See |
| 374 | C<PL_DBsingle>. |
| 375 | |
| 376 | GV * PL_DBsub |
| 377 | |
| 378 | =for hackers |
| 379 | Found in file intrpvar.h |
| 380 | |
| 381 | =item PL_DBtrace |
| 382 | X<PL_DBtrace> |
| 383 | |
| 384 | Trace variable used when Perl is run in debugging mode, with the B<-d> |
| 385 | switch. This is the C variable which corresponds to Perl's $DB::trace |
| 386 | variable. See C<PL_DBsingle>. |
| 387 | |
| 388 | SV * PL_DBtrace |
| 389 | |
| 390 | =for hackers |
| 391 | Found in file intrpvar.h |
| 392 | |
| 393 | =item PL_dowarn |
| 394 | X<PL_dowarn> |
| 395 | |
| 396 | The C variable which corresponds to Perl's $^W warning variable. |
| 397 | |
| 398 | bool PL_dowarn |
| 399 | |
| 400 | =for hackers |
| 401 | Found in file intrpvar.h |
| 402 | |
| 403 | =item PL_last_in_gv |
| 404 | X<PL_last_in_gv> |
| 405 | |
| 406 | The GV which was last used for a filehandle input operation. (C<< <FH> >>) |
| 407 | |
| 408 | GV* PL_last_in_gv |
| 409 | |
| 410 | =for hackers |
| 411 | Found in file thrdvar.h |
| 412 | |
| 413 | =item PL_ofs_sv |
| 414 | X<PL_ofs_sv> |
| 415 | |
| 416 | The output field separator - C<$,> in Perl space. |
| 417 | |
| 418 | SV* PL_ofs_sv |
| 419 | |
| 420 | =for hackers |
| 421 | Found in file thrdvar.h |
| 422 | |
| 423 | =item PL_rs |
| 424 | X<PL_rs> |
| 425 | |
| 426 | The input record separator - C<$/> in Perl space. |
| 427 | |
| 428 | SV* PL_rs |
| 429 | |
| 430 | =for hackers |
| 431 | Found in file thrdvar.h |
| 432 | |
| 433 | |
| 434 | =back |
| 435 | |
| 436 | =head1 GV Functions |
| 437 | |
| 438 | =over 8 |
| 439 | |
| 440 | =item is_gv_magical |
| 441 | X<is_gv_magical> |
| 442 | |
| 443 | Returns C<TRUE> if given the name of a magical GV. |
| 444 | |
| 445 | Currently only useful internally when determining if a GV should be |
| 446 | created even in rvalue contexts. |
| 447 | |
| 448 | C<flags> is not used at present but available for future extension to |
| 449 | allow selecting particular classes of magical variable. |
| 450 | |
| 451 | Currently assumes that C<name> is NUL terminated (as well as len being valid). |
| 452 | This assumption is met by all callers within the perl core, which all pass |
| 453 | pointers returned by SvPV. |
| 454 | |
| 455 | bool is_gv_magical(char *name, STRLEN len, U32 flags) |
| 456 | |
| 457 | =for hackers |
| 458 | Found in file gv.c |
| 459 | |
| 460 | |
| 461 | =back |
| 462 | |
| 463 | =head1 IO Functions |
| 464 | |
| 465 | =over 8 |
| 466 | |
| 467 | =item start_glob |
| 468 | X<start_glob> |
| 469 | |
| 470 | Function called by C<do_readline> to spawn a glob (or do the glob inside |
| 471 | perl on VMS). This code used to be inline, but now perl uses C<File::Glob> |
| 472 | this glob starter is only used by miniperl during the build process. |
| 473 | Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up. |
| 474 | |
| 475 | PerlIO* start_glob(SV* pattern, IO *io) |
| 476 | |
| 477 | =for hackers |
| 478 | Found in file doio.c |
| 479 | |
| 480 | |
| 481 | =back |
| 482 | |
| 483 | =head1 Pad Data Structures |
| 484 | |
| 485 | =over 8 |
| 486 | |
| 487 | =item CvPADLIST |
| 488 | X<CvPADLIST> |
| 489 | |
| 490 | CV's can have CvPADLIST(cv) set to point to an AV. |
| 491 | |
| 492 | For these purposes "forms" are a kind-of CV, eval""s are too (except they're |
| 493 | not callable at will and are always thrown away after the eval"" is done |
| 494 | executing). |
| 495 | |
| 496 | XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad, |
| 497 | but that is really the callers pad (a slot of which is allocated by |
| 498 | every entersub). |
| 499 | |
| 500 | The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items |
| 501 | is managed "manual" (mostly in pad.c) rather than normal av.c rules. |
| 502 | The items in the AV are not SVs as for a normal AV, but other AVs: |
| 503 | |
| 504 | 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather |
| 505 | the "static type information" for lexicals. |
| 506 | |
| 507 | The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that |
| 508 | depth of recursion into the CV. |
| 509 | The 0'th slot of a frame AV is an AV which is @_. |
| 510 | other entries are storage for variables and op targets. |
| 511 | |
| 512 | During compilation: |
| 513 | C<PL_comppad_name> is set to the names AV. |
| 514 | C<PL_comppad> is set to the frame AV for the frame CvDEPTH == 1. |
| 515 | C<PL_curpad> is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)). |
| 516 | |
| 517 | During execution, C<PL_comppad> and C<PL_curpad> refer to the live |
| 518 | frame of the currently executing sub. |
| 519 | |
| 520 | Iterating over the names AV iterates over all possible pad |
| 521 | items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having |
| 522 | &PL_sv_undef "names" (see pad_alloc()). |
| 523 | |
| 524 | Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names. |
| 525 | The rest are op targets/GVs/constants which are statically allocated |
| 526 | or resolved at compile time. These don't have names by which they |
| 527 | can be looked up from Perl code at run time through eval"" like |
| 528 | my/our variables can be. Since they can't be looked up by "name" |
| 529 | but only by their index allocated at compile time (which is usually |
| 530 | in PL_op->op_targ), wasting a name SV for them doesn't make sense. |
| 531 | |
| 532 | The SVs in the names AV have their PV being the name of the variable. |
| 533 | NV+1..IV inclusive is a range of cop_seq numbers for which the name is |
| 534 | valid. For typed lexicals name SV is SVt_PVMG and SvSTASH points at the |
| 535 | type. For C<our> lexicals, the type is SVt_PVGV, and GvSTASH points at the |
| 536 | stash of the associated global (so that duplicate C<our> declarations in the |
| 537 | same package can be detected). SvCUR is sometimes hijacked to |
| 538 | store the generation number during compilation. |
| 539 | |
| 540 | If SvFAKE is set on the name SV then slot in the frame AVs are |
| 541 | a REFCNT'ed references to a lexical from "outside". In this case, |
| 542 | the name SV does not have a cop_seq range, since it is in scope |
| 543 | throughout. |
| 544 | |
| 545 | If the 'name' is '&' the corresponding entry in frame AV |
| 546 | is a CV representing a possible closure. |
| 547 | (SvFAKE and name of '&' is not a meaningful combination currently but could |
| 548 | become so if C<my sub foo {}> is implemented.) |
| 549 | |
| 550 | The flag SVf_PADSTALE is cleared on lexicals each time the my() is executed, |
| 551 | and set on scope exit. This allows the 'Variable $x is not available' warning |
| 552 | to be generated in evals, such as |
| 553 | |
| 554 | { my $x = 1; sub f { eval '$x'} } f(); |
| 555 | |
| 556 | AV * CvPADLIST(CV *cv) |
| 557 | |
| 558 | =for hackers |
| 559 | Found in file pad.c |
| 560 | |
| 561 | =item cv_clone |
| 562 | X<cv_clone> |
| 563 | |
| 564 | Clone a CV: make a new CV which points to the same code etc, but which |
| 565 | has a newly-created pad built by copying the prototype pad and capturing |
| 566 | any outer lexicals. |
| 567 | |
| 568 | CV* cv_clone(CV* proto) |
| 569 | |
| 570 | =for hackers |
| 571 | Found in file pad.c |
| 572 | |
| 573 | =item cv_dump |
| 574 | X<cv_dump> |
| 575 | |
| 576 | dump the contents of a CV |
| 577 | |
| 578 | void cv_dump(const CV *cv, const char *title) |
| 579 | |
| 580 | =for hackers |
| 581 | Found in file pad.c |
| 582 | |
| 583 | =item do_dump_pad |
| 584 | X<do_dump_pad> |
| 585 | |
| 586 | Dump the contents of a padlist |
| 587 | |
| 588 | void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full) |
| 589 | |
| 590 | =for hackers |
| 591 | Found in file pad.c |
| 592 | |
| 593 | =item intro_my |
| 594 | X<intro_my> |
| 595 | |
| 596 | "Introduce" my variables to visible status. |
| 597 | |
| 598 | U32 intro_my() |
| 599 | |
| 600 | =for hackers |
| 601 | Found in file pad.c |
| 602 | |
| 603 | =item pad_add_anon |
| 604 | X<pad_add_anon> |
| 605 | |
| 606 | Add an anon code entry to the current compiling pad |
| 607 | |
| 608 | PADOFFSET pad_add_anon(SV* sv, OPCODE op_type) |
| 609 | |
| 610 | =for hackers |
| 611 | Found in file pad.c |
| 612 | |
| 613 | =item pad_add_name |
| 614 | X<pad_add_name> |
| 615 | |
| 616 | Create a new name in the current pad at the specified offset. |
| 617 | If C<typestash> is valid, the name is for a typed lexical; set the |
| 618 | name's stash to that value. |
| 619 | If C<ourstash> is valid, it's an our lexical, set the name's |
| 620 | GvSTASH to that value |
| 621 | |
| 622 | Also, if the name is @.. or %.., create a new array or hash for that slot |
| 623 | |
| 624 | If fake, it means we're cloning an existing entry |
| 625 | |
| 626 | PADOFFSET pad_add_name(char *name, HV* typestash, HV* ourstash, bool clone) |
| 627 | |
| 628 | =for hackers |
| 629 | Found in file pad.c |
| 630 | |
| 631 | =item pad_alloc |
| 632 | X<pad_alloc> |
| 633 | |
| 634 | Allocate a new my or tmp pad entry. For a my, simply push a null SV onto |
| 635 | the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards |
| 636 | for a slot which has no name and no active value. |
| 637 | |
| 638 | PADOFFSET pad_alloc(I32 optype, U32 tmptype) |
| 639 | |
| 640 | =for hackers |
| 641 | Found in file pad.c |
| 642 | |
| 643 | =item pad_block_start |
| 644 | X<pad_block_start> |
| 645 | |
| 646 | Update the pad compilation state variables on entry to a new block |
| 647 | |
| 648 | void pad_block_start(int full) |
| 649 | |
| 650 | =for hackers |
| 651 | Found in file pad.c |
| 652 | |
| 653 | =item pad_check_dup |
| 654 | X<pad_check_dup> |
| 655 | |
| 656 | Check for duplicate declarations: report any of: |
| 657 | * a my in the current scope with the same name; |
| 658 | * an our (anywhere in the pad) with the same name and the same stash |
| 659 | as C<ourstash> |
| 660 | C<is_our> indicates that the name to check is an 'our' declaration |
| 661 | |
| 662 | void pad_check_dup(char* name, bool is_our, HV* ourstash) |
| 663 | |
| 664 | =for hackers |
| 665 | Found in file pad.c |
| 666 | |
| 667 | =item pad_findlex |
| 668 | X<pad_findlex> |
| 669 | |
| 670 | Find a named lexical anywhere in a chain of nested pads. Add fake entries |
| 671 | in the inner pads if it's found in an outer one. innercv is the CV *inside* |
| 672 | the chain of outer CVs to be searched. If newoff is non-null, this is a |
| 673 | run-time cloning: don't add fake entries, just find the lexical and add a |
| 674 | ref to it at newoff in the current pad. |
| 675 | |
| 676 | PADOFFSET pad_findlex(const char* name, PADOFFSET newoff, const CV* innercv) |
| 677 | |
| 678 | =for hackers |
| 679 | Found in file pad.c |
| 680 | |
| 681 | =item pad_findmy |
| 682 | X<pad_findmy> |
| 683 | |
| 684 | Given a lexical name, try to find its offset, first in the current pad, |
| 685 | or failing that, in the pads of any lexically enclosing subs (including |
| 686 | the complications introduced by eval). If the name is found in an outer pad, |
| 687 | then a fake entry is added to the current pad. |
| 688 | Returns the offset in the current pad, or NOT_IN_PAD on failure. |
| 689 | |
| 690 | PADOFFSET pad_findmy(char* name) |
| 691 | |
| 692 | =for hackers |
| 693 | Found in file pad.c |
| 694 | |
| 695 | =item pad_fixup_inner_anons |
| 696 | X<pad_fixup_inner_anons> |
| 697 | |
| 698 | For any anon CVs in the pad, change CvOUTSIDE of that CV from |
| 699 | old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be |
| 700 | moved to a pre-existing CV struct. |
| 701 | |
| 702 | void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv) |
| 703 | |
| 704 | =for hackers |
| 705 | Found in file pad.c |
| 706 | |
| 707 | =item pad_free |
| 708 | X<pad_free> |
| 709 | |
| 710 | Free the SV at offset po in the current pad. |
| 711 | |
| 712 | void pad_free(PADOFFSET po) |
| 713 | |
| 714 | =for hackers |
| 715 | Found in file pad.c |
| 716 | |
| 717 | =item pad_leavemy |
| 718 | X<pad_leavemy> |
| 719 | |
| 720 | Cleanup at end of scope during compilation: set the max seq number for |
| 721 | lexicals in this scope and warn of any lexicals that never got introduced. |
| 722 | |
| 723 | void pad_leavemy() |
| 724 | |
| 725 | =for hackers |
| 726 | Found in file pad.c |
| 727 | |
| 728 | =item pad_new |
| 729 | X<pad_new> |
| 730 | |
| 731 | Create a new compiling padlist, saving and updating the various global |
| 732 | vars at the same time as creating the pad itself. The following flags |
| 733 | can be OR'ed together: |
| 734 | |
| 735 | padnew_CLONE this pad is for a cloned CV |
| 736 | padnew_SAVE save old globals |
| 737 | padnew_SAVESUB also save extra stuff for start of sub |
| 738 | |
| 739 | PADLIST* pad_new(int flags) |
| 740 | |
| 741 | =for hackers |
| 742 | Found in file pad.c |
| 743 | |
| 744 | =item pad_push |
| 745 | X<pad_push> |
| 746 | |
| 747 | Push a new pad frame onto the padlist, unless there's already a pad at |
| 748 | this depth, in which case don't bother creating a new one. |
| 749 | If has_args is true, give the new pad an @_ in slot zero. |
| 750 | |
| 751 | void pad_push(PADLIST *padlist, int depth, int has_args) |
| 752 | |
| 753 | =for hackers |
| 754 | Found in file pad.c |
| 755 | |
| 756 | =item pad_reset |
| 757 | X<pad_reset> |
| 758 | |
| 759 | Mark all the current temporaries for reuse |
| 760 | |
| 761 | void pad_reset() |
| 762 | |
| 763 | =for hackers |
| 764 | Found in file pad.c |
| 765 | |
| 766 | =item pad_setsv |
| 767 | X<pad_setsv> |
| 768 | |
| 769 | Set the entry at offset po in the current pad to sv. |
| 770 | Use the macro PAD_SETSV() rather than calling this function directly. |
| 771 | |
| 772 | void pad_setsv(PADOFFSET po, SV* sv) |
| 773 | |
| 774 | =for hackers |
| 775 | Found in file pad.c |
| 776 | |
| 777 | =item pad_swipe |
| 778 | X<pad_swipe> |
| 779 | |
| 780 | Abandon the tmp in the current pad at offset po and replace with a |
| 781 | new one. |
| 782 | |
| 783 | void pad_swipe(PADOFFSET po, bool refadjust) |
| 784 | |
| 785 | =for hackers |
| 786 | Found in file pad.c |
| 787 | |
| 788 | =item pad_tidy |
| 789 | X<pad_tidy> |
| 790 | |
| 791 | Tidy up a pad after we've finished compiling it: |
| 792 | * remove most stuff from the pads of anonsub prototypes; |
| 793 | * give it a @_; |
| 794 | * mark tmps as such. |
| 795 | |
| 796 | void pad_tidy(padtidy_type type) |
| 797 | |
| 798 | =for hackers |
| 799 | Found in file pad.c |
| 800 | |
| 801 | =item pad_undef |
| 802 | X<pad_undef> |
| 803 | |
| 804 | Free the padlist associated with a CV. |
| 805 | If parts of it happen to be current, we null the relevant |
| 806 | PL_*pad* global vars so that we don't have any dangling references left. |
| 807 | We also repoint the CvOUTSIDE of any about-to-be-orphaned |
| 808 | inner subs to the outer of this cv. |
| 809 | |
| 810 | (This function should really be called pad_free, but the name was already |
| 811 | taken) |
| 812 | |
| 813 | void pad_undef(CV* cv) |
| 814 | |
| 815 | =for hackers |
| 816 | Found in file pad.c |
| 817 | |
| 818 | |
| 819 | =back |
| 820 | |
| 821 | =head1 Stack Manipulation Macros |
| 822 | |
| 823 | =over 8 |
| 824 | |
| 825 | =item djSP |
| 826 | X<djSP> |
| 827 | |
| 828 | Declare Just C<SP>. This is actually identical to C<dSP>, and declares |
| 829 | a local copy of perl's stack pointer, available via the C<SP> macro. |
| 830 | See C<SP>. (Available for backward source code compatibility with the |
| 831 | old (Perl 5.005) thread model.) |
| 832 | |
| 833 | djSP; |
| 834 | |
| 835 | =for hackers |
| 836 | Found in file pp.h |
| 837 | |
| 838 | =item LVRET |
| 839 | X<LVRET> |
| 840 | |
| 841 | True if this op will be the return value of an lvalue subroutine |
| 842 | |
| 843 | =for hackers |
| 844 | Found in file pp.h |
| 845 | |
| 846 | |
| 847 | =back |
| 848 | |
| 849 | =head1 SV Manipulation Functions |
| 850 | |
| 851 | =over 8 |
| 852 | |
| 853 | =item report_uninit |
| 854 | X<report_uninit> |
| 855 | |
| 856 | Print appropriate "Use of uninitialized variable" warning |
| 857 | |
| 858 | void report_uninit() |
| 859 | |
| 860 | =for hackers |
| 861 | Found in file sv.c |
| 862 | |
| 863 | =item sv_add_arena |
| 864 | X<sv_add_arena> |
| 865 | |
| 866 | Given a chunk of memory, link it to the head of the list of arenas, |
| 867 | and split it into a list of free SVs. |
| 868 | |
| 869 | void sv_add_arena(char* ptr, U32 size, U32 flags) |
| 870 | |
| 871 | =for hackers |
| 872 | Found in file sv.c |
| 873 | |
| 874 | =item sv_clean_all |
| 875 | X<sv_clean_all> |
| 876 | |
| 877 | Decrement the refcnt of each remaining SV, possibly triggering a |
| 878 | cleanup. This function may have to be called multiple times to free |
| 879 | SVs which are in complex self-referential hierarchies. |
| 880 | |
| 881 | I32 sv_clean_all() |
| 882 | |
| 883 | =for hackers |
| 884 | Found in file sv.c |
| 885 | |
| 886 | =item sv_clean_objs |
| 887 | X<sv_clean_objs> |
| 888 | |
| 889 | Attempt to destroy all objects not yet freed |
| 890 | |
| 891 | void sv_clean_objs() |
| 892 | |
| 893 | =for hackers |
| 894 | Found in file sv.c |
| 895 | |
| 896 | =item sv_free_arenas |
| 897 | X<sv_free_arenas> |
| 898 | |
| 899 | Deallocate the memory used by all arenas. Note that all the individual SV |
| 900 | heads and bodies within the arenas must already have been freed. |
| 901 | |
| 902 | void sv_free_arenas() |
| 903 | |
| 904 | =for hackers |
| 905 | Found in file sv.c |
| 906 | |
| 907 | |
| 908 | =back |
| 909 | |
| 910 | =head1 AUTHORS |
| 911 | |
| 912 | The autodocumentation system was originally added to the Perl core by |
| 913 | Benjamin Stuhl. Documentation is by whoever was kind enough to |
| 914 | document their functions. |
| 915 | |
| 916 | =head1 SEE ALSO |
| 917 | |
| 918 | perlguts(1), perlapi(1) |
| 919 | |