1 /* perlvars.h 2 * 3 * Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 4 * by Larry Wall and others 5 * 6 * You may distribute under the terms of either the GNU General Public 7 * License or the Artistic License, as specified in the README file. 8 * 9 */ 10 11 /* 12 =head1 Global Variables 13 These variables are global to an entire process. They are shared between 14 all interpreters and all threads in a process. Any variables not documented 15 here may be changed or removed without notice, so don't use them! 16 If you feel you really do need to use an unlisted variable, first send email to 17 L<perl5-porters@perl.org|mailto:perl5-porters@perl.org>. It may be that 18 someone there will point out a way to accomplish what you need without using an 19 internal variable. But if not, you should get a go-ahead to document and then 20 use the variable. 21 22 =cut 23 */ 24 25 /* Don't forget to re-run regen/embed.pl to propagate changes! */ 26 27 /* This file describes the "global" variables used by perl 28 * This used to be in perl.h directly but we want to abstract out into 29 * distinct files which are per-thread, per-interpreter or really global, 30 * and how they're initialized. 31 * 32 * The 'G' prefix is only needed for vars that need appropriate #defines 33 * generated in embed*.h. Such symbols are also used to generate 34 * the appropriate export list for win32. */ 35 36 /* global state */ 37 #if defined(USE_ITHREADS) 38 PERLVAR(G, op_mutex, perl_mutex) /* Mutex for op refcounting */ 39 #endif 40 PERLVARI(G, curinterp, PerlInterpreter *, NULL) 41 /* currently running interpreter 42 * (initial parent interpreter under 43 * useithreads) */ 44 #if defined(USE_ITHREADS) 45 PERLVAR(G, thr_key, perl_key) /* key to retrieve per-thread struct */ 46 #endif 47 48 /* XXX does anyone even use this? */ 49 PERLVARI(G, do_undump, bool, FALSE) /* -u or dump seen? */ 50 51 #if defined(FAKE_PERSISTENT_SIGNAL_HANDLERS)||defined(FAKE_DEFAULT_SIGNAL_HANDLERS) 52 PERLVARI(G, sig_handlers_initted, int, 0) 53 #endif 54 #ifdef FAKE_PERSISTENT_SIGNAL_HANDLERS 55 PERLVARA(G, sig_ignoring, SIG_SIZE, int) 56 /* which signals we are ignoring */ 57 #endif 58 #ifdef FAKE_DEFAULT_SIGNAL_HANDLERS 59 PERLVARA(G, sig_defaulting, SIG_SIZE, int) 60 #endif 61 62 /* XXX signals are process-wide anyway, so we 63 * ignore the implications of this for threading */ 64 #ifndef HAS_SIGACTION 65 PERLVARI(G, sig_trapped, int, 0) 66 #endif 67 68 /* If Perl has to ignore SIGPFE, this is its saved state. 69 * See perl.h macros PERL_FPU_INIT and PERL_FPU_{PRE,POST}_EXEC. */ 70 PERLVAR(G, sigfpe_saved, Sighandler_t) 71 72 /* these ptrs to functions are to avoid linkage problems; see 73 * perl-5.8.0-2193-g5c1546dc48 74 */ 75 PERLVARI(G, csighandlerp, Sighandler_t, Perl_csighandler) 76 PERLVARI(G, csighandler1p, Sighandler1_t, Perl_csighandler1) 77 PERLVARI(G, csighandler3p, Sighandler3_t, Perl_csighandler3) 78 79 /* This is constant on most architectures, a global on OS/2 */ 80 #ifdef OS2 81 PERLVARI(G, sh_path, char *, SH_PATH) /* full path of shell */ 82 #endif 83 84 #ifdef USE_PERLIO 85 86 # if defined(USE_ITHREADS) 87 PERLVAR(G, perlio_mutex, perl_mutex) /* Mutex for perlio fd refcounts */ 88 # endif 89 90 PERLVARI(G, perlio_fd_refcnt, int *, 0) /* Pointer to array of fd refcounts. */ 91 PERLVARI(G, perlio_fd_refcnt_size, int, 0) /* Size of the array */ 92 PERLVARI(G, perlio_debug_fd, int, 0) /* the fd to write perlio debug into, 0 means not set yet */ 93 #endif 94 95 #ifdef HAS_MMAP 96 PERLVARI(G, mmap_page_size, IV, 0) 97 #endif 98 99 #if defined(USE_ITHREADS) 100 PERLVAR(G, hints_mutex, perl_mutex) /* Mutex for refcounted he refcounting */ 101 PERLVAR(G, env_mutex, perl_RnW1_mutex_t) /* Mutex for accessing ENV */ 102 PERLVAR(G, locale_mutex, perl_mutex) /* Mutex related to locale handling */ 103 #endif 104 105 #ifdef USE_POSIX_2008_LOCALE 106 PERLVARI(G, C_locale_obj, locale_t, NULL) 107 #endif 108 109 PERLVARI(G, watch_pvx, char *, NULL) 110 111 /* 112 =for apidoc AmnU|Perl_check_t *|PL_check 113 114 Array, indexed by opcode, of functions that will be called for the "check" 115 phase of optree building during compilation of Perl code. For most (but 116 not all) types of op, once the op has been initially built and populated 117 with child ops it will be filtered through the check function referenced 118 by the appropriate element of this array. The new op is passed in as the 119 sole argument to the check function, and the check function returns the 120 completed op. The check function may (as the name suggests) check the op 121 for validity and signal errors. It may also initialise or modify parts of 122 the ops, or perform more radical surgery such as adding or removing child 123 ops, or even throw the op away and return a different op in its place. 124 125 This array of function pointers is a convenient place to hook into the 126 compilation process. An XS module can put its own custom check function 127 in place of any of the standard ones, to influence the compilation of a 128 particular type of op. However, a custom check function must never fully 129 replace a standard check function (or even a custom check function from 130 another module). A module modifying checking must instead B<wrap> the 131 preexisting check function. A custom check function must be selective 132 about when to apply its custom behaviour. In the usual case where 133 it decides not to do anything special with an op, it must chain the 134 preexisting op function. Check functions are thus linked in a chain, 135 with the core's base checker at the end. 136 137 For thread safety, modules should not write directly to this array. 138 Instead, use the function L</wrap_op_checker>. 139 140 =for apidoc Amn|enum perl_phase|PL_phase 141 142 A value that indicates the current Perl interpreter's phase. Possible values 143 include C<PERL_PHASE_CONSTRUCT>, C<PERL_PHASE_START>, C<PERL_PHASE_CHECK>, 144 C<PERL_PHASE_INIT>, C<PERL_PHASE_RUN>, C<PERL_PHASE_END>, and 145 C<PERL_PHASE_DESTRUCT>. 146 147 For example, the following determines whether the interpreter is in 148 global destruction: 149 150 if (PL_phase == PERL_PHASE_DESTRUCT) { 151 // we are in global destruction 152 } 153 154 C<PL_phase> was introduced in Perl 5.14; in prior perls you can use 155 C<PL_dirty> (boolean) to determine whether the interpreter is in global 156 destruction. (Use of C<PL_dirty> is discouraged since 5.14.) 157 158 =cut 159 */ 160 161 #if defined(USE_ITHREADS) 162 PERLVAR(G, check_mutex, perl_mutex) /* Mutex for PL_check */ 163 #endif 164 165 /* allocate a unique index to every module that calls MY_CXT_INIT */ 166 167 #ifdef MULTIPLICITY 168 # ifdef USE_ITHREADS 169 PERLVAR(G, my_ctx_mutex, perl_mutex) 170 PERLVARI(G, veto_switch_non_tTHX_context, int, FALSE) 171 # endif 172 PERLVARI(G, my_cxt_index, int, 0) 173 #endif 174 175 /* this is currently set without MUTEX protection, so keep it a type which 176 * can be set atomically (ie not a bit field) */ 177 PERLVARI(G, veto_cleanup, int, FALSE) /* exit without cleanup */ 178 179 /* 180 =for apidoc AmnUx|Perl_keyword_plugin_t|PL_keyword_plugin 181 182 Function pointer, pointing at a function used to handle extended keywords. 183 The function should be declared as 184 185 int keyword_plugin_function(pTHX_ 186 char *keyword_ptr, STRLEN keyword_len, 187 OP **op_ptr) 188 189 The function is called from the tokeniser, whenever a possible keyword 190 is seen. C<keyword_ptr> points at the word in the parser's input 191 buffer, and C<keyword_len> gives its length; it is not null-terminated. 192 The function is expected to examine the word, and possibly other state 193 such as L<%^H|perlvar/%^H>, to decide whether it wants to handle it 194 as an extended keyword. If it does not, the function should return 195 C<KEYWORD_PLUGIN_DECLINE>, and the normal parser process will continue. 196 197 If the function wants to handle the keyword, it first must 198 parse anything following the keyword that is part of the syntax 199 introduced by the keyword. See L</Lexer interface> for details. 200 201 When a keyword is being handled, the plugin function must build 202 a tree of C<OP> structures, representing the code that was parsed. 203 The root of the tree must be stored in C<*op_ptr>. The function then 204 returns a constant indicating the syntactic role of the construct that 205 it has parsed: C<KEYWORD_PLUGIN_STMT> if it is a complete statement, or 206 C<KEYWORD_PLUGIN_EXPR> if it is an expression. Note that a statement 207 construct cannot be used inside an expression (except via C<do BLOCK> 208 and similar), and an expression is not a complete statement (it requires 209 at least a terminating semicolon). 210 211 When a keyword is handled, the plugin function may also have 212 (compile-time) side effects. It may modify C<%^H>, define functions, and 213 so on. Typically, if side effects are the main purpose of a handler, 214 it does not wish to generate any ops to be included in the normal 215 compilation. In this case it is still required to supply an op tree, 216 but it suffices to generate a single null op. 217 218 That's how the C<*PL_keyword_plugin> function needs to behave overall. 219 Conventionally, however, one does not completely replace the existing 220 handler function. Instead, take a copy of C<PL_keyword_plugin> before 221 assigning your own function pointer to it. Your handler function should 222 look for keywords that it is interested in and handle those. Where it 223 is not interested, it should call the saved plugin function, passing on 224 the arguments it received. Thus C<PL_keyword_plugin> actually points 225 at a chain of handler functions, all of which have an opportunity to 226 handle keywords, and only the last function in the chain (built into 227 the Perl core) will normally return C<KEYWORD_PLUGIN_DECLINE>. 228 229 For thread safety, modules should not set this variable directly. 230 Instead, use the function L</wrap_keyword_plugin>. 231 232 =cut 233 */ 234 235 #if defined(USE_ITHREADS) 236 PERLVAR(G, keyword_plugin_mutex, perl_mutex) /* Mutex for PL_keyword_plugin and PL_infix_plugin */ 237 #endif 238 PERLVARI(G, keyword_plugin, Perl_keyword_plugin_t, Perl_keyword_plugin_standard) 239 240 /* 241 =for apidoc AmnUx|Perl_infix_plugin_t|PL_infix_plugin 242 243 B<NOTE:> This API exists entirely for the purpose of making the CPAN module 244 C<XS::Parse::Infix> work. It is not expected that additional modules will make 245 use of it; rather, that they should use C<XS::Parse::Infix> to provide parsing 246 of new infix operators. 247 248 Function pointer, pointing at a function used to handle extended infix 249 operators. The function should be declared as 250 251 int infix_plugin_function(pTHX_ 252 char *opname, STRLEN oplen, 253 struct Perl_custom_infix **infix_ptr) 254 255 The function is called from the tokenizer whenever a possible infix operator 256 is seen. C<opname> points to the operator name in the parser's input buffer, 257 and C<oplen> gives the I<maximum> number of bytes of it that should be 258 consumed; it is not null-terminated. The function is expected to examine the 259 operator name and possibly other state such as L<%^H|perlvar/%^H>, to 260 determine whether it wants to handle the operator name. 261 262 As compared to the single stage of C<PL_keyword_plugin>, parsing of additional 263 infix operators occurs in three separate stages. This is because of the more 264 complex interactions it has with the parser, to ensure that operator 265 precedence rules work correctly. These stages are co-ordinated by the use of 266 an additional information structure. 267 268 If the function wants to handle the infix operator, it must set the variable 269 pointed to by C<infix_ptr> to the address of a structure that provides this 270 additional information about the subsequent parsing stages. If it does not, 271 it should make a call to the next function in the chain. 272 273 This structure has the following definition: 274 275 struct Perl_custom_infix { 276 enum Perl_custom_infix_precedence prec; 277 void (*parse)(pTHX_ SV **opdata, 278 struct Perl_custom_infix *); 279 OP *(*build_op)(pTHX_ SV **opdata, OP *lhs, OP *rhs, 280 struct Perl_custom_infix *); 281 }; 282 283 The function must then return an integer giving the number of bytes consumed 284 by the name of this operator. In the case of an operator whose name is 285 composed of identifier characters, this must be equal to C<oplen>. In the case 286 of an operator named by non-identifier characters, this is permitted to be 287 shorter than C<oplen>, and any additional characters after it will not be 288 claimed by the infix operator but instead will be consumed by the tokenizer 289 and parser as normal. 290 291 If the optional C<parse> function is provided, it is called immediately by the 292 parser to let the operator's definition consume any additional syntax from the 293 source code. This should I<not> be used for normal operand parsing, but it may 294 be useful when implementing things like parametric operators or meta-operators 295 that consume more syntax themselves. This function may use the variable 296 pointed to by C<opdata> to provide an SV containing additional data to be 297 passed into the C<build_op> function later on. 298 299 The information structure gives the operator precedence level in the C<prec> 300 field. This is used to tell the parser how much of the surrounding syntax 301 before and after should be considered as operands to the operator. 302 303 The tokenizer and parser will then continue to operate as normal until enough 304 additional input has been parsed to form both the left- and right-hand side 305 operands to the operator, according to the precedence level. At this point the 306 C<build_op> function is called, being passed the left- and right-hand operands 307 as optree fragments. It is expected to combine them into the resulting optree 308 fragment, which it should return. 309 310 After the C<build_op> function has returned, if the variable pointed to by 311 C<opdata> was set to a non-C<NULL> value, it will then be destroyed by calling 312 C<SvREFCNT_dec()>. 313 314 For thread safety, modules should not set this variable directly. 315 Instead, use the function L</wrap_infix_plugin>. 316 317 However, that all said, the introductory note above still applies. This 318 variable is provided in core perl only for the benefit of the 319 C<XS::Parse::Infix> module. That module acts as a central registry for infix 320 operators, automatically handling things like deparse support and 321 discovery/reflection, and these abilities only work because it knows all the 322 registered operators. Other modules should not use this interpreter variable 323 directly to implement them because then those central features would no longer 324 work properly. 325 326 Furthermore, it is likely that this (experimental) API will be replaced in a 327 future Perl version by a more complete API that fully implements the central 328 registry and other semantics currently provided by C<XS::Parse::Infix>, once 329 the module has had sufficient experimental testing time. This current 330 mechanism exists only as an interim measure to get to that stage. 331 332 =cut 333 */ 334 335 PERLVARI(G, infix_plugin, Perl_infix_plugin_t, Perl_infix_plugin_standard) 336 337 PERLVARI(G, op_sequence, HV *, NULL) /* dump.c */ 338 PERLVARI(G, op_seq, UV, 0) /* dump.c */ 339 340 #ifdef USE_ITHREADS 341 PERLVAR(G, dollarzero_mutex, perl_mutex) /* Modifying $0 */ 342 #endif 343 344 /* Restricted hashes placeholder value. 345 In theory, the contents are never used, only the address. 346 In practice, &PL_sv_placeholder is returned by some APIs, and the calling 347 code is checking SvOK(). */ 348 349 PERLVAR(G, sv_placeholder, SV) 350 351 #if defined(MYMALLOC) && defined(USE_ITHREADS) 352 PERLVAR(G, malloc_mutex, perl_mutex) /* Mutex for malloc */ 353 #endif 354 355 PERLVARI(G, hash_seed_set, bool, FALSE) /* perl.c */ 356 PERLVARA(G, hash_seed_w, PERL_HASH_SEED_WORDS, PVT__PERL_HASH_WORD_TYPE) /* perl.c and hv.h */ 357 #if defined(PERL_HASH_STATE_BYTES) 358 PERLVARA(G, hash_state_w, PERL_HASH_STATE_WORDS, PVT__PERL_HASH_WORD_TYPE) /* perl.c and hv.h */ 359 #endif 360 #if defined(PERL_USE_SINGLE_CHAR_HASH_CACHE) 361 #define PERL_SINGLE_CHAR_HASH_CACHE_ELEMS ((1+256) * sizeof(U32)) 362 PERLVARA(G, hash_chars, PERL_SINGLE_CHAR_HASH_CACHE_ELEMS, unsigned char) /* perl.c and hv.h */ 363 #endif 364 365 /* The path separator can vary depending on whether we're running under DCL or 366 * a Unix shell. 367 */ 368 #ifdef __VMS 369 PERLVAR(G, perllib_sep, char) 370 #endif 371 372 /* Definitions of user-defined \p{} properties, as the subs that define them 373 * are only called once */ 374 PERLVARI(G, user_def_props, HV *, NULL) 375 376 #if defined(USE_ITHREADS) 377 PERLVAR(G, user_def_props_aTHX, PerlInterpreter *) /* aTHX that user_def_props 378 was defined in */ 379 PERLVAR(G, user_prop_mutex, perl_mutex) /* Mutex for manipulating 380 PL_user_defined_properties */ 381 #endif 382 383 /* these record the best way to perform certain IO operations while 384 * atomically setting FD_CLOEXEC. On the first call, a probe is done 385 * and the result recorded for use by subsequent calls. 386 * In theory these variables aren't thread-safe, but the worst that can 387 * happen is that two treads will both do an initial probe 388 */ 389 PERLVARI(G, strategy_dup, int, 0) /* doio.c */ 390 PERLVARI(G, strategy_dup2, int, 0) /* doio.c */ 391 PERLVARI(G, strategy_open, int, 0) /* doio.c */ 392 PERLVARI(G, strategy_open3, int, 0) /* doio.c */ 393 PERLVARI(G, strategy_mkstemp, int, 0) /* doio.c */ 394 PERLVARI(G, strategy_socket, int, 0) /* doio.c */ 395 PERLVARI(G, strategy_accept, int, 0) /* doio.c */ 396 PERLVARI(G, strategy_pipe, int, 0) /* doio.c */ 397 PERLVARI(G, strategy_socketpair, int, 0) /* doio.c */ 398 399 PERLVARI(G, my_environ, char **, NULL) 400 PERLVARI(G, origenviron, char **, NULL) 401