Debian Codegraph @

upstream/fedora-44/man1/perlhacktips.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLHACKTIPS 1"
61 .TH PERLHACKTIPS 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perlhacktips \- Tips for Perl core C code hacking
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 This document will help you learn the best way to go about hacking on
71 the Perl core C code. It covers common problems, debugging, profiling,
72 and more.
73 .PP
74 If you haven\*(Aqt read perlhack and perlhacktut yet, you might want
75 to do that first.
76 .SH "COMMON PROBLEMS"
77 .IX Header "COMMON PROBLEMS"
78 Perl source now permits some specific C99 features which we know are
79 supported by all platforms, but mostly plays by ANSI C89 rules. You
80 don\*(Aqt care about some particular platform having broken Perl? I hear
81 there is still a strong demand for J2EE programmers.
82 .SS "Perl environment problems"
83 .IX Subsection "Perl environment problems"
84 .IP \(bu 4
85 Not compiling with threading
86 .Sp
87 Compiling with threading (\-Duseithreads) completely rewrites the
88 function prototypes of Perl. You better try your changes with that.
89 Related to this is the difference between "Perl_\-less" and "Perl_\-ly"
90 APIs, for example:
91 .Sp
92 .Vb 2
93 \& Perl_sv_setiv(aTHX_ ...);
94 \& sv_setiv(...);
95 .Ve
96 .Sp
97 The first one explicitly passes in the context, which is needed for
98 e.g. threaded builds. The second one does that implicitly; do not get
99 them mixed. If you are not passing in a aTHX_, you will need to do a
100 dTHX as the first thing in the function.
101 .Sp
102 See "How multiple interpreters and concurrency are
103 supported" in perlguts for further discussion about context.
104 .IP \(bu 4
105 Not compiling with \-DDEBUGGING
106 .Sp
107 The DEBUGGING define exposes more code to the compiler, therefore more
108 ways for things to go wrong. You should try it.
109 .IP \(bu 4
110 Introducing (non\-read\-only) globals
111 .Sp
112 Do not introduce any modifiable globals, truly global or file static.
113 They are bad form and complicate multithreading and other forms of
114 concurrency. The right way is to introduce them as new interpreter
115 variables, see \fIintrpvar.h\fR (at the very end for binary
116 compatibility).
117 .Sp
118 Introducing read\-only (const) globals is okay, as long as you verify
119 with e.g. \f(CW\*(C`nm libperl.a|egrep \-v \*(Aq [TURtr] \*(Aq\*(C'\fR (if your \f(CW\*(C`nm\*(C'\fR has
120 BSD\-style output) that the data you added really is read\-only. (If it
121 is, it shouldn\*(Aqt show up in the output of that command.)
122 .Sp
123 If you want to have static strings, make them constant:
124 .Sp
125 .Vb 1
126 \& static const char etc[] = "...";
127 .Ve
128 .Sp
129 If you want to have arrays of constant strings, note carefully the
130 right combination of \f(CW\*(C`const\*(C'\fRs:
131 .Sp
132 .Vb 2
133 \& static const char * const yippee[] =
134 \& {"hi", "ho", "silver"};
135 .Ve
136 .IP \(bu 4
137 Not exporting your new function
138 .Sp
139 Some platforms (Win32, AIX, VMS, OS/2, to name a few) require any
140 function that is part of the public API (the shared Perl library) to be
141 explicitly marked as exported. See the discussion about \fIembed.pl\fR in
142 perlguts.
143 .IP \(bu 4
144 Exporting your new function
145 .Sp
146 The new shiny result of either genuine new functionality or your
147 arduous refactoring is now ready and correctly exported. So what could
148 possibly go wrong?
149 .Sp
150 Maybe simply that your function did not need to be exported in the
151 first place. Perl has a long and not so glorious history of exporting
152 functions that it should not have.
153 .Sp
154 If the function is used only inside one source code file, make it
155 static. See the discussion about \fIembed.pl\fR in perlguts.
156 .Sp
157 If the function is used across several files, but intended only for
158 Perl\*(Aqs internal use (and this should be the common case), do not export
159 it to the public API. See the discussion about \fIembed.pl\fR in
160 perlguts.
161 .SS C99
162 .IX Subsection "C99"
163 Starting from 5.35.5 we now permit some C99 features in the core C
164 source. However, code in dual life extensions still needs to be C89
165 only, because it needs to compile against earlier version of Perl
166 running on older platforms. Also note that our headers need to also be
167 valid as C++, because XS extensions written in C++ need to include
168 them, hence \fImember structure initialisers\fR can\*(Aqt be used in headers.
169 .PP
170 C99 support is still far from complete on all platforms we currently
171 support. As a baseline we can only assume C89 semantics with the
172 specific C99 features described below, which we\*(Aqve verified work
173 everywhere. It\*(Aqs fine to probe for additional C99 features and use
174 them where available, providing there is also a fallback for compilers
175 that don\*(Aqt support the feature. For example, we use C11 thread local
176 storage when available, but fall back to POSIX thread specific APIs
177 otherwise.
178 .PP
179 Code can use (and rely on) the following C99 features being present
180 .IP \(bu 4
181 mixed declarations and code
182 .IP \(bu 4
183 64 bit integer types
184 .Sp
185 For consistency with the existing source code, use the typedefs \f(CW\*(C`I64\*(C'\fR
186 and \f(CW\*(C`U64\*(C'\fR, instead of using \f(CW\*(C`long long\*(C'\fR and \f(CW\*(C`unsigned long long\*(C'\fR
187 directly.
188 .IP \(bu 4
189 variadic macros
190 .Sp
191 .Vb 2
192 \& void greet(char *file, unsigned int line, char *format, ...);
193 \& #define logged_greet(...) greet(_\|_FILE_\|_, _\|_LINE_\|_, _\|_VA_ARGS_\|_);
194 .Ve
195 .Sp
196 Note that \f(CW\*(C`_\|_VA_OPT_\|_\*(C'\fR is standardized as of C23 and C++20. Before
197 that it was a gcc extension.
198 .IP \(bu 4
199 declarations in for loops
200 .Sp
201 .Vb 3
202 \& for (const char *p = message; *p; ++p) {
203 \& putchar(*p);
204 \& }
205 .Ve
206 .IP \(bu 4
207 member structure initialisers
208 .Sp
209 But not in headers, as support was only added to C++ relatively
210 recently.
211 .Sp
212 Hence this is fine in C and XS code, but not headers:
213 .Sp
214 .Vb 4
215 \& struct message {
216 \& char *action;
217 \& char *target;
218 \& };
219 \&
220 \& struct message mcguffin = {
221 \& .target = "member structure initialisers",
222 \& .action = "Built"
223 \& };
224 .Ve
225 .Sp
226 You cannot use the similar syntax for compound literals, since we also
227 build perl using C++ compilers:
228 .Sp
229 .Vb 10
230 \& /* this is fine */
231 \& struct message m = {
232 \& .target = "some target",
233 \& .action = "some action"
234 \& };
235 \& /* this is not valid in C++ */
236 \& m = (struct message){
237 \& .target = "some target",
238 \& .action = "some action"
239 \& };
240 .Ve
241 .Sp
242 While structure designators are usable, the related array designators
243 are not, since they aren\*(Aqt supported by C++ at all.
244 .IP \(bu 4
245 flexible array members
246 .Sp
247 This is standards conformant:
248 .Sp
249 .Vb 4
250 \& struct greeting {
251 \& unsigned int len;
252 \& char message[];
253 \& };
254 .Ve
255 .Sp
256 However, the source code already uses the "unwarranted chumminess with
257 the compiler" hack in many places:
258 .Sp
259 .Vb 4
260 \& struct greeting {
261 \& unsigned int len;
262 \& char message[1];
263 \& };
264 .Ve
265 .Sp
266 Strictly it \fBis\fR undefined behaviour accessing beyond \f(CW\*(C`message[0]\*(C'\fR,
267 but this has been a commonly used hack since K&R times, and using it
268 hasn\*(Aqt been a practical issue anywhere (in the perl source or any other
269 common C code). Hence it\*(Aqs unclear what we would gain from actively
270 changing to the C99 approach.
271 .IP \(bu 4
272 \&\f(CW\*(C`//\*(C'\fR comments
273 .Sp
274 All compilers we tested support their use. Not all humans we tested
275 support their use.
276 .IP \(bu 4
277 booleans
278 .Sp
279 You can use \f(CW\*(C`bool\*(C'\fR, \f(CW\*(C`true\*(C'\fR, and \f(CW\*(C`false\*(C'\fR as provided by \f(CW\*(C`<stdbool.h>\*(C'\fR
280 (or natively in C++).
281 .PP
282 Code explicitly should not use any other C99 features. For example
283 .IP \(bu 4
284 variable length arrays
285 .Sp
286 Not supported by \fBany\fR MSVC, and this is not going to change.
287 .Sp
288 Even "variable" length arrays where the variable is a constant
289 expression are syntax errors under MSVC.
290 .IP \(bu 4
291 C99 types in \f(CW\*(C`<stdint.h>\*(C'\fR
292 .Sp
293 Use \f(CW\*(C`PERL_INT_FAST8_T\*(C'\fR etc as defined in \fIhandy.h\fR
294 .IP \(bu 4
295 C99 format strings in \f(CW\*(C`<inttypes.h>\*(C'\fR
296 .Sp
297 \&\f(CW\*(C`snprintf\*(C'\fR in the VMS libc only added support for \f(CW\*(C`PRIdN\*(C'\fR etc very
298 recently, meaning that there are live supported installations without
299 this, or formats such as \f(CW%zu\fR.
300 .Sp
301 (perl\*(Aqs \f(CW\*(C`sv_catpvf\*(C'\fR etc use parser code in \fIsv.c\fR, which
302 supports the \f(CW\*(C`z\*(C'\fR modifier, along with perl\-specific formats such as
303 \&\f(CW\*(C`SVf\*(C'\fR.)
304 .PP
305 If you want to use a C99 feature not listed above then you need to do
306 one of
307 .IP \(bu 4
308 Probe for it in \fIConfigure\fR, set a variable in \fIconfig.sh\fR, and add
309 fallback logic in the headers for platforms which don\*(Aqt have it.
310 .IP \(bu 4
311 Write test code and verify that it works on platforms we need to
312 support, before relying on it unconditionally.
313 .PP
314 Likely you want to repeat the same plan as we used to get the current
315 C99 feature set. See the message at
316 <https://markmail.org/thread/odr4fjrn72u2fkpz> for the C99 probes we
317 used before. Note that the two most "fussy" compilers appear to be MSVC
318 and the vendor compiler on VMS. To date all the *nix compilers have
319 been far more flexible in what they support.
320 .PP
321 On *nix platforms, \fIConfigure\fR attempts to set compiler flags
322 appropriately. All vendor compilers that we tested defaulted to C99 (or
323 C11) support. However, older versions of gcc default to C89, or permit
324 \&\fImost\fR C99 (with warnings), but forbid \fIdeclarations in for loops\fR
325 unless \f(CW\*(C`\-std=gnu99\*(C'\fR is added. The alternative \f(CW\*(C`\-std=c99\*(C'\fR \fBmight\fR
326 seem better, but using it on some platforms can prevent \f(CW\*(C`<unistd.h>\*(C'\fR declaring some prototypes being declared, which breaks the build.
327 gcc\*(Aqs \f(CW\*(C`\-ansi\*(C'\fR flag implies \f(CW\*(C`\-std=c89\*(C'\fR so we can no longer set that,
328 hence the Configure option \f(CW\*(C`\-gccansipedantic\*(C'\fR now only adds
329 \&\f(CW\*(C`\-pedantic\*(C'\fR.
330 .PP
331 The Perl core source code files (the ones at the top level of the
332 source code distribution) are automatically compiled with as many as
333 possible of the \f(CW\*(C`\-std=gnu99\*(C'\fR, \f(CW\*(C`\-pedantic\*(C'\fR, and a selection of \f(CW\*(C`\-W\*(C'\fR
334 flags (see cflags.SH). Files in \fIext/\fR \fIdist/\fR \fIcpan/\fR etc are
335 compiled with the same flags as the installed perl would use to compile
336 XS extensions.
337 .PP
338 Basically, it\*(Aqs safe to assume that \fIConfigure\fR and \fIcflags.SH\fR have
339 picked the best combination of flags for the version of gcc on the
340 platform, and attempting to add more flags related to enforcing a C
341 dialect will cause problems either locally, or on other systems that
342 the code is shipped to.
343 .PP
344 We believe that the C99 support in gcc 3.1 is good enough for us, but
345 we don\*(Aqt have a 19 year old gcc handy to check this :\-) If you have
346 ancient vendor compilers that don\*(Aqt default to C99, the flags you might
347 want to try are
348 .IP AIX 4
349 .IX Item "AIX"
350 \&\f(CW\*(C`\-qlanglvl=stdc99\*(C'\fR
351 .IP HP/UX 4
352 .IX Item "HP/UX"
353 \&\f(CW\*(C`\-AC99\*(C'\fR
354 .IP Solaris 4
355 .IX Item "Solaris"
356 \&\f(CW\*(C`\-xc99\*(C'\fR
357 .SS "Symbol Names and Namespace Pollution"
358 .IX Subsection "Symbol Names and Namespace Pollution"
359 \fIChoosing legal symbol names\fR
360 .IX Subsection "Choosing legal symbol names"
361 .PP
362 C reserves for its implementation any symbol whose name begins with an
363 underscore followed immediately by either an uppercase letter \f(CW\*(C`[A\-Z]\*(C'\fR
364 or another underscore. C++ further reserves any symbol containing two
365 consecutive underscores, and further reserves in the global name space
366 any symbol beginning with an underscore, not just ones followed by a
367 capital. We care about C++ because header files (\fI*.h\fR) need to be
368 compilable by it, and some people do all their development using a C++
369 compiler.
370 .PP
371 The consequences of failing to do this are probably none. Unless you
372 stumble on a name that the implementation uses, things will work.
373 Indeed, the perl core has more than a few instances of using
374 implementation\-reserved symbols. (These are gradually being changed.)
375 But your code might stop working any time that the implementation
376 decides to use a name you already had chosen, potentially many years
377 before.
378 .PP
379 It\*(Aqs best then to:
380 .ie n .IP "\fBDon\*(Aqt begin a file\-level symbol name with an underscore\fR; (\fIe.g.\fR, don\*(Aqt use: ""_FOOBAR"")" 4
381 .el .IP "\fBDon\*(Aqt begin a file\-level symbol name with an underscore\fR; (\fIe.g.\fR, don\*(Aqt use: \f(CW_FOOBAR\fR)" 4
382 .IX Item "Don't begin a file-level symbol name with an underscore; (e.g., don't use: _FOOBAR)"
383 It is fine to have a symbol in a function or block like \f(CW\*(C`_ref\*(C'\fR,
384 beginning with an underscore followed by a lowercase letter.
385 .ie n .IP "\fBDon\*(Aqt use two consecutive underscores in a symbol name\fR; (\fIe.g.\fR, don\*(Aqt use ""FOO_\|_BAR"")" 4
386 .el .IP "\fBDon\*(Aqt use two consecutive underscores in a symbol name\fR; (\fIe.g.\fR, don\*(Aqt use \f(CWFOO_\|_BAR\fR)" 4
387 .IX Item "Don't use two consecutive underscores in a symbol name; (e.g., don't use FOO__BAR)"
388 .PP
389 POSIX also reserves many symbols. See Section 2.2.2 in
390 <https://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html>.
391 Perl also has conflicts with that.
392 .PP
393 Perl reserves for its use any symbol beginning with \f(CW\*(C`Perl\*(C'\fR, \f(CW\*(C`perl\*(C'\fR,
394 or \f(CW\*(C`PL_\*(C'\fR. Any time you introduce a macro into a header file that
395 doesn\*(Aqt follow that convention, you are creating the possibility of a
396 namespace clash with an existing XS module, unless you restrict it by,
397 say,
398 .PP
399 .Vb 3
400 \& #ifdef PERL_CORE
401 \& # define my_symbol
402 \& #endif
403 .Ve
404 .PP
405 There are many symbols in header files that aren\*(Aqt of this form, and
406 which are accessible from XS namespace, intentionally or not, just
407 about anything in \fIconfig.h\fR, for example.
408 .PP
409 Having to use one of these prefixes detracts from the readability of
410 the code, and hasn\*(Aqt been an actual issue for non\-trivial names. Things
411 like perl defining its own \f(CW\*(C`MAX\*(C'\fR macro have been problematic, but they
412 were quickly discovered, and a \f(CW\*(C`#ifdef\ PERL_CORE\*(C'\fR guard added.
413 .PP
414 So there\*(Aqs no rule imposed about using such symbols, just be aware of
415 the issues.
416 .PP
417 \fIChoosing good symbol names\fR
418 .IX Subsection "Choosing good symbol names"
419 .PP
420 Ideally, a symbol name should correctly and precisely describe its
421 intended purpose. But there is a tension between that and getting
422 names that are overly long and hence awkward to type and read.
423 Metaphors could be helpful (a poetic name), but those tend to be
424 culturally specific, and may not translate for someone whose native
425 language isn\*(Aqt English, or even comes from a different cultural
426 background. Besides, the talent of writing poetry seems to be rare in
427 programmers.
428 .PP
429 Certain symbol names don\*(Aqt reflect their purpose, but are nonetheless
430 fine to use because of long\-standing conventions. These often
431 originated in the field of Mathematics, where \f(CW\*(C`i\*(C'\fR and \f(CW\*(C`j\*(C'\fR are
432 frequently used as subscripts, and \f(CW\*(C`n\*(C'\fR as a population count. Since
433 at least the 1950\*(Aqs, computer programs have used \f(CW\*(C`i\*(C'\fR, \fIetc.\fR as loop
434 variables.
435 .PP
436 Our guidance is to choose a name that reasonably describes the purpose,
437 and to comment its declaration more precisely.
438 .PP
439 One certainly shouldn\*(Aqt use misleading nor ambiguous names. \f(CW\*(C`last_foo\*(C'\fR
440 could mean either the final \f(CW\*(C`foo\*(C'\fR or the previous \f(CW\*(C`foo\*(C'\fR, and so could
441 be confusing to the reader, or even to the writer coming back to the
442 code after a few months of working on something else. Sometimes the
443 programmer has a particular line of thought in mind, and it doesn\*(Aqt
444 occur to them that ambiguity is present.
445 .PP
446 There are probably still many off\-by\-1 bugs around because the name
447 "\f(CW\*(C`av_len\*(C'\fR" in perlapi doesn\*(Aqt correspond to what other \fI\-len\fR
448 constructs mean, such as "\f(CW\*(C`sv_len\*(C'\fR" in perlapi. Awkward (and
449 controversial) synonyms were created to use instead that conveyed its
450 true meaning ("\f(CW\*(C`av_top_index\*(C'\fR" in perlapi). Eventually, though, someone
451 had the better idea to create a new name to signify what most people
452 think \f(CW\*(C`\-len\*(C'\fR signifies. So "\f(CW\*(C`av_count\*(C'\fR" in perlapi was born. And we
453 wish it had been thought up much earlier.
454 .SS "Writing safer macros"
455 .IX Subsection "Writing safer macros"
456 Macros are used extensively in the Perl core for such things as hiding
457 internal details from the caller, so that it doesn\*(Aqt have to be
458 concerned about them. For example, most lines of code don\*(Aqt need to
459 know if they are running on a threaded versus unthreaded perl. That
460 detail is automatically mostly hidden.
461 .PP
462 It is often better to use an inline function instead of a macro. They
463 are immune to name collisions with the caller, and don\*(Aqt magnify
464 problems when called with parameters that are expressions with side
465 effects. There was a time when one might choose a macro over an inline
466 function because compiler support for inline functions was quite
467 limited. Some only would actually only inline the first two or three
468 encountered in a compilation. But those days are long gone, and inline
469 functions are fully supported in modern compilers.
470 .PP
471 Nevertheless, there are situations where a function won\*(Aqt do, and a
472 macro is required. One example is when a parameter can be any of
473 several types. A function has to be declared with a single explicit
474 parameter type, so a macro may be called for.
475 .PP
476 Or maybe the code involved is so trivial that a function would be just
477 complicating overkill, such as when the macro simply creates a mnemonic
478 name for some constant value.
479 .PP
480 If you do choose to use a non\-trivial macro, be aware that there are
481 several avoidable pitfalls that can occur. Keep in mind that a macro
482 is expanded within the lexical context of each place in the source it
483 is called. If you have a token \f(CW\*(C`foo\*(C'\fR in the macro and the source
484 happens also to have \f(CW\*(C`foo\*(C'\fR, the meaning of the macro\*(Aqs \f(CW\*(C`foo\*(C'\fR will
485 become that of the caller\*(Aqs. Sometimes that is exactly the behavior
486 you want, but be aware that this tends to be confusing later on. It
487 effectively turns \f(CW\*(C`foo\*(C'\fR into a reserved word for any code that calls
488 the macro, and this fact is usually not documented nor considered. It
489 is safer to pass \f(CW\*(C`foo\*(C'\fR as a parameter, so that \f(CW\*(C`foo\*(C'\fR remains freely
490 available to the caller and the macro interface is explicitly
491 specified.
492 .PP
493 Worse is when the equivalence between the two \f(CW\*(C`foo\*(C'\fR\*(Aqs is coincidental.
494 Suppose for example, that the macro declares a variable
495 .PP
496 .Vb 1
497 \& int foo
498 .Ve
499 .PP
500 That works fine as long as the caller doesn\*(Aqt define the string \f(CW\*(C`foo\*(C'\fR
501 in some way. And it might not be until years later that someone comes
502 along with an instance where \f(CW\*(C`foo\*(C'\fR is used. For example a future
503 caller could do this:
504 .PP
505 .Vb 1
506 \& #define foo bar
507 .Ve
508 .PP
509 Then that declaration of \f(CW\*(C`foo\*(C'\fR in the macro suddenly becomes
510 .PP
511 .Vb 1
512 \& int bar
513 .Ve
514 .PP
515 That could mean that something completely different happens than
516 intended. It is hard to debug; the macro and call may not even be in
517 the same file, so it would require some digging and gnashing of teeth
518 to figure out.
519 .PP
520 Therefore, if a macro does use variables, their names should be such
521 that it is very unlikely that they would collide with any caller, now
522 or forever. One way to do that, now being used in the perl source, is
523 to include the name of the macro itself as part of the name of each
524 variable in the macro. Suppose the macro is named \f(CW\*(C`SvPV\*(C'\fR Then we
525 could have
526 .PP
527 .Vb 1
528 \& int foo_svpv_ = 0;
529 .Ve
530 .PP
531 This is harder to read than plain \f(CW\*(C`foo\*(C'\fR, but it is pretty much
532 guaranteed that a caller will never naively use \f(CW\*(C`foo_svpv_\*(C'\fR (and run
533 into problems). (The lowercasing makes it clearer that this is a
534 variable, but assumes that there won\*(Aqt be two elements whose names
535 differ only in the case of their letters.) The trailing underscore
536 makes it even more unlikely to clash, as those, by convention, signify
537 a private variable name. (See "Choosing legal symbol names" for
538 restrictions on what names you can use.)
539 .PP
540 This kind of name collision doesn\*(Aqt happen with the macro\*(Aqs formal
541 parameters, so they don\*(Aqt need to have complicated names. But there
542 are pitfalls when a parameter is an expression, or has some Perl
543 magic attached. When calling a function, C will evaluate the parameter
544 once, and pass the result to the function. But when calling a macro,
545 the parameter is copied as\-is by the C preprocessor to each instance
546 inside the macro. This means that when evaluating a parameter having
547 side effects, the function and macro results differ. This is
548 particularly fraught when a parameter has overload magic, say it is a
549 tied variable that reads the next line in a file upon each evaluation.
550 Having it read multiple lines per call is probably not what the caller
551 intended. If a macro refers to a potentially overloadable parameter
552 more than once, it should first make a copy and then use that copy the
553 rest of the time. There are macros in the perl core that violate this,
554 but are gradually being converted, usually by changing to use inline
555 functions instead.
556 .PP
557 Above we said "first make a copy". In a macro, that is easier said
558 than done, because macros are normally expressions, and declarations
559 aren\*(Aqt allowed in expressions. But the \f(CW\*(C`STMT_START\*(C'\fR\ ..\ \f(CW\*(C`STMT_END\*(C'\fR
560 construct, described in perlapi, allows you to
561 have declarations in most contexts, as long as you don\*(Aqt need a return
562 value. If you do need a value returned, you can make the interface
563 such that a pointer is passed to the construct, which then stores its
564 result there. (Or you can use GCC brace groups. But these require a
565 fallback if the code will ever get executed on a platform that lacks
566 this non\-standard extension to C. And that fallback would be another
567 code path, which can get out\-of\-sync with the brace group one, so doing
568 this isn\*(Aqt advisable.) In situations where there\*(Aqs no other way, Perl
569 does furnish "\f(CW\*(C`PL_Sv\*(C'\fR" in perlintern and "\f(CW\*(C`PL_na\*(C'\fR" in perlapi to use
570 (with a slight performance penalty) for some such common cases. But
571 beware that a call chain involving multiple macros using them will zap
572 the other\*(Aqs use. These have been very difficult to debug.
573 .PP
574 For a concrete example of these pitfalls in action, see
575 <https://perlmonks.org/?node_id=11144355>.
576 .SS "Portability problems"
577 .IX Subsection "Portability problems"
578 The following are common causes of compilation and/or execution
579 failures, not specific to Perl as such. The C FAQ is good bedtime
580 reading. Please test your changes with as many C compilers and
581 platforms as possible; we will, anyway, and it\*(Aqs nice to save oneself
582 from public embarrassment.
583 .PP
584 Also study perlport carefully to avoid any bad assumptions about the
585 operating system, filesystems, character set, and so forth.
586 .PP
587 Do not assume an operating system indicates a certain compiler.
588 .IP \(bu 4
589 Casting pointers to integers or casting integers to pointers
590 .Sp
591 .Vb 3
592 \& void castaway(U8* p)
593 \& {
594 \& IV i = p;
595 .Ve
596 .Sp
597 or
598 .Sp
599 .Vb 3
600 \& void castaway(U8* p)
601 \& {
602 \& IV i = (IV)p;
603 .Ve
604 .Sp
605 Both are bad, and broken, and unportable. Use the \fBPTR2IV()\fR macro that
606 does it right. (Likewise, there are \fBPTR2UV()\fR, \fBPTR2NV()\fR, \fBINT2PTR()\fR, and
607 \&\fBNUM2PTR()\fR.)
608 .IP \(bu 4
609 Casting between function pointers and data pointers
610 .Sp
611 Technically speaking casting between function pointers and data
612 pointers is unportable and undefined, but practically speaking it seems
613 to work, but you should use the \fBFPTR2DPTR()\fR and \fBDPTR2FPTR()\fR macros.
614 Sometimes you can also play games with unions.
615 .IP \(bu 4
616 Assuming \f(CW\*(C`sizeof(int) == sizeof(long)\*(C'\fR
617 .Sp
618 There are platforms where longs are 64 bits, and platforms where ints
619 are 64 bits, and while we are out to shock you, even platforms where
620 shorts are 64 bits. This is all legal according to the C standard. (In
621 other words, \f(CW\*(C`long long\*(C'\fR is not a portable way to specify 64 bits, and
622 \&\f(CW\*(C`long long\*(C'\fR is not even guaranteed to be any wider than \f(CW\*(C`long\*(C'\fR.)
623 .Sp
624 Instead, use the definitions \f(CW\*(C`IV\*(C'\fR, \f(CW\*(C`UV\*(C'\fR, \f(CW\*(C`IVSIZE\*(C'\fR, \f(CW\*(C`I32SIZE\*(C'\fR, and
625 so forth. Avoid things like \f(CW\*(C`I32\*(C'\fR because they are \fBnot\fR guaranteed
626 to be \fIexactly\fR 32 bits (they are \fIat least\fR 32 bits), nor are they
627 guaranteed to be \f(CW\*(C`int\*(C'\fR or \f(CW\*(C`long\*(C'\fR. If you explicitly need 64\-bit
628 variables, use \f(CW\*(C`I64\*(C'\fR and \f(CW\*(C`U64\*(C'\fR.
629 .IP \(bu 4
630 Assuming one can dereference any type of pointer for any type of data
631 .Sp
632 .Vb 2
633 \& char *p = ...;
634 \& long pony = *(long *)p; /* BAD */
635 .Ve
636 .Sp
637 Many platforms, quite rightly so, will give you a core dump instead of
638 a pony if the p happens not to be correctly aligned.
639 .IP \(bu 4
640 Lvalue casts
641 .Sp
642 .Vb 1
643 \& (int)*p = ...; /* BAD */
644 .Ve
645 .Sp
646 Simply not portable. Get your lvalue to be of the right type, or maybe
647 use temporary variables, or dirty tricks with unions.
648 .IP \(bu 4
649 Assume \fBanything\fR about structs (especially the ones you don\*(Aqt
650 control, like the ones coming from the system headers)
651 .RS 4
652 .IP \(bu 8
653 That a certain field exists in a struct
654 .IP \(bu 8
655 That no other fields exist besides the ones you know of
656 .IP \(bu 8
657 That a field is of certain signedness, sizeof, or type
658 .IP \(bu 8
659 That the fields are in a certain order
660 .RS 8
661 .IP \(bu 8
662 While C guarantees the ordering specified in the struct definition,
663 between different platforms the definitions might differ
664 .RE
665 .RS 8
666 .RE
667 .IP \(bu 8
668 That the \f(CWsizeof(struct)\fR or the alignments are the same everywhere
669 .RS 8
670 .IP \(bu 8
671 There might be padding bytes between the fields to align the fields \-
672 the bytes can be anything
673 .IP \(bu 8
674 Structs are required to be aligned to the maximum alignment required by
675 the fields \- which for native types is usually equivalent to
676 \&\f(CWsizeof(the_field)\fR.
677 .RE
678 .RS 8
679 .RE
680 .RE
681 .RS 4
682 .RE
683 .IP \(bu 4
684 Assuming the character set is ASCIIish
685 .Sp
686 Perl can compile and run under EBCDIC platforms. See perlebcdic.
687 This is transparent for the most part, but because the character sets
688 differ, you shouldn\*(Aqt use numeric (decimal, octal, nor hex) constants
689 to refer to characters. You can safely say \f(CW\*(AqA\*(Aq\fR, but not \f(CW0x41\fR.
690 You can safely say \f(CW\*(Aq\en\*(Aq\fR, but not \f(CW\*(C`\e012\*(C'\fR. However, you can use
691 macros defined in \fIutf8.h\fR to specify any code point portably.
692 \&\f(CWLATIN1_TO_NATIVE(0xDF)\fR is going to be the code point that means
693 LATIN SMALL LETTER SHARP S on whatever platform you are running on (on
694 ASCII platforms it compiles without adding any extra code, so there is
695 zero performance hit on those). The acceptable inputs to
696 \&\f(CW\*(C`LATIN1_TO_NATIVE\*(C'\fR are from \f(CW0x00\fR through \f(CW0xFF\fR. If your input
697 isn\*(Aqt guaranteed to be in that range, use \f(CW\*(C`UNICODE_TO_NATIVE\*(C'\fR instead.
698 \&\f(CW\*(C`NATIVE_TO_LATIN1\*(C'\fR and \f(CW\*(C`NATIVE_TO_UNICODE\*(C'\fR translate the opposite
699 direction.
700 .Sp
701 If you need the string representation of a character that doesn\*(Aqt have
702 a mnemonic name in C, you should add it to the list in
703 \&\fIregen/unicode_constants.pl\fR, and have Perl create \f(CW\*(C`#define\*(C'\fR\*(Aqs for
704 you, based on the current platform.
705 .Sp
706 Note that the \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW\*(C'\fR and \f(CW\*(C`to\fR\f(CIFOO\fR\f(CW\*(C'\fR macros in \fIhandy.h\fR work
707 properly on native code points and strings.
708 .Sp
709 Also, the range \*(AqA\*(Aq \- \*(AqZ\*(Aq in ASCII is an unbroken sequence of 26 upper
710 case alphabetic characters. That is not true in EBCDIC. Nor for \*(Aqa\*(Aq
711 to \*(Aqz\*(Aq. But \*(Aq0\*(Aq \- \*(Aq9\*(Aq is an unbroken range in both systems. Don\*(Aqt
712 assume anything about other ranges. (Note that special handling of
713 ranges in regular expression patterns and transliterations makes it
714 appear to Perl code that the aforementioned ranges are all unbroken.)
715 .Sp
716 Many of the comments in the existing code ignore the possibility of
717 EBCDIC, and may be wrong therefore, even if the code works. This is
718 actually a tribute to the successful transparent insertion of being
719 able to handle EBCDIC without having to change pre\-existing code.
720 .Sp
721 UTF\-8 and UTF\-EBCDIC are two different encodings used to represent
722 Unicode code points as sequences of bytes. Macros with the same names
723 (but different definitions) in \fIutf8.h\fR and \fIutfebcdic.h\fR are used to
724 allow the calling code to think that there is only one such encoding.
725 This is almost always referred to as \f(CW\*(C`utf8\*(C'\fR, but it means the EBCDIC
726 version as well. Again, comments in the code may well be wrong even if
727 the code itself is right. For example, the concept of UTF\-8
728 \&\f(CW\*(C`invariant characters\*(C'\fR differs between ASCII and EBCDIC. On ASCII
729 platforms, only characters that do not have the high\-order bit set
730 (i.e. whose ordinals are strict ASCII, 0 \- 127) are invariant, and the
731 documentation and comments in the code may assume that, often referring
732 to something like, say, \f(CW\*(C`hibit\*(C'\fR. The situation differs and is not so
733 simple on EBCDIC machines, but as long as the code itself uses the
734 \&\f(CWNATIVE_IS_INVARIANT()\fR macro appropriately, it works, even if the
735 comments are wrong.
736 .Sp
737 As noted in "TESTING" in perlhack, when writing test scripts, the file
738 \&\fIt/charset_tools.pl\fR contains some helpful functions for writing tests
739 valid on both ASCII and EBCDIC platforms. Sometimes, though, a test
740 can\*(Aqt use a function and it\*(Aqs inconvenient to have different test
741 versions depending on the platform. There are 20 code points that are
742 the same in all 4 character sets currently recognized by Perl (the 3
743 EBCDIC code pages plus ISO 8859\-1 (ASCII/Latin1)). These can be used
744 in such tests, though there is a small possibility that Perl will
745 become available in yet another character set, breaking your test. All
746 but one of these code points are C0 control characters. The most
747 significant controls that are the same are \f(CW\*(C`\e0\*(C'\fR, \f(CW\*(C`\er\*(C'\fR, and \f(CW\*(C`\eN{VT}\*(C'\fR
748 (also specifiable as \f(CW\*(C`\ecK\*(C'\fR, \f(CW\*(C`\ex0B\*(C'\fR, \f(CW\*(C`\eN{U+0B}\*(C'\fR, or \f(CW\*(C`\e013\*(C'\fR). The
749 single non\-control is U+00B6 PILCROW SIGN. The controls that are the
750 same have the same bit pattern in all 4 character sets, regardless of
751 the UTF8ness of the string containing them. The bit pattern for U+B6
752 is the same in all 4 for non\-UTF8 strings, but differs in each when its
753 containing string is UTF\-8 encoded. The only other code points that
754 have some sort of sameness across all 4 character sets are the pair
755 0xDC and 0xFC. Together these represent upper\- and lowercase LATIN
756 LETTER U WITH DIAERESIS, but which is upper and which is lower may be
757 reversed: 0xDC is the capital in Latin1 and 0xFC is the small letter,
758 while 0xFC is the capital in EBCDIC and 0xDC is the small one. This
759 factoid may be exploited in writing case insensitive tests that are the
760 same across all 4 character sets.
761 .IP \(bu 4
762 Assuming the character set is just ASCII
763 .Sp
764 ASCII is a 7 bit encoding, but bytes have 8 bits in them. The 128
765 extra characters have different meanings depending on the locale.
766 Absent a locale, currently these extra characters are generally
767 considered to be unassigned, and this has presented some problems. This
768 has being changed starting in 5.12 so that these characters can be
769 considered to be Latin\-1 (ISO\-8859\-1).
770 .IP \(bu 4
771 Mixing #define and #ifdef
772 .Sp
773 .Vb 6
774 \& #define BURGLE(x) ... \e
775 \& #ifdef BURGLE_OLD_STYLE /* BAD */
776 \& ... do it the old way ... \e
777 \& #else
778 \& ... do it the new way ... \e
779 \& #endif
780 .Ve
781 .Sp
782 You cannot portably "stack" cpp directives. For example in the above
783 you need two separate \fBBURGLE()\fR #defines, one for each #ifdef branch.
784 .IP \(bu 4
785 Adding non\-comment stuff after #endif or #else
786 .Sp
787 .Vb 5
788 \& #ifdef SNOSH
789 \& ...
790 \& #else !SNOSH /* BAD */
791 \& ...
792 \& #endif SNOSH /* BAD */
793 .Ve
794 .Sp
795 The #endif and #else cannot portably have anything non\-comment after
796 them. If you want to document what is going (which is a good idea
797 especially if the branches are long), use (C) comments:
798 .Sp
799 .Vb 5
800 \& #ifdef SNOSH
801 \& ...
802 \& #else /* !SNOSH */
803 \& ...
804 \& #endif /* SNOSH */
805 .Ve
806 .Sp
807 The gcc option \f(CW\*(C`\-Wendif\-labels\*(C'\fR warns about the bad variant (by
808 default on starting from Perl 5.9.4).
809 .IP \(bu 4
810 Having a comma after the last element of an enum list
811 .Sp
812 .Vb 5
813 \& enum color {
814 \& CERULEAN,
815 \& CHARTREUSE,
816 \& CINNABAR, /* BAD */
817 \& };
818 .Ve
819 .Sp
820 is not portable. Leave out the last comma.
821 .Sp
822 Also note that whether enums are implicitly morphable to ints varies
823 between compilers, you might need to (int).
824 .IP \(bu 4
825 Mixing signed char pointers with unsigned char pointers
826 .Sp
827 .Vb 4
828 \& int foo(char *s) { ... }
829 \& ...
830 \& unsigned char *t = ...; /* Or U8* t = ... */
831 \& foo(t); /* BAD */
832 .Ve
833 .Sp
834 While this is legal practice, it is certainly dubious, and downright
835 fatal in at least one platform: for example VMS cc considers this a
836 fatal error. One cause for people often making this mistake is that a
837 "naked char" and therefore dereferencing a "naked char pointer" have an
838 undefined signedness: it depends on the compiler and the flags of the
839 compiler and the underlying platform whether the result is signed or
840 unsigned. For this very same reason using a \*(Aqchar\*(Aq as an array index
841 is bad.
842 .IP \(bu 4
843 Macros that have string constants and their arguments as substrings of
844 the string constants
845 .Sp
846 .Vb 2
847 \& #define FOO(n) printf("number = %d\en", n) /* BAD */
848 \& FOO(10);
849 .Ve
850 .Sp
851 Pre\-ANSI semantics for that was equivalent to
852 .Sp
853 .Vb 1
854 \& printf("10umber = %d\e10");
855 .Ve
856 .Sp
857 which is probably not what you were expecting. Unfortunately at least
858 one reasonably common and modern C compiler does "real backward
859 compatibility" here, in AIX that is what still happens even though the
860 rest of the AIX compiler is very happily C89.
861 .IP \(bu 4
862 Using printf formats for non\-basic C types
863 .Sp
864 .Vb 2
865 \& IV i = ...;
866 \& printf("i = %d\en", i); /* BAD */
867 .Ve
868 .Sp
869 While this might by accident work in some platform (where IV happens to
870 be an \f(CW\*(C`int\*(C'\fR), in general it cannot. IV might be something larger.
871 Even worse the situation is with more specific types (defined by Perl\*(Aqs
872 configuration step in \fIconfig.h\fR):
873 .Sp
874 .Vb 2
875 \& Uid_t who = ...;
876 \& printf("who = %d\en", who); /* BAD */
877 .Ve
878 .Sp
879 The problem here is that Uid_t might be not only not \f(CW\*(C`int\*(C'\fR\-wide but it
880 might also be unsigned, in which case large uids would be printed as
881 negative values.
882 .Sp
883 There is no simple solution to this because of \fBprintf()\fR\*(Aqs limited
884 intelligence, but for many types the right format is available as with
885 either \*(Aqf\*(Aq or \*(Aq_f\*(Aq suffix, for example:
886 .Sp
887 .Vb 3
888 \& IVdf /* IV in decimal */
889 \& UVxf /* UV in hexadecimal */
890 \& U32of /* A U32 in octal */
891 \&
892 \& printf("i = %"IVdf"\en", i); /* The IVdf is a string constant. */
893 \&
894 \& Uid_t_f /* Uid_t in decimal */
895 \&
896 \& printf("who = %"Uid_t_f"\en", who);
897 .Ve
898 .Sp
899 Or you can try casting to a "wide enough" type:
900 .Sp
901 .Vb 1
902 \& printf("i = %"IVdf"\en", (IV)something_very_small_and_signed);
903 .Ve
904 .Sp
905 See "Formatted Printing of Size_t and SSize_t" in perlguts for how to
906 print those.
907 .Sp
908 Also remember that the \f(CW%p\fR format really does require a void pointer:
909 .Sp
910 .Vb 2
911 \& U8* p = ...;
912 \& printf("p = %p\en", (void*)p);
913 .Ve
914 .Sp
915 The gcc option \f(CW\*(C`\-Wformat\*(C'\fR scans for such problems.
916 .IP \(bu 4
917 Blindly passing va_list
918 .Sp
919 Not all platforms support passing va_list to further varargs (stdarg)
920 functions. The right thing to do is to copy the va_list using the
921 \&\fBPerl_va_copy()\fR if the NEED_VA_COPY is defined.
922 .IP \(bu 4
923 Using gcc statement expressions
924 .Sp
925 .Vb 1
926 \& val = ({...;...;...}); /* BAD */
927 .Ve
928 .Sp
929 While a nice extension, it\*(Aqs not portable. Historically, Perl used
930 them in macros if available to gain some extra speed (essentially as a
931 funky form of inlining), but we now support (or emulate) C99 \f(CW\*(C`static
932 inline\*(C'\fR functions, so use them instead. Declare functions as
933 \&\f(CW\*(C`PERL_STATIC_INLINE\*(C'\fR to transparently fall back to emulation where
934 needed.
935 .IP \(bu 4
936 Binding together several statements in a macro
937 .Sp
938 Use the macros \f(CW\*(C`STMT_START\*(C'\fR and \f(CW\*(C`STMT_END\*(C'\fR.
939 .Sp
940 .Vb 3
941 \& STMT_START {
942 \& ...
943 \& } STMT_END
944 .Ve
945 .Sp
946 But there can be subtle (but avoidable if you do it right) bugs
947 introduced with these; see "\f(CW\*(C`STMT_START\*(C'\fR" in perlapi for best practices
948 for their use.
949 .IP \(bu 4
950 Testing for operating systems or versions when you should be testing
951 for features
952 .Sp
953 .Vb 3
954 \& #ifdef _\|_FOONIX_\|_ /* BAD */
955 \& foo = quux();
956 \& #endif
957 .Ve
958 .Sp
959 Unless you know with 100% certainty that \fBquux()\fR is only ever available
960 for the "Foonix" operating system \fBand\fR that is available \fBand\fR
961 correctly working for \fBall\fR past, present, \fBand\fR future versions of
962 "Foonix", the above is very wrong. This is more correct (though still
963 not perfect, because the below is a compile\-time check):
964 .Sp
965 .Vb 3
966 \& #ifdef HAS_QUUX
967 \& foo = quux();
968 \& #endif
969 .Ve
970 .Sp
971 How does the HAS_QUUX become defined where it needs to be? Well, if
972 Foonix happens to be Unixy enough to be able to run the Configure
973 script, and Configure has been taught about detecting and testing
974 \&\fBquux()\fR, the HAS_QUUX will be correctly defined. In other platforms,
975 the corresponding configuration step will hopefully do the same.
976 .Sp
977 In a pinch, if you cannot wait for Configure to be educated, or if you
978 have a good hunch of where \fBquux()\fR might be available, you can
979 temporarily try the following:
980 .Sp
981 .Vb 3
982 \& #if (defined(_\|_FOONIX_\|_) || defined(_\|_BARNIX_\|_))
983 \& # define HAS_QUUX
984 \& #endif
985 \&
986 \& ...
987 \&
988 \& #ifdef HAS_QUUX
989 \& foo = quux();
990 \& #endif
991 .Ve
992 .Sp
993 But in any case, try to keep the features and operating systems
994 separate.
995 .Sp
996 A good resource on the predefined macros for various operating systems,
997 compilers, and so forth is
998 <https://sourceforge.net/p/predef/wiki/Home/>.
999 .IP \(bu 4
1000 Assuming the contents of static memory pointed to by the return values
1001 of Perl wrappers for C library functions doesn\*(Aqt change. Many C
1002 library functions return pointers to static storage that can be
1003 overwritten by subsequent calls to the same or related functions. If
1004 you handle those returns before one of those functions that share the
1005 storage gets called, this is fine, but in embedded perls, or when using
1006 threads, such a function may get called before you get a chance to
1007 handle it.
1008 .Sp
1009 "Dealing with embedded perls and threads" in perlclib contains a list of
1010 problematic functions with good advice as to how to cope with them.
1011 .SS "Problematic System Interfaces"
1012 .IX Subsection "Problematic System Interfaces"
1013 There are lots of issues with using various C library functions,
1014 including security ones. You should read perlclib which covers
1015 things in detail.
1016 .PP
1017 Remember that Perl strings are NOT the same as C strings: They may
1018 contain \f(CW\*(C`NUL\*(C'\fR characters, whereas a C string is terminated by the first
1019 \&\f(CW\*(C`NUL\*(C'\fR. That is why Perl API functions that deal with strings generally
1020 take a pointer to the first byte and either a length or a pointer to the
1021 byte just beyond the final one.
1022 .PP
1023 And this is the reason that many of the C library string handling
1024 functions should not be used. They don\*(Aqt cope with the full generality
1025 of Perl strings. It may be that your test cases don\*(Aqt have embedded
1026 \&\f(CW\*(C`NUL\*(C'\fRs, and so the tests pass, whereas there may well eventually arise
1027 real\-world cases where they fail. A lesson here is to include \f(CW\*(C`NUL\*(C'\fRs
1028 in your tests. Now it\*(Aqs fairly rare in most real world cases to get
1029 \&\f(CW\*(C`NUL\*(C'\fRs, so your code may seem to work, until one day a \f(CW\*(C`NUL\*(C'\fR comes
1030 along.
1031 .PP
1032 Here\*(Aqs an example. It used to be a common paradigm, for decades, in
1033 the perl core to use \f(CW\*(C`strchr("list",\ c)\*(C'\fR to see if the character
1034 \&\f(CW\*(C`c\*(C'\fR is any of the ones given in \f(CW"list"\fR, a double\-quote\-enclosed
1035 string of the set of characters that we are seeing if \f(CW\*(C`c\*(C'\fR is one of.
1036 As long as \f(CW\*(C`c\*(C'\fR isn\*(Aqt a \f(CW\*(C`NUL\*(C'\fR, it works. But when \f(CW\*(C`c\*(C'\fR is a \f(CW\*(C`NUL\*(C'\fR,
1037 \&\f(CW\*(C`strchr\*(C'\fR returns a pointer to the terminating \f(CW\*(C`NUL\*(C'\fR in \f(CW"list"\fR.
1038 This likely will result in a segfault or a security issue when the
1039 caller uses that end pointer as the starting point to read from.
1040 .PP
1041 A solution to this and many similar issues is to use the \f(CW\*(C`mem\*(C'\fR\fI\-foo\fR
1042 C library functions instead. In this case \f(CW\*(C`memchr\*(C'\fR can be used to see
1043 if \f(CW\*(C`c\*(C'\fR is in \f(CW"list"\fR and works even if \f(CW\*(C`c\*(C'\fR is \f(CW\*(C`NUL\*(C'\fR. These
1044 functions need an additional parameter to give the string length. In
1045 the case of literal string parameters, perl has defined macros that
1046 calculate the length for you. See "String Handling" in perlapi.
1047 .SH DEBUGGING
1048 .IX Header "DEBUGGING"
1049 You can compile a special debugging version of Perl, which allows you
1050 to use the \f(CW\*(C`\-D\*(C'\fR option of Perl to tell more about what Perl is doing.
1051 But sometimes there is no alternative than to dive in with a debugger,
1052 either to see the stack trace of a core dump (very useful in a bug
1053 report), or trying to figure out what went wrong before the core dump
1054 happened, or how did we end up having wrong or unexpected results.
1055 .SS "Poking at Perl"
1056 .IX Subsection "Poking at Perl"
1057 To really poke around with Perl, you\*(Aqll probably want to build Perl for
1058 debugging, like this:
1059 .PP
1060 .Vb 2
1061 \& ./Configure \-d \-DDEBUGGING
1062 \& make
1063 .Ve
1064 .PP
1065 \&\f(CW\*(C`\-DDEBUGGING\*(C'\fR turns on the C compiler\*(Aqs \f(CW\*(C`\-g\*(C'\fR flag to have it produce
1066 debugging information which will allow us to step through a running
1067 program, and to see in which C function we are at (without the
1068 debugging information we might see only the numerical addresses of the
1069 functions, which is not very helpful). It will also turn on the
1070 \&\f(CW\*(C`DEBUGGING\*(C'\fR compilation symbol which enables all the internal
1071 debugging code in Perl. There are a whole bunch of things you can debug
1072 with this: perlrun lists them all, and the best
1073 way to find out about them is to play about with them. The most useful
1074 options are probably
1075 .PP
1076 .Vb 5
1077 \& l Context (loop) stack processing
1078 \& s Stack snapshots (with v, displays all stacks)
1079 \& t Trace execution
1080 \& o Method and overloading resolution
1081 \& c String/numeric conversions
1082 .Ve
1083 .PP
1084 For example
1085 .PP
1086 .Vb 8
1087 \& $ perl \-Dst \-e \*(Aq$x + 1\*(Aq
1088 \& ....
1089 \& (\-e:1) gvsv(main::x)
1090 \& => UNDEF
1091 \& (\-e:1) const(IV(1))
1092 \& => UNDEF IV(1)
1093 \& (\-e:1) add
1094 \& => NV(1)
1095 .Ve
1096 .PP
1097 Some of the functionality of the debugging code can be achieved with a
1098 non\-debugging perl by using XS modules:
1099 .PP
1100 .Vb 2
1101 \& \-Dr => use re \*(Aqdebug\*(Aq
1102 \& \-Dx => use O \*(AqDebug\*(Aq
1103 .Ve
1104 .SS "Using a source\-level debugger"
1105 .IX Subsection "Using a source-level debugger"
1106 If the debugging output of \f(CW\*(C`\-D\*(C'\fR doesn\*(Aqt help you, it\*(Aqs time to step
1107 through perl\*(Aqs execution with a source\-level debugger.
1108 .IP \(bu 3
1109 We\*(Aqll use \f(CW\*(C`gdb\*(C'\fR for our examples here; the principles will apply to
1110 any debugger (many vendors call their debugger \f(CW\*(C`dbx\*(C'\fR), but check the
1111 manual of the one you\*(Aqre using.
1112 .PP
1113 To fire up the debugger, type
1114 .PP
1115 .Vb 1
1116 \& gdb ./perl
1117 .Ve
1118 .PP
1119 Or if you have a core dump:
1120 .PP
1121 .Vb 1
1122 \& gdb ./perl core
1123 .Ve
1124 .PP
1125 You\*(Aqll want to do that in your Perl source tree so the debugger can
1126 read the source code. You should see the copyright message, followed
1127 by the prompt.
1128 .PP
1129 .Vb 1
1130 \& (gdb)
1131 .Ve
1132 .PP
1133 \&\f(CW\*(C`help\*(C'\fR will get you into the documentation, but here are the most
1134 useful commands:
1135 .IP \(bu 3
1136 run [args]
1137 .Sp
1138 Run the program with the given arguments.
1139 .IP \(bu 3
1140 break function_name
1141 .IP \(bu 3
1142 break source.c:xxx
1143 .Sp
1144 Tells the debugger that we\*(Aqll want to pause execution when we reach
1145 either the named function (but see "Internal Functions" in perlguts!) or
1146 the given line in the named source file.
1147 .IP \(bu 3
1148 step
1149 .Sp
1150 Steps through the program a line at a time.
1151 .IP \(bu 3
1152 next
1153 .Sp
1154 Steps through the program a line at a time, without descending into
1155 functions.
1156 .IP \(bu 3
1157 continue
1158 .Sp
1159 Run until the next breakpoint.
1160 .IP \(bu 3
1161 finish
1162 .Sp
1163 Run until the end of the current function, then stop again.
1164 .IP \(bu 3
1165 \&\*(Aqenter\*(Aq
1166 .Sp
1167 Just pressing Enter will do the most recent operation again \- it\*(Aqs a
1168 blessing when stepping through miles of source code.
1169 .IP \(bu 3
1170 ptype
1171 .Sp
1172 Prints the C definition of the argument given.
1173 .Sp
1174 .Vb 10
1175 \& (gdb) ptype PL_op
1176 \& type = struct op {
1177 \& OP *op_next;
1178 \& OP *op_sibparent;
1179 \& OP *(*op_ppaddr)(void);
1180 \& PADOFFSET op_targ;
1181 \& unsigned int op_type : 9;
1182 \& unsigned int op_opt : 1;
1183 \& unsigned int op_slabbed : 1;
1184 \& unsigned int op_savefree : 1;
1185 \& unsigned int op_static : 1;
1186 \& unsigned int op_folded : 1;
1187 \& unsigned int op_spare : 2;
1188 \& U8 op_flags;
1189 \& U8 op_private;
1190 \& } *
1191 .Ve
1192 .IP \(bu 3
1193 print
1194 .Sp
1195 Execute the given C code and print its results. \fBWARNING\fR: Perl makes
1196 heavy use of macros, and \fIgdb\fR does not necessarily support macros
1197 (see later "gdb macro support"). You\*(Aqll have to substitute them
1198 yourself, or to invoke cpp on the source code files (see "The .i
1199 Targets") So, for instance, you can\*(Aqt say
1200 .Sp
1201 .Vb 1
1202 \& print SvPV_nolen(sv)
1203 .Ve
1204 .Sp
1205 but you have to say
1206 .Sp
1207 .Vb 1
1208 \& print Perl_sv_2pv_nolen(sv)
1209 .Ve
1210 .PP
1211 You may find it helpful to have a "macro dictionary", which you can
1212 produce by saying \f(CW\*(C`cpp \-dM perl.c | sort\*(C'\fR. Even then, \fIcpp\fR won\*(Aqt
1213 recursively apply those macros for you.
1214 .SS "gdb macro support"
1215 .IX Subsection "gdb macro support"
1216 Recent versions of \fIgdb\fR have fairly good macro support, but in order
1217 to use it you\*(Aqll need to compile perl with macro definitions included
1218 in the debugging information. Using \fIgcc\fR version 3.1, this means
1219 configuring with \f(CW\*(C`\-Doptimize=\-g3\*(C'\fR. Other compilers might use a
1220 different switch (if they support debugging macros at all).
1221 .SS "Dumping Perl Data Structures"
1222 .IX Subsection "Dumping Perl Data Structures"
1223 One way to get around this macro hell is to use the dumping functions
1224 in \fIdump.c\fR; these work a little like an internal
1225 Devel::Peek, but they also cover OPs and other
1226 structures that you can\*(Aqt get at from Perl. Let\*(Aqs take an example.
1227 We\*(Aqll use the \f(CW\*(C`$x = $y + $z\*(C'\fR we used before, but give it a bit of
1228 context: \f(CW\*(C`$y = "6XXXX"; $z = 2.3;\*(C'\fR. Where\*(Aqs a good place to stop and
1229 poke around?
1230 .PP
1231 What about \f(CW\*(C`pp_add\*(C'\fR, the function we examined earlier to implement the
1232 \&\f(CW\*(C`+\*(C'\fR operator:
1233 .PP
1234 .Vb 2
1235 \& (gdb) break Perl_pp_add
1236 \& Breakpoint 1 at 0x46249f: file pp_hot.c, line 309.
1237 .Ve
1238 .PP
1239 Notice we use \f(CW\*(C`Perl_pp_add\*(C'\fR and not \f(CW\*(C`pp_add\*(C'\fR \- see
1240 "Internal Functions" in perlguts. With the breakpoint in place, we can
1241 run our program:
1242 .PP
1243 .Vb 1
1244 \& (gdb) run \-e \*(Aq$y = "6XXXX"; $z = 2.3; $x = $y + $z\*(Aq
1245 .Ve
1246 .PP
1247 Lots of junk will go past as gdb reads in the relevant source files and
1248 libraries, and then:
1249 .PP
1250 .Vb 5
1251 \& Breakpoint 1, Perl_pp_add () at pp_hot.c:309
1252 \& 1396 dSP; dATARGET; bool useleft; SV *svl, *svr;
1253 \& (gdb) step
1254 \& 311 dPOPTOPnnrl_ul;
1255 \& (gdb)
1256 .Ve
1257 .PP
1258 We looked at this bit of code before, and we said that
1259 \&\f(CW\*(C`dPOPTOPnnrl_ul\*(C'\fR arranges for two \f(CW\*(C`NV\*(C'\fRs to be placed into \f(CW\*(C`left\*(C'\fR and
1260 \&\f(CW\*(C`right\*(C'\fR \- let\*(Aqs slightly expand it:
1261 .PP
1262 .Vb 3
1263 \& #define dPOPTOPnnrl_ul NV right = POPn; \e
1264 \& SV *leftsv = TOPs; \e
1265 \& NV left = USE_LEFT(leftsv) ? SvNV(leftsv) : 0.0
1266 .Ve
1267 .PP
1268 \&\f(CW\*(C`POPn\*(C'\fR takes the SV from the top of the stack and obtains its NV
1269 either directly (if \f(CW\*(C`SvNOK\*(C'\fR is set) or by calling the \f(CW\*(C`sv_2nv\*(C'\fR
1270 function. \f(CW\*(C`TOPs\*(C'\fR takes the next SV from the top of the stack \- yes,
1271 \&\f(CW\*(C`POPn\*(C'\fR uses \f(CW\*(C`TOPs\*(C'\fR \- but doesn\*(Aqt remove it. We then use \f(CW\*(C`SvNV\*(C'\fR to
1272 get the NV from \f(CW\*(C`leftsv\*(C'\fR in the same way as before \- yes, \f(CW\*(C`POPn\*(C'\fR uses
1273 \&\f(CW\*(C`SvNV\*(C'\fR.
1274 .PP
1275 Since we don\*(Aqt have an NV for \f(CW$y\fR, we\*(Aqll have to use \f(CW\*(C`sv_2nv\*(C'\fR to
1276 convert it. If we step again, we\*(Aqll find ourselves there:
1277 .PP
1278 .Vb 4
1279 \& (gdb) step
1280 \& Perl_sv_2nv (sv=0xa0675d0) at sv.c:1669
1281 \& 1669 if (!sv)
1282 \& (gdb)
1283 .Ve
1284 .PP
1285 We can now use \f(CW\*(C`Perl_sv_dump\*(C'\fR to investigate the SV:
1286 .PP
1287 .Vb 8
1288 \& (gdb) print Perl_sv_dump(sv)
1289 \& SV = PV(0xa057cc0) at 0xa0675d0
1290 \& REFCNT = 1
1291 \& FLAGS = (POK,pPOK)
1292 \& PV = 0xa06a510 "6XXXX"\e0
1293 \& CUR = 5
1294 \& LEN = 6
1295 \& $1 = void
1296 .Ve
1297 .PP
1298 We know we\*(Aqre going to get \f(CW6\fR from this, so let\*(Aqs finish the
1299 subroutine:
1300 .PP
1301 .Vb 4
1302 \& (gdb) finish
1303 \& Run till exit from #0 Perl_sv_2nv (sv=0xa0675d0) at sv.c:1671
1304 \& 0x462669 in Perl_pp_add () at pp_hot.c:311
1305 \& 311 dPOPTOPnnrl_ul;
1306 .Ve
1307 .PP
1308 We can also dump out this op: the current op is always stored in
1309 \&\f(CW\*(C`PL_op\*(C'\fR, and we can dump it with \f(CW\*(C`Perl_op_dump\*(C'\fR. This\*(Aqll give us
1310 similar output to CPAN module B::Debug.
1311 .PP
1312 .Vb 10
1313 \& (gdb) print Perl_op_dump(PL_op)
1314 \& {
1315 \& 13 TYPE = add ===> 14
1316 \& TARG = 1
1317 \& FLAGS = (SCALAR,KIDS)
1318 \& {
1319 \& TYPE = null ===> (12)
1320 \& (was rv2sv)
1321 \& FLAGS = (SCALAR,KIDS)
1322 \& {
1323 \& 11 TYPE = gvsv ===> 12
1324 \& FLAGS = (SCALAR)
1325 \& GV = main::b
1326 \& }
1327 \& }
1328 .Ve
1329 .PP
1330 # finish this later #
1331 .SS "Using gdb to look at specific parts of a program"
1332 .IX Subsection "Using gdb to look at specific parts of a program"
1333 With the example above, you knew to look for \f(CW\*(C`Perl_pp_add\*(C'\fR, but what
1334 if there were multiple calls to it all over the place, or you didn\*(Aqt
1335 know what the op was you were looking for?
1336 .PP
1337 One way to do this is to inject a rare call somewhere near what you\*(Aqre
1338 looking for. For example, you could add \f(CW\*(C`study\*(C'\fR before your method:
1339 .PP
1340 .Vb 1
1341 \& study;
1342 .Ve
1343 .PP
1344 And in gdb do:
1345 .PP
1346 .Vb 1
1347 \& (gdb) break Perl_pp_study
1348 .Ve
1349 .PP
1350 And then step until you hit what you\*(Aqre looking for. This works well
1351 in a loop if you want to only break at certain iterations:
1352 .PP
1353 .Vb 3
1354 \& for my $i (1..100) {
1355 \& study if $i == 50;
1356 \& }
1357 .Ve
1358 .SS "Using gdb to look at what the parser/lexer are doing"
1359 .IX Subsection "Using gdb to look at what the parser/lexer are doing"
1360 If you want to see what perl is doing when parsing/lexing your code,
1361 you can use \f(CW\*(C`BEGIN {}\*(C'\fR:
1362 .PP
1363 .Vb 3
1364 \& print "Before\en";
1365 \& BEGIN { study; }
1366 \& print "After\en";
1367 .Ve
1368 .PP
1369 And in gdb:
1370 .PP
1371 .Vb 1
1372 \& (gdb) break Perl_pp_study
1373 .Ve
1374 .PP
1375 If you want to see what the parser/lexer is doing inside of \f(CW\*(C`if\*(C'\fR
1376 blocks and the like you need to be a little trickier:
1377 .PP
1378 .Vb 1
1379 \& if ($x && $y && do { BEGIN { study } 1 } && $z) { ... }
1380 .Ve
1381 .SH "SOURCE CODE STATIC ANALYSIS"
1382 .IX Header "SOURCE CODE STATIC ANALYSIS"
1383 Various tools exist for analysing C source code \fBstatically\fR, as
1384 opposed to \fBdynamically\fR, that is, without executing the code. It is
1385 possible to detect resource leaks, undefined behaviour, type
1386 mismatches, portability problems, code paths that would cause illegal
1387 memory accesses, and other similar problems by just parsing the C code
1388 and looking at the resulting graph, what does it tell about the
1389 execution and data flows. As a matter of fact, this is exactly how C
1390 compilers know to give warnings about dubious code.
1391 .SS lint
1392 .IX Subsection "lint"
1393 The good old C code quality inspector, \f(CW\*(C`lint\*(C'\fR, is available in several
1394 platforms, but please be aware that there are several different
1395 implementations of it by different vendors, which means that the flags
1396 are not identical across different platforms.
1397 .PP
1398 There is a \f(CW\*(C`lint\*(C'\fR target in Makefile, but you may have to diddle with
1399 the flags (see above).
1400 .SS Coverity
1401 .IX Subsection "Coverity"
1402 Coverity (<https://www.coverity.com/>) is a product similar to lint and
1403 as a testbed for their product they periodically check several open
1404 source projects, and they give out accounts to open source developers
1405 to the defect databases.
1406 .PP
1407 There is Coverity setup for the perl5 project:
1408 <https://scan.coverity.com/projects/perl5>
1409 .SS "HP\-UX cadvise (Code Advisor)"
1410 .IX Subsection "HP-UX cadvise (Code Advisor)"
1411 HP has a C/C++ static analyzer product for HP\-UX caller Code Advisor.
1412 (Link not given here because the URL is horribly long and seems
1413 horribly unstable; use the search engine of your choice to find it.)
1414 The use of the \f(CW\*(C`cadvise_cc\*(C'\fR recipe with \f(CW\*(C`Configure ...
1415 \&\-Dcc=./cadvise_cc\*(C'\fR (see cadvise "User Guide") is recommended; as is the
1416 use of \f(CW\*(C`+wall\*(C'\fR.
1417 .SS "cpd (cut\-and\-paste detector)"
1418 .IX Subsection "cpd (cut-and-paste detector)"
1419 The cpd tool detects cut\-and\-paste coding. If one instance of the
1420 cut\-and\-pasted code changes, all the other spots should probably be
1421 changed, too. Therefore such code should probably be turned into a
1422 subroutine or a macro.
1423 .PP
1424 cpd (<https://docs.pmd\-code.org/latest/pmd_userdocs_cpd.html>) is part
1425 of the pmd project (<https://pmd.github.io/>). pmd was originally
1426 written for static analysis of Java code, but later the cpd part of it
1427 was extended to parse also C and C++.
1428 .PP
1429 Download the pmd\-bin\-X.Y.zip () from the SourceForge site, extract the
1430 pmd\-X.Y.jar from it, and then run that on source code thusly:
1431 .PP
1432 .Vb 2
1433 \& java \-cp pmd\-X.Y.jar net.sourceforge.pmd.cpd.CPD \e
1434 \& \-\-minimum\-tokens 100 \-\-files /some/where/src \-\-language c > cpd.txt
1435 .Ve
1436 .PP
1437 You may run into memory limits, in which case you should use the \-Xmx
1438 option:
1439 .PP
1440 .Vb 1
1441 \& java \-Xmx512M ...
1442 .Ve
1443 .SS "gcc warnings"
1444 .IX Subsection "gcc warnings"
1445 Though much can be written about the inconsistency and coverage
1446 problems of gcc warnings (like \f(CW\*(C`\-Wall\*(C'\fR not meaning "all the warnings",
1447 or some common portability problems not being covered by \f(CW\*(C`\-Wall\*(C'\fR, or
1448 \&\f(CW\*(C`\-ansi\*(C'\fR and \f(CW\*(C`\-pedantic\*(C'\fR both being a poorly defined collection of
1449 warnings, and so forth), gcc is still a useful tool in keeping our
1450 coding nose clean.
1451 .PP
1452 The \f(CW\*(C`\-Wall\*(C'\fR is by default on.
1453 .PP
1454 It would be nice for \f(CW\*(C`\-pedantic\*(C'\fR) to be on always, but unfortunately
1455 it is not safe on all platforms \- for example fatal conflicts with the
1456 system headers (Solaris being a prime example). If Configure
1457 \&\f(CW\*(C`\-Dgccansipedantic\*(C'\fR is used, the \f(CW\*(C`cflags\*(C'\fR frontend selects
1458 \&\f(CW\*(C`\-pedantic\*(C'\fR for the platforms where it is known to be safe.
1459 .PP
1460 The following extra flags are added:
1461 .IP \(bu 4
1462 \&\f(CW\*(C`\-Wendif\-labels\*(C'\fR
1463 .IP \(bu 4
1464 \&\f(CW\*(C`\-Wextra\*(C'\fR
1465 .IP \(bu 4
1466 \&\f(CW\*(C`\-Wc++\-compat\*(C'\fR
1467 .IP \(bu 4
1468 \&\f(CW\*(C`\-Wwrite\-strings\*(C'\fR
1469 .IP \(bu 4
1470 \&\f(CW\*(C`\-Werror=pointer\-arith\*(C'\fR
1471 .IP \(bu 4
1472 \&\f(CW\*(C`\-Werror=vla\*(C'\fR
1473 .PP
1474 The following flags would be nice to have but they would first need
1475 their own Augean stablemaster:
1476 .IP \(bu 4
1477 \&\f(CW\*(C`\-Wshadow\*(C'\fR
1478 .IP \(bu 4
1479 \&\f(CW\*(C`\-Wstrict\-prototypes\*(C'\fR
1480 .PP
1481 The \f(CW\*(C`\-Wtraditional\*(C'\fR is another example of the annoying tendency of gcc
1482 to bundle a lot of warnings under one switch (it would be impossible to
1483 deploy in practice because it would complain a lot) but it does contain
1484 some warnings that would be beneficial to have available on their own,
1485 such as the warning about string constants inside macros containing the
1486 macro arguments: this behaved differently pre\-ANSI than it does in
1487 ANSI, and some C compilers are still in transition, AIX being an
1488 example.
1489 .SS "Warnings of other C compilers"
1490 .IX Subsection "Warnings of other C compilers"
1491 Other C compilers (yes, there \fBare\fR other C compilers than gcc) often
1492 have their "strict ANSI" or "strict ANSI with some portability
1493 extensions" modes on, like for example the Sun Workshop has its \f(CW\*(C`\-Xa\*(C'\fR
1494 mode on (though implicitly), or the DEC (these days, HP...) has its
1495 \&\f(CW\*(C`\-std1\*(C'\fR mode on.
1496 .SH "MEMORY DEBUGGERS"
1497 .IX Header "MEMORY DEBUGGERS"
1498 \&\fBNOTE 1\fR: Running under older memory debuggers such as Purify,
1499 valgrind or Third Degree greatly slows down the execution: seconds
1500 become minutes, minutes become hours. For example as of Perl 5.8.1,
1501 the \fIext/Encode/t/Unicode.t\fR test takes extraordinarily long to
1502 complete under e.g. Purify, Third Degree, and valgrind. Under valgrind
1503 it takes more than six hours, even on a snappy computer. Said test
1504 must be doing something that is quite unfriendly for memory debuggers.
1505 If you don\*(Aqt feel like waiting, you can simply kill the perl process.
1506 Roughly valgrind slows down execution by factor 10, AddressSanitizer by
1507 factor 2.
1508 .PP
1509 \&\fBNOTE 2\fR: To minimize the number of memory leak false alarms (see
1510 "PERL_DESTRUCT_LEVEL" for more information), you have to set the
1511 environment variable \f(CW\*(C`PERL_DESTRUCT_LEVEL\*(C'\fR to 2. For example, like
1512 this:
1513 .PP
1514 .Vb 1
1515 \& env PERL_DESTRUCT_LEVEL=2 valgrind ./perl \-Ilib ...
1516 .Ve
1517 .PP
1518 \&\fBNOTE 3\fR: There are known memory leaks when there are compile\-time
1519 errors within \f(CW\*(C`eval\*(C'\fR or \f(CW\*(C`require\*(C'\fR; seeing \f(CW\*(C`S_doeval\*(C'\fR in the call
1520 stack is a good sign of these. Fixing these leaks is non\-trivial,
1521 unfortunately, but they must be fixed eventually.
1522 .PP
1523 \&\fBNOTE 4\fR: DynaLoader will not clean up after itself completely
1524 unless Perl is built with the Configure option
1525 \&\f(CW\*(C`\-Accflags=\-DDL_UNLOAD_ALL_AT_EXIT\*(C'\fR.
1526 .SS valgrind
1527 .IX Subsection "valgrind"
1528 The valgrind tool can be used to find out both memory leaks and illegal
1529 heap memory accesses. As of version 3.3.0, Valgrind only supports
1530 Linux on x86, x86\-64 and PowerPC and Darwin (OS X) on x86 and x86\-64.
1531 The special "test.valgrind" target can be used to run the tests under
1532 valgrind. Found errors and memory leaks are logged in files named
1533 \&\fItestfile.valgrind\fR and by default output is displayed inline.
1534 .PP
1535 Example usage:
1536 .PP
1537 .Vb 1
1538 \& make test.valgrind
1539 .Ve
1540 .PP
1541 Since valgrind adds significant overhead, tests will take much longer
1542 to run. The valgrind tests support being run in parallel to help with
1543 this:
1544 .PP
1545 .Vb 1
1546 \& TEST_JOBS=9 make test.valgrind
1547 .Ve
1548 .PP
1549 Note that the above two invocations will be very verbose as reachable
1550 memory and leak\-checking is enabled by default. If you want to just
1551 see pure errors, try:
1552 .PP
1553 .Vb 2
1554 \& VG_OPTS=\*(Aq\-q \-\-leak\-check=no \-\-show\-reachable=no\*(Aq TEST_JOBS=9 \e
1555 \& make test.valgrind
1556 .Ve
1557 .PP
1558 Valgrind also provides a cachegrind tool, invoked on perl as:
1559 .PP
1560 .Vb 1
1561 \& VG_OPTS=\-\-tool=cachegrind make test.valgrind
1562 .Ve
1563 .PP
1564 As system libraries (most notably glibc) are also triggering errors,
1565 valgrind allows to suppress such errors using suppression files. The
1566 default suppression file that comes with valgrind already catches a lot
1567 of them. Some additional suppressions are defined in \fIt/perl.supp\fR.
1568 .PP
1569 To get valgrind and for more information see <https://valgrind.org/>.
1570 .SS AddressSanitizer
1571 .IX Subsection "AddressSanitizer"
1572 AddressSanitizer ("ASan") consists of a compiler instrumentation module
1573 and a run\-time \f(CW\*(C`malloc\*(C'\fR library. ASan is available for a variety of
1574 architectures, operating systems, and compilers (see project link
1575 below). It checks for unsafe memory usage, such as use after free and
1576 buffer overflow conditions, and is fast enough that you can easily
1577 compile your debugging or optimized perl with it. Modern versions of
1578 ASan check for memory leaks by default on most platforms, otherwise
1579 (e.g. x86_64 OS X) this feature can be enabled via
1580 \&\f(CW\*(C`ASAN_OPTIONS=detect_leaks=1\*(C'\fR.
1581 .PP
1582 To build perl with AddressSanitizer, your Configure invocation should
1583 look like:
1584 .PP
1585 .Vb 4
1586 \& sh Configure \-des \-Dcc=clang \e
1587 \& \-Accflags=\-fsanitize=address \-Aldflags=\-fsanitize=address \e
1588 \& \-Alddlflags=\-shared\e \-fsanitize=address \e
1589 \& \-fsanitize\-blacklist=\`pwd\`/asan_ignore
1590 .Ve
1591 .PP
1592 where these arguments mean:
1593 .IP \(bu 4
1594 \&\-Dcc=clang
1595 .Sp
1596 This should be replaced by the full path to your clang executable if it
1597 is not in your path.
1598 .IP \(bu 4
1599 \&\-Accflags=\-fsanitize=address
1600 .Sp
1601 Compile perl and extensions sources with AddressSanitizer.
1602 .IP \(bu 4
1603 \&\-Aldflags=\-fsanitize=address
1604 .Sp
1605 Link the perl executable with AddressSanitizer.
1606 .IP \(bu 4
1607 \&\-Alddlflags=\-shared\e \-fsanitize=address
1608 .Sp
1609 Link dynamic extensions with AddressSanitizer. You must manually
1610 specify \f(CW\*(C`\-shared\*(C'\fR because using \f(CW\*(C`\-Alddlflags=\-shared\*(C'\fR will prevent
1611 Configure from setting a default value for \f(CW\*(C`lddlflags\*(C'\fR, which usually
1612 contains \f(CW\*(C`\-shared\*(C'\fR (at least on Linux).
1613 .IP \(bu 4
1614 \&\-fsanitize\-blacklist=\`pwd\`/asan_ignore
1615 .Sp
1616 AddressSanitizer will ignore functions listed in the \f(CW\*(C`asan_ignore\*(C'\fR
1617 file. (This file should contain a short explanation of why each of the
1618 functions is listed.)
1619 .PP
1620 See also <https://github.com/google/sanitizers/wiki/AddressSanitizer>.
1621 .SS "Dr Memory"
1622 .IX Subsection "Dr Memory"
1623 Dr. Memory is a tool similar to valgrind which is usable on Windows
1624 and Linux.
1625 .PP
1626 It supports heap checking like \f(CW\*(C`memcheck\*(C'\fR from valgrind. There are
1627 also other tools included.
1628 .PP
1629 See <https://drmemory.org/>.
1630 .SH PROFILING
1631 .IX Header "PROFILING"
1632 Depending on your platform there are various ways of profiling Perl.
1633 .PP
1634 There are two commonly used techniques of profiling executables:
1635 \&\fIstatistical time\-sampling\fR and \fIbasic\-block counting\fR.
1636 .PP
1637 The first method takes periodically samples of the CPU program counter,
1638 and since the program counter can be correlated with the code generated
1639 for functions, we get a statistical view of in which functions the
1640 program is spending its time. The caveats are that very small/fast
1641 functions have lower probability of showing up in the profile, and that
1642 periodically interrupting the program (this is usually done rather
1643 frequently, in the scale of milliseconds) imposes an additional
1644 overhead that may skew the results. The first problem can be
1645 alleviated by running the code for longer (in general this is a good
1646 idea for profiling), the second problem is usually kept in guard by the
1647 profiling tools themselves.
1648 .PP
1649 The second method divides up the generated code into \fIbasic blocks\fR.
1650 Basic blocks are sections of code that are entered only in the
1651 beginning and exited only at the end. For example, a conditional jump
1652 starts a basic block. Basic block profiling usually works by
1653 \&\fIinstrumenting\fR the code by adding \fIenter basic block #nnnn\fR
1654 book\-keeping code to the generated code. During the execution of the
1655 code the basic block counters are then updated appropriately. The
1656 caveat is that the added extra code can skew the results: again, the
1657 profiling tools usually try to factor their own effects out of the
1658 results.
1659 .SS "Gprof Profiling"
1660 .IX Subsection "Gprof Profiling"
1661 \&\fIgprof\fR is a profiling tool available in many Unix platforms which
1662 uses \fIstatistical time\-sampling\fR. You can build a profiled version of
1663 \&\fIperl\fR by compiling using gcc with the flag \f(CW\*(C`\-pg\*(C'\fR. Either edit
1664 \&\fIconfig.sh\fR or re\-run \fIConfigure\fR. Running the profiled version of
1665 Perl will create an output file called \fIgmon.out\fR which contains the
1666 profiling data collected during the execution.
1667 .PP
1668 quick hint:
1669 .PP
1670 .Vb 6
1671 \& $ sh Configure \-des \-Dusedevel \-Accflags=\*(Aq\-pg\*(Aq \e
1672 \& \-Aldflags=\*(Aq\-pg\*(Aq \-Alddlflags=\*(Aq\-pg \-shared\*(Aq \e
1673 \& && make perl
1674 \& $ ./perl ... # creates gmon.out in current directory
1675 \& $ gprof ./perl > out
1676 \& $ less out
1677 .Ve
1678 .PP
1679 (you probably need to add \f(CW\*(C`\-shared\*(C'\fR to the <\-Alddlflags> line until RT
1680 #118199 is resolved)
1681 .PP
1682 The \fIgprof\fR tool can then display the collected data in various ways.
1683 Usually \fIgprof\fR understands the following options:
1684 .IP \(bu 4
1685 \&\-a
1686 .Sp
1687 Suppress statically defined functions from the profile.
1688 .IP \(bu 4
1689 \&\-b
1690 .Sp
1691 Suppress the verbose descriptions in the profile.
1692 .IP \(bu 4
1693 \&\-e routine
1694 .Sp
1695 Exclude the given routine and its descendants from the profile.
1696 .IP \(bu 4
1697 \&\-f routine
1698 .Sp
1699 Display only the given routine and its descendants in the profile.
1700 .IP \(bu 4
1701 \&\-s
1702 .Sp
1703 Generate a summary file called \fIgmon.sum\fR which then may be given to
1704 subsequent gprof runs to accumulate data over several runs.
1705 .IP \(bu 4
1706 \&\-z
1707 .Sp
1708 Display routines that have zero usage.
1709 .PP
1710 For more detailed explanation of the available commands and output
1711 formats, see your own local documentation of \fIgprof\fR.
1712 .SS "GCC gcov Profiling"
1713 .IX Subsection "GCC gcov Profiling"
1714 \&\fIbasic block profiling\fR is officially available in gcc 3.0 and later.
1715 You can build a profiled version of \fIperl\fR by compiling using gcc with
1716 the flags \f(CW\*(C`\-fprofile\-arcs \-ftest\-coverage\*(C'\fR. Either edit \fIconfig.sh\fR
1717 or re\-run \fIConfigure\fR.
1718 .PP
1719 quick hint:
1720 .PP
1721 .Vb 9
1722 \& $ sh Configure \-des \-Dusedevel \-Doptimize=\*(Aq\-g\*(Aq \e
1723 \& \-Accflags=\*(Aq\-fprofile\-arcs \-ftest\-coverage\*(Aq \e
1724 \& \-Aldflags=\*(Aq\-fprofile\-arcs \-ftest\-coverage\*(Aq \e
1725 \& \-Alddlflags=\*(Aq\-fprofile\-arcs \-ftest\-coverage \-shared\*(Aq \e
1726 \& && make perl
1727 \& $ rm \-f regexec.c.gcov regexec.gcda
1728 \& $ ./perl ...
1729 \& $ gcov regexec.c
1730 \& $ less regexec.c.gcov
1731 .Ve
1732 .PP
1733 (you probably need to add \f(CW\*(C`\-shared\*(C'\fR to the <\-Alddlflags> line until RT
1734 #118199 is resolved)
1735 .PP
1736 Running the profiled version of Perl will cause profile output to be
1737 generated. For each source file an accompanying \fI.gcda\fR file will be
1738 created.
1739 .PP
1740 To display the results you use the \fIgcov\fR utility (which should be
1741 installed if you have gcc 3.0 or newer installed). \fIgcov\fR is run on
1742 source code files, like this
1743 .PP
1744 .Vb 1
1745 \& gcov sv.c
1746 .Ve
1747 .PP
1748 which will cause \fIsv.c.gcov\fR to be created. The \fI.gcov\fR files
1749 contain the source code annotated with relative frequencies of
1750 execution indicated by "#" markers. If you want to generate \fI.gcov\fR
1751 files for all profiled object files, you can run something like this:
1752 .PP
1753 .Vb 3
1754 \& for file in \`find . \-name \e*.gcno\`
1755 \& do sh \-c "cd \`dirname $file\` && gcov \`basename $file .gcno\`"
1756 \& done
1757 .Ve
1758 .PP
1759 Useful options of \fIgcov\fR include \f(CW\*(C`\-b\*(C'\fR which will summarise the basic
1760 block, branch, and function call coverage, and \f(CW\*(C`\-c\*(C'\fR which instead of
1761 relative frequencies will use the actual counts. For more information
1762 on the use of \fIgcov\fR and basic block profiling with gcc, see the
1763 latest GNU CC manual. As of gcc 4.8, this is at
1764 <https://gcc.gnu.org/onlinedocs/gcc/Gcov\-Intro.html#Gcov\-Intro>.
1765 .SS "callgrind profiling"
1766 .IX Subsection "callgrind profiling"
1767 callgrind is a valgrind tool for profiling source code. Paired with
1768 kcachegrind (a Qt based UI), it gives you an overview of where code is
1769 taking up time, as well as the ability to examine callers, call trees,
1770 and more. One of its benefits is you can use it on perl and XS modules
1771 that have not been compiled with debugging symbols.
1772 .PP
1773 If perl is compiled with debugging symbols (\f(CW\*(C`\-g\*(C'\fR), you can view the
1774 annotated source and click around, much like Devel::NYTProf\*(Aqs HTML
1775 output.
1776 .PP
1777 For basic usage:
1778 .PP
1779 .Vb 1
1780 \& valgrind \-\-tool=callgrind ./perl ...
1781 .Ve
1782 .PP
1783 By default it will write output to \fIcallgrind.out.PID\fR, but you can
1784 change that with \f(CW\*(C`\-\-callgrind\-out\-file=...\*(C'\fR
1785 .PP
1786 To view the data, do:
1787 .PP
1788 .Vb 1
1789 \& kcachegrind callgrind.out.PID
1790 .Ve
1791 .PP
1792 If you\*(Aqd prefer to view the data in a terminal, you can use
1793 \&\fIcallgrind_annotate\fR. In its basic form:
1794 .PP
1795 .Vb 1
1796 \& callgrind_annotate callgrind.out.PID | less
1797 .Ve
1798 .PP
1799 Some useful options are:
1800 .IP \(bu 4
1801 \&\-\-threshold
1802 .Sp
1803 Percentage of counts (of primary sort event) we are interested in. The
1804 default is 99%, 100% might show things that seem to be missing.
1805 .IP \(bu 4
1806 \&\-\-auto
1807 .Sp
1808 Annotate all source files containing functions that helped reach the
1809 event count threshold.
1810 .ie n .SS """profiler"" profiling (Cygwin)"
1811 .el .SS "\f(CWprofiler\fP profiling (Cygwin)"
1812 .IX Subsection "profiler profiling (Cygwin)"
1813 Cygwin allows for \f(CW\*(C`gprof\*(C'\fR profiling and \f(CW\*(C`gcov\*(C'\fR coverage testing, but
1814 this only profiles the main executable.
1815 .PP
1816 You can use the \f(CW\*(C`profiler\*(C'\fR tool to perform sample based profiling, it
1817 requires no special preparation of the executables beyond debugging
1818 symbols.
1819 .PP
1820 This produces sampling data which can be processed with \f(CW\*(C`gprof\*(C'\fR.
1821 .PP
1822 There is limited
1823 documentation <https://www.cygwin.com/cygwin-ug-net/profiler.html> on
1824 the Cygwin web site.
1825 .SS "Visual Studio Profiling"
1826 .IX Subsection "Visual Studio Profiling"
1827 You can use the Visual Studio profiler to profile perl if you\*(Aqve built
1828 perl with MSVC, even though we build perl at the command\-line. You
1829 will need to build perl with \f(CW\*(C`CFG=Debug\*(C'\fR or \f(CW\*(C`CFG=DebugSymbols\*(C'\fR.
1830 .PP
1831 The Visual Studio profiler is a sampling profiler.
1832 .PP
1833 See the Visual Studio
1834 documentation <https://github.com/MicrosoftDocs/visualstudio-docs/blob/main/docs/profiling/beginners-guide-to-performance-profiling.md>
1835 to get started.
1836 .SH "MISCELLANEOUS TRICKS"
1837 .IX Header "MISCELLANEOUS TRICKS"
1838 .SS PERL_DESTRUCT_LEVEL
1839 .IX Subsection "PERL_DESTRUCT_LEVEL"
1840 If you want to run any of the tests yourself manually using e.g.
1841 valgrind, please note that by default perl \fBdoes not\fR explicitly clean
1842 up all the memory it has allocated (such as global memory arenas) but
1843 instead lets the \f(CWexit()\fR of the whole program "take care" of such
1844 allocations, also known as "global destruction of objects".
1845 .PP
1846 There is a way to tell perl to do complete cleanup: set the environment
1847 variable \f(CW\*(C`PERL_DESTRUCT_LEVEL\*(C'\fR to a non\-zero value. The \fIt/TEST\fR
1848 wrapper does set this to 2, and this is what you need to do too, if you
1849 don\*(Aqt want to see the "global leaks": For example, for running under
1850 valgrind
1851 .PP
1852 .Vb 1
1853 \& env PERL_DESTRUCT_LEVEL=2 valgrind ./perl \-Ilib t/foo/bar.t
1854 .Ve
1855 .PP
1856 (Note: the mod_perl Apache module uses this environment variable for
1857 its own purposes and extends its semantics. Refer to the mod_perl
1858 documentation <https://perl.apache.org/docs/> for more information.
1859 Also, spawned threads do the equivalent of setting this variable to the
1860 value 1.)
1861 .PP
1862 If, at the end of a run, you get the message \fIN scalars leaked\fR, you
1863 can recompile with \f(CW\*(C`\-DDEBUG_LEAKING_SCALARS\*(C'\fR (\f(CW\*(C`Configure
1864 \&\-Accflags=\-DDEBUG_LEAKING_SCALARS\*(C'\fR), which will cause the addresses of
1865 all those leaked SVs to be dumped along with details as to where each
1866 SV was originally allocated. This information is also displayed by
1867 Devel::Peek. Note that the extra details recorded with each SV
1868 increase memory usage, so it shouldn\*(Aqt be used in production
1869 environments. It also converts \f(CWnew_SV()\fR from a macro into a real
1870 function, so you can use your favourite debugger to discover where
1871 those pesky SVs were allocated.
1872 .PP
1873 If you see that you\*(Aqre leaking memory at runtime, but neither valgrind
1874 nor \f(CW\*(C`\-DDEBUG_LEAKING_SCALARS\*(C'\fR will find anything, you\*(Aqre probably
1875 leaking SVs that are still reachable and will be properly cleaned up
1876 during destruction of the interpreter. In such cases, using the \f(CW\*(C`\-Dm\*(C'\fR
1877 switch can point you to the source of the leak. If the executable was
1878 built with \f(CW\*(C`\-DDEBUG_LEAKING_SCALARS\*(C'\fR, \f(CW\*(C`\-Dm\*(C'\fR will output SV
1879 allocations in addition to memory allocations. Each SV allocation has
1880 a distinct serial number that will be written on creation and
1881 destruction of the SV. So if you\*(Aqre executing the leaking code in a
1882 loop, you need to look for SVs that are created, but never destroyed
1883 between each cycle. If such an SV is found, set a conditional
1884 breakpoint within \f(CWnew_SV()\fR and make it break only when
1885 \&\f(CW\*(C`PL_sv_serial\*(C'\fR is equal to the serial number of the leaking SV. Then
1886 you will catch the interpreter in exactly the state where the leaking
1887 SV is allocated, which is sufficient in many cases to find the source
1888 of the leak.
1889 .PP
1890 As \f(CW\*(C`\-Dm\*(C'\fR is using the PerlIO layer for output, it will by itself
1891 allocate quite a bunch of SVs, which are hidden to avoid recursion. You
1892 can bypass the PerlIO layer if you use the SV logging provided by
1893 \&\f(CW\*(C`\-DPERL_MEM_LOG\*(C'\fR instead.
1894 .SS "Leaked SV spotting: \fBsv_mark_arenas()\fP and \fBsv_sweep_arenas()\fP"
1895 .IX Subsection "Leaked SV spotting: sv_mark_arenas() and sv_sweep_arenas()"
1896 These functions exist only on \f(CW\*(C`DEBUGGING\*(C'\fR builds. The first marks all
1897 live SVs which can be found in the SV arenas with the \f(CW\*(C`SVf_BREAK\*(C'\fR flag.
1898 The second lists any such SVs which don\*(Aqt have the flag set, and resets
1899 the flag on the rest. They are intended to identify SVs which are being
1900 created, but not freed, between two points in code. They can be used
1901 either by temporarily adding calls to them in the relevant places in the
1902 code, or by calling them directly from a debugger.
1903 .PP
1904 For example, suppose the following code was found to be leaking:
1905 .PP
1906 .Vb 1
1907 \& while (1) { eval \*(Aq\e(1..3)\*(Aq }
1908 .Ve
1909 .PP
1910 A \fIgdb\fR session on a threaded perl might look something like this:
1911 .PP
1912 .Vb 10
1913 \& $ gdb ./perl
1914 \& (gdb) break Perl_pp_entereval
1915 \& (gdb) run \-e\*(Aqwhile (1) { eval q{\e(1..3)} }\*(Aq
1916 \& ...
1917 \& Breakpoint 1, Perl_pp_entereval ....
1918 \& (gdb) call Perl_sv_mark_arenas(my_perl)
1919 \& (gdb) continue
1920 \& ...
1921 \& Breakpoint 1, Perl_pp_entereval ....\`
1922 \& (gdb) call Perl_sv_sweep_arenas(my_perl)
1923 \& Unmarked SV: 0xaf23a8: AV()
1924 \& Unmarked SV: 0xaf2408: IV(1)
1925 \& Unmarked SV: 0xaf2468: IV(2)
1926 \& Unmarked SV: 0xaf24c8: IV(3)
1927 \& Unmarked SV: 0xace6c8: PV("AV()"\e0)
1928 \& Unmarked SV: 0xace848: PV("IV(1)"\e0)
1929 \& (gdb)
1930 .Ve
1931 .PP
1932 Here, at the start of the first call to \fBpp_entereval()\fR, all existing SVs
1933 are marked. Then at the start of the second call, we list all the SVs
1934 which have been since been created but not yet freed. It is quickly clear
1935 that an array and its three elements are likely not being freed, perhaps
1936 as a result of a bug during constant folding. The final two SVs are just
1937 temporaries created during the debugging output and can be ignored.
1938 .PP
1939 This trick relies on the \f(CW\*(C`SVf_BREAK\*(C'\fR flag not otherwise being used. This
1940 flag is typically used only during global destruction, but also sometimes
1941 for a mark and sweep operation when looking for common elements on the two
1942 sides of a list assignment. The presence of the flag can also alter the
1943 behaviour of some specific actions in the core, such as choosing whether to
1944 copy or to COW a string SV. So turning it on can occasionally alter the
1945 behaviour of code slightly.
1946 .SS PERL_MEM_LOG
1947 .IX Subsection "PERL_MEM_LOG"
1948 If compiled with \f(CW\*(C`\-DPERL_MEM_LOG\*(C'\fR (\f(CW\*(C`\-Accflags=\-DPERL_MEM_LOG\*(C'\fR), both
1949 memory and SV allocations go through logging functions, which is handy
1950 for breakpoint setting.
1951 .PP
1952 Unless \f(CW\*(C`\-DPERL_MEM_LOG_NOIMPL\*(C'\fR (\f(CW\*(C`\-Accflags=\-DPERL_MEM_LOG_NOIMPL\*(C'\fR) is
1953 also compiled, the logging functions read \f(CW$ENV\fR{PERL_MEM_LOG} to
1954 determine whether to log the event, and if so how:
1955 .PP
1956 .Vb 6
1957 \& $ENV{PERL_MEM_LOG} =~ /m/ Log all memory ops
1958 \& $ENV{PERL_MEM_LOG} =~ /s/ Log all SV ops
1959 \& $ENV{PERL_MEM_LOG} =~ /c/ Additionally log C backtrace for
1960 \& new_SV events
1961 \& $ENV{PERL_MEM_LOG} =~ /t/ include timestamp in Log
1962 \& $ENV{PERL_MEM_LOG} =~ /^(\ed+)/ write to FD given (default is 2)
1963 .Ve
1964 .PP
1965 Memory logging is somewhat similar to \f(CW\*(C`\-Dm\*(C'\fR but is independent of
1966 \&\f(CW\*(C`\-DDEBUGGING\*(C'\fR, and at a higher level; all uses of \fBNewx()\fR, \fBRenew()\fR, and
1967 \&\fBSafefree()\fR are logged with the caller\*(Aqs source code file and line
1968 number (and C function name, if supported by the C compiler). In
1969 contrast, \f(CW\*(C`\-Dm\*(C'\fR is directly at the point of \f(CWmalloc()\fR. SV logging
1970 is similar.
1971 .PP
1972 Since the logging doesn\*(Aqt use PerlIO, all SV allocations are logged and
1973 no extra SV allocations are introduced by enabling the logging. If
1974 compiled with \f(CW\*(C`\-DDEBUG_LEAKING_SCALARS\*(C'\fR, the serial number for each SV
1975 allocation is also logged.
1976 .PP
1977 The \f(CW\*(C`c\*(C'\fR option uses the \f(CW\*(C`Perl_c_backtrace\*(C'\fR facility, and therefore
1978 additionally requires the Configure \f(CW\*(C`\-Dusecbacktrace\*(C'\fR compile flag in
1979 order to access it.
1980 .SS "DDD over gdb"
1981 .IX Subsection "DDD over gdb"
1982 Those debugging perl with the DDD frontend over gdb may find the
1983 following useful:
1984 .PP
1985 You can extend the data conversion shortcuts menu, so for example you
1986 can display an SV\*(Aqs IV value with one click, without doing any typing.
1987 To do that simply edit ~/.ddd/init file and add after:
1988 .PP
1989 .Vb 6
1990 \& ! Display shortcuts.
1991 \& Ddd*gdbDisplayShortcuts: \e
1992 \& /t () // Convert to Bin\en\e
1993 \& /d () // Convert to Dec\en\e
1994 \& /x () // Convert to Hex\en\e
1995 \& /o () // Convert to Oct(\en\e
1996 .Ve
1997 .PP
1998 the following two lines:
1999 .PP
2000 .Vb 2
2001 \& ((XPV*) (())\->sv_any )\->xpv_pv // 2pvx\en\e
2002 \& ((XPVIV*) (())\->sv_any )\->xiv_iv // 2ivx
2003 .Ve
2004 .PP
2005 so now you can do ivx and pvx lookups or you can plug there the sv_peek
2006 "conversion":
2007 .PP
2008 .Vb 1
2009 \& Perl_sv_peek(my_perl, (SV*)()) // sv_peek
2010 .Ve
2011 .PP
2012 (The my_perl is for threaded builds.) Just remember that every line,
2013 but the last one, should end with \en\e
2014 .PP
2015 Alternatively edit the init file interactively via: 3rd mouse button \->
2016 New Display \-> Edit Menu
2017 .PP
2018 Note: you can define up to 20 conversion shortcuts in the gdb section.
2019 .SS "C backtrace"
2020 .IX Subsection "C backtrace"
2021 On some platforms Perl supports retrieving the C level backtrace
2022 (similar to what symbolic debuggers like gdb do).
2023 .PP
2024 The backtrace returns the stack trace of the C call frames, with the
2025 symbol names (function names), the object names (like "perl"), and if
2026 it can, also the source code locations (file:line).
2027 .PP
2028 The supported platforms are Linux, and OS X (some *BSD might work at
2029 least partly, but they have not yet been tested).
2030 .PP
2031 This feature hasn\*(Aqt been tested with multiple threads, but it will only
2032 show the backtrace of the thread doing the backtracing.
2033 .PP
2034 The feature needs to be enabled with \f(CW\*(C`Configure \-Dusecbacktrace\*(C'\fR.
2035 .PP
2036 The \f(CW\*(C`\-Dusecbacktrace\*(C'\fR also enables keeping the debug information when
2037 compiling/linking (often: \f(CW\*(C`\-g\*(C'\fR). Many compilers/linkers do support
2038 having both optimization and keeping the debug information. The debug
2039 information is needed for the symbol names and the source locations.
2040 .PP
2041 Static functions might not be visible for the backtrace.
2042 .PP
2043 Source code locations, even if available, can often be missing or
2044 misleading if the compiler has e.g. inlined code. Optimizer can make
2045 matching the source code and the object code quite challenging.
2046 .IP Linux 4
2047 .IX Item "Linux"
2048 You \fBmust\fR have the BFD (\-lbfd) library installed, otherwise \f(CW\*(C`perl\*(C'\fR
2049 will fail to link. The BFD is usually distributed as part of the GNU
2050 binutils.
2051 .Sp
2052 Summary: \f(CW\*(C`Configure ... \-Dusecbacktrace\*(C'\fR and you need \f(CW\*(C`\-lbfd\*(C'\fR.
2053 .IP "OS X" 4
2054 .IX Item "OS X"
2055 The source code locations are supported \fBonly\fR if you have the
2056 Developer Tools installed. (BFD is \fBnot\fR needed.)
2057 .Sp
2058 Summary: \f(CW\*(C`Configure ... \-Dusecbacktrace\*(C'\fR and installing the Developer
2059 Tools would be good.
2060 .PP
2061 Optionally, for trying out the feature, you may want to enable
2062 automatic dumping of the backtrace just before a warning or croak (die)
2063 message is emitted, by adding \f(CW\*(C`\-Accflags=\-DUSE_C_BACKTRACE_ON_ERROR\*(C'\fR
2064 for Configure.
2065 .PP
2066 Unless the above additional feature is enabled, nothing about the
2067 backtrace functionality is visible, except for the Perl/XS level.
2068 .PP
2069 Furthermore, even if you have enabled this feature to be compiled, you
2070 need to enable it in runtime with an environment variable:
2071 \&\f(CW\*(C`PERL_C_BACKTRACE_ON_ERROR=10\*(C'\fR. It must be an integer higher than
2072 zero, telling the desired frame count.
2073 .PP
2074 Retrieving the backtrace from Perl level (using for example an XS
2075 extension) would be much less exciting than one would hope: normally
2076 you would see \f(CW\*(C`runops\*(C'\fR, \f(CW\*(C`entersub\*(C'\fR, and not much else. This API is
2077 intended to be called \fBfrom within\fR the Perl implementation, not from
2078 Perl level execution.
2079 .PP
2080 The C API for the backtrace is as follows:
2081 .IP get_c_backtrace 4
2082 .IX Item "get_c_backtrace"
2083 .PD 0
2084 .IP free_c_backtrace 4
2085 .IX Item "free_c_backtrace"
2086 .IP get_c_backtrace_dump 4
2087 .IX Item "get_c_backtrace_dump"
2088 .IP dump_c_backtrace 4
2089 .IX Item "dump_c_backtrace"
2090 .PD
2091 .SS Poison
2092 .IX Subsection "Poison"
2093 If you see in a debugger a memory area mysteriously full of 0xABABABAB
2094 or 0xEFEFEFEF, you may be seeing the effect of the \fBPoison()\fR macros, see
2095 perlclib.
2096 .SS "Read\-only optrees"
2097 .IX Subsection "Read-only optrees"
2098 Under ithreads the optree is read only. If you want to enforce this,
2099 to check for write accesses from buggy code, compile with
2100 \&\f(CW\*(C`\-Accflags=\-DPERL_DEBUG_READONLY_OPS\*(C'\fR to enable code that allocates op
2101 memory via \f(CW\*(C`mmap\*(C'\fR, and sets it read\-only when it is attached to a
2102 subroutine. Any write access to an op results in a \f(CW\*(C`SIGBUS\*(C'\fR and abort.
2103 .PP
2104 This code is intended for development only, and may not be portable
2105 even to all Unix variants. Also, it is an 80% solution, in that it
2106 isn\*(Aqt able to make all ops read only. Specifically it does not apply
2107 to op slabs belonging to \f(CW\*(C`BEGIN\*(C'\fR blocks.
2108 .PP
2109 However, as an 80% solution it is still effective, as it has caught
2110 bugs in the past.
2111 .SS "When is a bool not a bool?"
2112 .IX Subsection "When is a bool not a bool?"
2113 There wasn\*(Aqt necessarily a standard \f(CW\*(C`bool\*(C'\fR type on compilers prior to
2114 C99, and so some workarounds were created. The \f(CW\*(C`TRUE\*(C'\fR and \f(CW\*(C`FALSE\*(C'\fR
2115 macros are still available as alternatives for \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR.
2116 And the \f(CW\*(C`cBOOL\*(C'\fR macro was created to correctly cast to a true/false
2117 value in all circumstances, but should no longer be necessary. Using
2118 \&\f(CW\*(C`(bool)\*(C'\fR\ \fIexpr\fR should now always work.
2119 .PP
2120 There are no plans to remove any of \f(CW\*(C`TRUE\*(C'\fR, \f(CW\*(C`FALSE\*(C'\fR, nor \f(CW\*(C`cBOOL\*(C'\fR.
2121 .SS "Finding unsafe truncations"
2122 .IX Subsection "Finding unsafe truncations"
2123 You may wish to run \f(CW\*(C`Configure\*(C'\fR with something like
2124 .PP
2125 .Vb 1
2126 \& \-Accflags=\*(Aq\-Wconversion \-Wno\-sign\-conversion \-Wno\-shorten\-64\-to\-32\*(Aq
2127 .Ve
2128 .PP
2129 or your compiler\*(Aqs equivalent to make it easier to spot any unsafe
2130 truncations that show up.
2131 .SS "The .i Targets"
2132 .IX Subsection "The .i Targets"
2133 You can expand the macros in a \fIfoo.c\fR file by saying
2134 .PP
2135 .Vb 1
2136 \& make foo.i
2137 .Ve
2138 .PP
2139 which will expand the macros using cpp. Don\*(Aqt be scared by the
2140 results.
2141 .SH AUTHOR
2142 .IX Header "AUTHOR"
2143 This document was originally written by Nathan Torkington, and is
2144 maintained by the perl5\-porters mailing list.