Debian Codegraph @

upstream/debian-unstable/man1/perlhacktips.1

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