3 * Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
4 * by Larry Wall and others
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.
12 =head1 Global Variables
15 /* Don't forget to re-run embed.pl to propagate changes! */
17 /* This file describes the "global" variables used by perl
18 * This used to be in perl.h directly but we want to abstract out into
19 * distinct files which are per-thread, per-interpreter or really global,
20 * and how they're initialized.
22 * The 'G' prefix is only needed for vars that need appropriate #defines
23 * generated in embed*.h. Such symbols are also used to generate
24 * the appropriate export list for win32. */
27 PERLVAR(Gcurinterp, PerlInterpreter *)
28 /* currently running interpreter
29 * (initial parent interpreter under
31 #if defined(USE_ITHREADS)
32 PERLVAR(Gthr_key, perl_key) /* key to retrieve per-thread struct */
35 /* constants (these are not literals to facilitate pointer comparisons)
36 * (PERLVARISC really does create variables, despite its looks) */
39 PERLVARISC(Ghexdigit, "0123456789abcdef0123456789ABCDEF")
40 PERLVARISC(Gpatleave, "\\.^$@dDwWsSbB+*?|()-nrtfeaxc0123456789[{]}")
42 /* XXX does anyone even use this? */
43 PERLVARI(Gdo_undump, bool, FALSE) /* -u or dump seen? */
45 #if defined(MYMALLOC) && defined(USE_ITHREADS)
46 PERLVAR(Gmalloc_mutex, perl_mutex) /* Mutex for malloc */
49 #if defined(USE_ITHREADS)
50 PERLVAR(Gop_mutex, perl_mutex) /* Mutex for op refcounting */
54 PERLVAR(Gdollarzero_mutex, perl_mutex) /* Modifying $0 */
58 /* This is constant on most architectures, a global on OS/2 */
62 # define PERL___C const
64 PERLVARI(Gsh_path, PERL___C char *, SH_PATH) /* full path of shell */
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(Gsigfpe_saved, Sighandler_t)
73 /* Restricted hashes placeholder value.
74 * The contents are never used, only the address. */
75 PERLVAR(Gsv_placeholder, SV)
78 PERLVARI(Gcsighandlerp, Sighandler_t, Perl_csighandler) /* Pointer to C-level sighandler */
81 #ifndef PERL_USE_SAFE_PUTENV
82 PERLVARI(Guse_safe_putenv, int, 1)
86 PERLVARI(Gperlio_fd_refcnt, int*, 0) /* Pointer to array of fd refcounts. */
87 PERLVARI(Gperlio_fd_refcnt_size, int, 0) /* Size of the array */
88 PERLVARI(Gperlio_debug_fd, int, 0) /* the fd to write perlio debug into, 0 means not set yet */
92 PERLVARI(Gmmap_page_size, IV, 0)
95 #if defined(FAKE_PERSISTENT_SIGNAL_HANDLERS)||defined(FAKE_DEFAULT_SIGNAL_HANDLERS)
96 PERLVARI(Gsig_handlers_initted, int, 0)
98 #ifdef FAKE_PERSISTENT_SIGNAL_HANDLERS
99 PERLVARA(Gsig_ignoring, SIG_SIZE, int) /* which signals we are ignoring */
101 #ifdef FAKE_DEFAULT_SIGNAL_HANDLERS
102 PERLVARA(Gsig_defaulting, SIG_SIZE, int)
105 #ifndef PERL_IMPLICIT_CONTEXT
106 PERLVAR(Gsig_sv, SV*)
109 /* XXX signals are process-wide anyway, so we
110 * ignore the implications of this for threading */
111 #ifndef HAS_SIGACTION
112 PERLVARI(Gsig_trapped, int, 0)
116 PERLVAR(Gwatch_pvx, char*)
119 #ifdef PERL_GLOBAL_STRUCT
120 PERLVAR(Gppaddr, Perl_ppaddr_t*) /* or opcode.h */
121 PERLVAR(Gcheck, Perl_check_t *) /* or opcode.h */
122 PERLVARA(Gfold_locale, 256, unsigned char) /* or perl.h */
125 #ifdef PERL_NEED_APPCTX
126 PERLVAR(Gappctx, void*) /* the application context */
129 PERLVAR(Gop_sequence, HV*) /* dump.c */
130 PERLVARI(Gop_seq, UV, 0) /* dump.c */
132 #if defined(HAS_TIMES) && defined(PERL_NEED_TIMESBASE)
133 PERLVAR(Gtimesbase, struct tms)
136 /* allocate a unique index to every module that calls MY_CXT_INIT */
138 #ifdef PERL_IMPLICIT_CONTEXT
140 PERLVAR(Gmy_ctx_mutex, perl_mutex)
142 PERLVARI(Gmy_cxt_index, int, 0)
145 #if defined(USE_ITHREADS)
146 PERLVAR(Ghints_mutex, perl_mutex) /* Mutex for refcounted he refcounting */
149 #if defined(USE_ITHREADS)
150 PERLVAR(Gperlio_mutex, perl_mutex) /* Mutex for perlio fd refcounts */
153 /* this is currently set without MUTEX protection, so keep it a type which
154 * can be set atomically (ie not a bit field) */
155 PERLVARI(Gveto_cleanup, int, FALSE) /* exit without cleanup */
157 /* dummy variables that hold pointers to both runops functions, thus forcing
158 * them *both* to get linked in (useful for Peek.xs, debugging etc) */
160 PERLVARI(Grunops_std, runops_proc_t, MEMBER_TO_FPTR(Perl_runops_standard))
161 PERLVARI(Grunops_dbg, runops_proc_t, MEMBER_TO_FPTR(Perl_runops_debug))
164 /* These are baked at compile time into any shared perl library.
165 In future 5.10.x releases this will allow us in main() to sanity test the
166 library we're linking against. */
168 PERLVARI(Grevision, U8, PERL_REVISION)
169 PERLVARI(Gversion, U8, PERL_VERSION)
170 PERLVARI(Gsubversion, U8, PERL_SUBVERSION)
172 #if defined(MULTIPLICITY)
173 # define PERL_INTERPRETER_SIZE_UPTO_MEMBER(member) \
174 STRUCT_OFFSET(struct interpreter, member) + \
175 sizeof(((struct interpreter*)0)->member)
177 /* These might be useful. */
178 PERLVARI(Ginterp_size, U16, sizeof(struct interpreter))
179 #if defined(PERL_GLOBAL_STRUCT)
180 PERLVARI(Gglobal_struct_size, U16, sizeof(struct perl_vars))
183 /* This will be useful for subsequent releases, because this has to be the
184 same in your libperl as in main(), else you have a mismatch and must abort.
186 PERLVARI(Ginterp_size_5_10_0, U16,
187 PERL_INTERPRETER_SIZE_UPTO_MEMBER(PERL_LAST_5_10_0_INTERP_MEMBER))
191 =for apidoc AmUx|Perl_keyword_plugin_t|PL_keyword_plugin
193 Function pointer, pointing at a function used to handle extended keywords.
194 The function should be declared as
196 int keyword_plugin_function(pTHX_
197 char *keyword_ptr, STRLEN keyword_len,
200 The function is called from the tokeniser, whenever a possible keyword
201 is seen. C<keyword_ptr> points at the word in the parser's input
202 buffer, and C<keyword_len> gives its length; it is not null-terminated.
203 The function is expected to examine the word, and possibly other state
204 such as L<%^H|perlvar/%^H>, to decide whether it wants to handle it
205 as an extended keyword. If it does not, the function should return
206 C<KEYWORD_PLUGIN_DECLINE>, and the normal parser process will continue.
208 If the function wants to handle the keyword, it first must
209 parse anything following the keyword that is part of the syntax
210 introduced by the keyword. The lexer interface is poorly documented.
211 Broadly speaking, parsing needs to look at the buffer that extends
212 from C<PL_parser-E<gt>bufptr> to C<PL_parser-E<gt>bufend>, and
213 C<PL_parser-E<gt>bufptr> must be advanced across whatever text is
214 consumed by the parsing process. The buffer end is not necessarily the
215 real end of the input text, but refilling the buffer is too complicated
216 to discuss here. See L<Devel::Declare> for some parsing experience,
217 and hope for more core support in a future version of Perl.
219 When a keyword is being handled, the plugin function must build
220 a tree of C<OP> structures, representing the code that was parsed.
221 The root of the tree must be stored in C<*op_ptr>. The function then
222 returns a contant indicating the syntactic role of the construct that
223 it has parsed: C<KEYWORD_PLUGIN_STMT> if it is a complete statement, or
224 C<KEYWORD_PLUGIN_EXPR> if it is an expression. Note that a statement
225 construct cannot be used inside an expression (except via C<do BLOCK>
226 and similar), and an expression is not a complete statement (it requires
227 at least a terminating semicolon).
229 When a keyword is handled, the plugin function may also have
230 (compile-time) side effects. It may modify C<%^H>, define functions, and
231 so on. Typically, if side effects are the main purpose of a handler,
232 it does not wish to generate any ops to be included in the normal
233 compilation. In this case it is still required to supply an op tree,
234 but it suffices to generate a single null op.
236 That's how the C<*PL_keyword_plugin> function needs to behave overall.
237 Conventionally, however, one does not completely replace the existing
238 handler function. Instead, take a copy of C<PL_keyword_plugin> before
239 assigning your own function pointer to it. Your handler function should
240 look for keywords that it is interested in and handle those. Where it
241 is not interested, it should call the saved plugin function, passing on
242 the arguments it received. Thus C<PL_keyword_plugin> actually points
243 at a chain of handler functions, all of which have an opportunity to
244 handle keywords, and only the last function in the chain (built into
245 the Perl core) will normally return C<KEYWORD_PLUGIN_DECLINE>.
250 PERLVARI(Gkeyword_plugin, Perl_keyword_plugin_t, MEMBER_TO_FPTR(Perl_keyword_plugin_standard))