| 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. |