pod/perlintern.pod

   1 =head1 NAME
   2
   3 perlintern - autogenerated documentation of purely B<internal>
   4                  Perl functions
   5
   6 =head1 DESCRIPTION
   7
   8 This file is the autogenerated documentation of functions in the
   9 Perl interpreter that are documented using Perl's internal documentation
  10 format but are not marked as part of the Perl API. In other words,
  11 B<they are not for use in extensions>!
  12
  13
  14 =head1 Global Variables
  15
  16 =over 8
  17
  18 =item PL_DBsingle
  19
  20 When Perl is run in debugging mode, with the B<-d> switch, this SV is a
  21 boolean which indicates whether subs are being single-stepped.
  22 Single-stepping is automatically turned on after every step.  This is the C
  23 variable which corresponds to Perl's $DB::single variable.  See
  24 C<PL_DBsub>.
  25
  26         SV *    PL_DBsingle
  27
  28 =for hackers
  29 Found in file intrpvar.h
  30
  31 =item PL_DBsub
  32
  33 When Perl is run in debugging mode, with the B<-d> switch, this GV contains
  34 the SV which holds the name of the sub being debugged.  This is the C
  35 variable which corresponds to Perl's $DB::sub variable.  See
  36 C<PL_DBsingle>.
  37
  38         GV *    PL_DBsub
  39
  40 =for hackers
  41 Found in file intrpvar.h
  42
  43 =item PL_DBtrace
  44
  45 Trace variable used when Perl is run in debugging mode, with the B<-d>
  46 switch.  This is the C variable which corresponds to Perl's $DB::trace
  47 variable.  See C<PL_DBsingle>.
  48
  49         SV *    PL_DBtrace
  50
  51 =for hackers
  52 Found in file intrpvar.h
  53
  54 =item PL_dowarn
  55
  56 The C variable which corresponds to Perl's $^W warning variable.
  57
  58         bool    PL_dowarn
  59
  60 =for hackers
  61 Found in file intrpvar.h
  62
  63 =item PL_last_in_gv
  64
  65 The GV which was last used for a filehandle input operation. (C<< <FH> >>)
  66
  67         GV*     PL_last_in_gv
  68
  69 =for hackers
  70 Found in file thrdvar.h
  71
  72 =item PL_ofs_sv
  73
  74 The output field separator - C<$,> in Perl space.
  75
  76         SV*     PL_ofs_sv
  77
  78 =for hackers
  79 Found in file thrdvar.h
  80
  81 =item PL_rs
  82
  83 The input record separator - C<$/> in Perl space.
  84
  85         SV*     PL_rs
  86
  87 =for hackers
  88 Found in file thrdvar.h
  89
  90
  91 =back
  92
  93 =head1 GV Functions
  94
  95 =over 8
  96
  97 =item is_gv_magical
  98
  99 Returns C<TRUE> if given the name of a magical GV.
 100
 101 Currently only useful internally when determining if a GV should be
 102 created even in rvalue contexts.
 103
 104 C<flags> is not used at present but available for future extension to
 105 allow selecting particular classes of magical variable.
 106
 107         bool    is_gv_magical(char *name, STRLEN len, U32 flags)
 108
 109 =for hackers
 110 Found in file gv.c
 111
 112
 113 =back
 114
 115 =head1 IO Functions
 116
 117 =over 8
 118
 119 =item start_glob
 120
 121 Function called by C<do_readline> to spawn a glob (or do the glob inside
 122 perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
 123 this glob starter is only used by miniperl during the build process.
 124 Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.
 125
 126         PerlIO* start_glob(SV* pattern, IO *io)
 127
 128 =for hackers
 129 Found in file doio.c
 130
 131
 132 =back
 133
 134 =head1 Pad Data Structures
 135
 136 =over 8
 137
 138 =item CvPADLIST
 139
 140 CV's can have CvPADLIST(cv) set to point to an AV.
 141
 142 For these purposes "forms" are a kind-of CV, eval""s are too (except they're
 143 not callable at will and are always thrown away after the eval"" is done
 144 executing).
 145
 146 XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
 147 but that is really the callers pad (a slot of which is allocated by
 148 every entersub).
 149
 150 The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
 151 is managed "manual" (mostly in op.c) rather than normal av.c rules.
 152 The items in the AV are not SVs as for a normal AV, but other AVs:
 153
 154 0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
 155 the "static type information" for lexicals.
 156
 157 The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
 158 depth of recursion into the CV.
 159 The 0'th slot of a frame AV is an AV which is @_.
 160 other entries are storage for variables and op targets.
 161
 162 During compilation:
 163 C<PL_comppad_name> is set the the the names AV.
 164 C<PL_comppad> is set the the frame AV for the frame CvDEPTH == 1.
 165 C<PL_curpad> is set the body of the frame AV (i.e. AvARRAY(PL_comppad)).
 166
 167 Itterating over the names AV itterates over all possible pad
 168 items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
 169 &PL_sv_undef "names" (see pad_alloc()).
 170
 171 Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
 172 The rest are op targets/GVs/constants which are statically allocated
 173 or resolved at compile time.  These don't have names by which they
 174 can be looked up from Perl code at run time through eval"" like
 175 my/our variables can be.  Since they can't be looked up by "name"
 176 but only by their index allocated at compile time (which is usually
 177 in PL_op->op_targ), wasting a name SV for them doesn't make sense.
 178
 179 The SVs in the names AV have their PV being the name of the variable.
 180 NV+1..IV inclusive is a range of cop_seq numbers for which the name is valid.
 181 For typed lexicals name SV is SVt_PVMG and SvSTASH points at the type.
 182
 183 If SvFAKE is set on the name SV then slot in the frame AVs are
 184 a REFCNT'ed references to a lexical from "outside".
 185
 186 If the 'name' is '&' the the corresponding entry in frame AV
 187 is a CV representing a possible closure.
 188 (SvFAKE and name of '&' is not a meaningful combination currently but could
 189 become so if C<my sub foo {}> is implemented.)
 190
 191         AV *    CvPADLIST(CV *cv)
 192
 193 =for hackers
 194 Found in file cv.h
 195
 196
 197 =back
 198
 199 =head1 Stack Manipulation Macros
 200
 201 =over 8
 202
 203 =item djSP
 204
 205 Declare Just C<SP>. This is actually identical to C<dSP>, and declares
 206 a local copy of perl's stack pointer, available via the C<SP> macro.
 207 See C<SP>.  (Available for backward source code compatibility with the
 208 old (Perl 5.005) thread model.)
 209
 210                 djSP;
 211
 212 =for hackers
 213 Found in file pp.h
 214
 215 =item LVRET
 216
 217 True if this op will be the return value of an lvalue subroutine
 218
 219 =for hackers
 220 Found in file pp.h
 221
 222
 223 =back
 224
 225 =head1 SV Manipulation Functions
 226
 227 =over 8
 228
 229 =item report_uninit
 230
 231 Print appropriate "Use of uninitialized variable" warning
 232
 233         void    report_uninit()
 234
 235 =for hackers
 236 Found in file sv.c
 237
 238 =item sv_add_arena
 239
 240 Given a chunk of memory, link it to the head of the list of arenas,
 241 and split it into a list of free SVs.
 242
 243         void    sv_add_arena(char* ptr, U32 size, U32 flags)
 244
 245 =for hackers
 246 Found in file sv.c
 247
 248 =item sv_clean_all
 249
 250 Decrement the refcnt of each remaining SV, possibly triggering a
 251 cleanup. This function may have to be called multiple times to free
 252 SVs which are in complex self-referential hierarchies.
 253
 254         I32     sv_clean_all()
 255
 256 =for hackers
 257 Found in file sv.c
 258
 259 =item sv_clean_objs
 260
 261 Attempt to destroy all objects not yet freed
 262
 263         void    sv_clean_objs()
 264
 265 =for hackers
 266 Found in file sv.c
 267
 268 =item sv_free_arenas
 269
 270 Deallocate the memory used by all arenas. Note that all the individual SV
 271 heads and bodies within the arenas must already have been freed.
 272
 273         void    sv_free_arenas()
 274
 275 =for hackers
 276 Found in file sv.c
 277
 278
 279 =back
 280
 281 =head1 AUTHORS
 282
 283 The autodocumentation system was originally added to the Perl core by
 284 Benjamin Stuhl. Documentation is by whoever was kind enough to
 285 document their functions.
 286
 287 =head1 SEE ALSO
 288
 289 perlguts(1), perlapi(1)
 290