Perl source plays by ANSI C89 rules: no C99 (or C++) extensions. Insome cases we have to take pre-ANSI requirements into consideration.You don't care about some particular platform having broken Perl? Ihear there is still a strong demand for J2EE programmers.

Perl environment problems

Not compiling with threading
Compiling with threading (-Duseithreads) completely rewrites thefunction prototypes of Perl. You better try your changes with that.Related to this is the difference between "Perl_-less" and "Perl_-ly"APIs, for example:
```
  Perl_sv_setiv(aTHX_ ...);
   sv_setiv(...);
 
```
The first one explicitly passes in the context, which is needed fore.g. threaded builds. The second one does that implicitly; do not getthem mixed. If you are not passing in a aTHX_, you will need to do adTHX (or a dVAR) as the first thing in the function.
See How multiple interpreters and concurrency are supported in perlguts for further discussion about context.
Not compiling with -DDEBUGGING
The DEBUGGING define exposes more code to the compiler, therefore moreways for things to go wrong. You should try it.
Introducing (non-read-only) globals
Do not introduce any modifiable globals, truly global or file static.They are bad form and complicate multithreading and other forms ofconcurrency. The right way is to introduce them as new interpretervariables, see intrpvar.h (at the very end for binarycompatibility).
Introducing read-only (const) globals is okay, as long as you verifywith e.g. nm libperl.a|egrep -v ' [TURtr] ' (if your nm hasBSD-style output) that the data you added really is read-only. (If itis, it shouldn't show up in the output of that command.)
If you want to have static strings, make them constant:
```
  static const char etc[] = "...";
 
```
If you want to have arrays of constant strings, note carefully theright combination of consts:
```
 static const char * const yippee[] =
 {"hi", "ho", "silver"};
 
```
There is a way to completely hide any modifiable globals (they are allmoved to heap), the compilation setting-DPERL_GLOBAL_STRUCT_PRIVATE. It is not normally used, but can beused for testing, read more about it in Background and PERL_IMPLICIT_CONTEXT in perlguts.
Not exporting your new function
Some platforms (Win32, AIX, VMS, OS/2, to name a few) require anyfunction that is part of the public API (the shared Perl library) to beexplicitly marked as exported. See the discussion about embed.pl inperlguts.
Exporting your new function
The new shiny result of either genuine new functionality or yourarduous refactoring is now ready and correctly exported. So what couldpossibly go wrong?
Maybe simply that your function did not need to be exported in thefirst place. Perl has a long and not so glorious history of exportingfunctions that it should not have.
If the function is used only inside one source code file, make itstatic. See the discussion about embed.pl in perlguts.
If the function is used across several files, but intended only forPerl's internal use (and this should be the common case), do not exportit to the public API. See the discussion about embed.pl inperlguts.

Portability problems

The following are common causes of compilation and/or executionfailures, not common to Perl as such. The C FAQ is good bedtimereading. Please test your changes with as many C compilers andplatforms as possible; we will, anyway, and it's nice to save oneselffrom public embarrassment.

If using gcc, you can add the -std=c89 option which will hopefullycatch most of these unportabilities. (However it might also catchincompatibilities in your system's header files.)

Use the Configure -Dgccansipedantic flag to enable the gcc -ansi-pedantic flags which enforce stricter ANSI rules.

If using the gcc -Wall note that not all the possible warnings (like-Wunitialized) are given unless you also compile with -O.

Note that if using gcc, starting from Perl 5.9.5 the Perl core sourcecode files (the ones at the top level of the source code distribution,but not e.g. the extensions under ext/) are automatically compiled withas many as possible of the -std=c89, -ansi, -pedantic, and aselection of -W flags (see cflags.SH).

Also study perlport carefully to avoid any bad assumptions about theoperating system, filesystems, and so forth.

You may once in a while try a "make microperl" to see whether we canstill compile Perl with just the bare minimum of interfaces. (SeeREADME.micro.)

Do not assume an operating system indicates a certain compiler.

Casting pointers to integers or casting integers to pointers
```
 void castaway(U8* p)
  {
   IV i = p;
 
```
or
```
 void castaway(U8* p)
  {
   IV i = (IV)p;
 
```
Both are bad, and broken, and unportable. Use the PTR2IV() macro thatdoes it right. (Likewise, there are PTR2UV(), PTR2NV(), INT2PTR(), andNUM2PTR().)
Casting between data function pointers and data pointers
Technically speaking casting between function pointers and datapointers is unportable and undefined, but practically speaking it seemsto work, but you should use the FPTR2DPTR() and DPTR2FPTR() macros.Sometimes you can also play games with unions.
Assuming sizeof(int) == sizeof(long)
There are platforms where longs are 64 bits, and platforms where intsare 64 bits, and while we are out to shock you, even platforms whereshorts are 64 bits. This is all legal according to the C standard. (Inother words, "long long" is not a portable way to specify 64 bits, and"long long" is not even guaranteed to be any wider than "long".)
Instead, use the definitions IV, UV, IVSIZE, I32SIZE, and so forth.Avoid things like I32 because they are not guaranteed to beexactly 32 bits, they are at least 32 bits, nor are theyguaranteed to be int or long. If you really explicitly need64-bit variables, use I64 and U64, but only if guarded by HAS_QUAD.
Assuming one can dereference any type of pointer for any type of data
```
  char *p = ...;
   long pony = *p; /* BAD */
 
```
Many platforms, quite rightly so, will give you a core dump instead ofa pony if the p happens not to be correctly aligned.
Lvalue casts
```
  (int)*p = ...; /* BAD */
 
```
Simply not portable. Get your lvalue to be of the right type, or maybeuse temporary variables, or dirty tricks with unions.
Assume anything about structs (especially the ones you don'tcontrol, like the ones coming from the system headers)
- That a certain field exists in a struct
- That no other fields exist besides the ones you know of
- That a field is of certain signedness, sizeof, or type
- That the fields are in a certain order
  - While C guarantees the ordering specified in the struct definition,between different platforms the definitions might differ
- That the sizeof(struct) or the alignments are the same everywhere
  - There might be padding bytes between the fields to align the fields -the bytes can be anything
  - Structs are required to be aligned to the maximum alignment required bythe fields - which for native types is for usually equivalent tosizeof() of the field
Assuming the character set is ASCIIish
Perl can compile and run under EBCDIC platforms. See perlebcdic.This is transparent for the most part, but because the character setsdiffer, you shouldn't use numeric (decimal, octal, nor hex) constantsto refer to characters. You can safely say 'A', but not 0x41. You cansafely say '\n', but not \012. If a character doesn't have a trivialinput form, you can create a #define for it in both utfebcdic.h andutf8.h, so that it resolves to different values depending on thecharacter set being used. (There are three different EBCDIC charactersets defined in utfebcdic.h, so it might be best to insert the#define three times in that file.)
Also, the range 'A' - 'Z' in ASCII is an unbroken sequence of 26 uppercase alphabetic characters. That is not true in EBCDIC. Nor for 'a' to'z'. But '0' - '9' is an unbroken range in both systems. Don't assumeanything about other ranges.
Many of the comments in the existing code ignore the possibility ofEBCDIC, and may be wrong therefore, even if the code works. This isactually a tribute to the successful transparent insertion of beingable to handle EBCDIC without having to change pre-existing code.
UTF-8 and UTF-EBCDIC are two different encodings used to representUnicode code points as sequences of bytes. Macros with the same names(but different definitions) in utf8.h and utfebcdic.h are used toallow the calling code to think that there is only one such encoding.This is almost always referred to as utf8, but it means the EBCDICversion as well. Again, comments in the code may well be wrong even ifthe code itself is right. For example, the concept of invariantcharacters differs between ASCII and EBCDIC. On ASCII platforms, onlycharacters that do not have the high-order bit set (i.e. whose ordinalsare strict ASCII, 0 - 127) are invariant, and the documentation andcomments in the code may assume that, often referring to somethinglike, say, hibit. The situation differs and is not so simple onEBCDIC machines, but as long as the code itself uses theNATIVE_IS_INVARIANT() macro appropriately, it works, even if thecomments are wrong.
Assuming the character set is just ASCII
ASCII is a 7 bit encoding, but bytes have 8 bits in them. The 128 extracharacters have different meanings depending on the locale. Absent alocale, currently these extra characters are generally considered to beunassigned, and this has presented some problems. This is being changedstarting in 5.12 so that these characters will be considered to beLatin-1 (ISO-8859-1).

Mixing #define and #ifdef

  #define BURGLE(x) ... \
   #ifdef BURGLE_OLD_STYLE /* BAD */
   ... do it the old way ... \
   #else
   ... do it the new way ... \
   #endif

You cannot portably "stack" cpp directives. For example in the aboveyou need two separate BURGLE() #defines, one for each #ifdef branch.

Adding non-comment stuff after #endif or #else
```
  #ifdef SNOSH
   ...
   #else !SNOSH /* BAD */
   ...
   #endif SNOSH /* BAD */
 
```
The #endif and #else cannot portably have anything non-comment afterthem. If you want to document what is going (which is a good ideaespecially if the branches are long), use (C) comments:
```
  #ifdef SNOSH
   ...
   #else /* !SNOSH */
   ...
   #endif /* SNOSH */
 
```
The gcc option -Wendif-labels warns about the bad variant (bydefault on starting from Perl 5.9.4).
Having a comma after the last element of an enum list
```
  enum color {
  CERULEAN,
  CHARTREUSE,
  CINNABAR, /* BAD */
   };
 
```
is not portable. Leave out the last comma.
Also note that whether enums are implicitly morphable to ints variesbetween compilers, you might need to (int).
Using //-comments
```
  // This function bamfoodles the zorklator.   /* BAD */
 
```
That is C99 or C++. Perl is C89. Using the //-comments is silentlyallowed by many C compilers but cranking up the ANSI C89 strictness(which we like to do) causes the compilation to fail.
Mixing declarations and code
```
  void zorklator()
   {
  int n = 3;
  set_zorkmids(n); /* BAD */
  int q = 4;
 
```
That is C99 or C++. Some C compilers allow that, but you shouldn't.
The gcc option -Wdeclaration-after-statements scans for suchproblems (by default on starting from Perl 5.9.4).
Introducing variables inside for()
```
  for(int i = ...; ...; ...) { /* BAD */
 
```
That is C99 or C++. While it would indeed be awfully nice to have thatalso in C89, to limit the scope of the loop variable, alas, we cannot.
Mixing signed char pointers with unsigned char pointers
```
  int foo(char *s) { ... }
   ...
   unsigned char *t = ...; /* Or U8* t = ... */
   foo(t);   /* BAD */
 
```
While this is legal practice, it is certainly dubious, and downrightfatal in at least one platform: for example VMS cc considers this afatal error. One cause for people often making this mistake is that a"naked char" and therefore dereferencing a "naked char pointer" have anundefined signedness: it depends on the compiler and the flags of thecompiler and the underlying platform whether the result is signed orunsigned. For this very same reason using a 'char' as an array index isbad.
Macros that have string constants and their arguments as substrings ofthe string constants
```
  #define FOO(n) printf("number = %d\n", n) /* BAD */
   FOO(10);
 
```
Pre-ANSI semantics for that was equivalent to
```
  printf("10umber = %d\10");
 
```
which is probably not what you were expecting. Unfortunately at leastone reasonably common and modern C compiler does "real backwardcompatibility" here, in AIX that is what still happens even though therest of the AIX compiler is very happily C89.
Using printf formats for non-basic C types
```
   IV i = ...;
    printf("i = %d\n", i); /* BAD */
 
```
While this might by accident work in some platform (where IV happens tobe an int), in general it cannot. IV might be something larger. Evenworse the situation is with more specific types (defined by Perl'sconfiguration step in config.h):
```
   Uid_t who = ...;
    printf("who = %d\n", who); /* BAD */
 
```
The problem here is that Uid_t might be not only not int-wide but itmight also be unsigned, in which case large uids would be printed asnegative values.
There is no simple solution to this because of printf()'s limitedintelligence, but for many types the right format is available as witheither 'f' or '_f' suffix, for example:
```
   IVdf /* IV in decimal */
    UVxf /* UV is hexadecimal */
 
    printf("i = %"IVdf"\n", i); /* The IVdf is a string constant. */
 
    Uid_t_f /* Uid_t in decimal */
 
    printf("who = %"Uid_t_f"\n", who);
 
```
Or you can try casting to a "wide enough" type:
```
   printf("i = %"IVdf"\n", (IV)something_very_small_and_signed);
 
```
Also remember that the %p format really does require a void pointer:
```
   U8* p = ...;
    printf("p = %p\n", (void*)p);
 
```
The gcc option -Wformat scans for such problems.
Blindly using variadic macros
gcc has had them for a while with its own syntax, and C99 brought themwith a standardized syntax. Don't use the former, and use the latteronly if the HAS_C99_VARIADIC_MACROS is defined.
Blindly passing va_list
Not all platforms support passing va_list to further varargs (stdarg)functions. The right thing to do is to copy the va_list using thePerl_va_copy() if the NEED_VA_COPY is defined.
Using gcc statement expressions
```
   val = ({...;...;...}); /* BAD */
 
```
While a nice extension, it's not portable. The Perl code doesadmittedly use them if available to gain some extra speed (essentiallyas a funky form of inlining), but you shouldn't.
Binding together several statements in a macro
Use the macros STMT_START and STMT_END.
```
   STMT_START {
   ...
    } STMT_END
 
```
Testing for operating systems or versions when should be testing forfeatures
```
  #ifdef __FOONIX__ /* BAD */
   foo = quux();
   #endif
 
```
Unless you know with 100% certainty that quux() is only ever availablefor the "Foonix" operating system and that is available andcorrectly working for all past, present, and future versions of"Foonix", the above is very wrong. This is more correct (though stillnot perfect, because the below is a compile-time check):
```
  #ifdef HAS_QUUX
   foo = quux();
   #endif
 
```
How does the HAS_QUUX become defined where it needs to be? Well, ifFoonix happens to be Unixy enough to be able to run the Configurescript, and Configure has been taught about detecting and testingquux(), the HAS_QUUX will be correctly defined. In other platforms, thecorresponding configuration step will hopefully do the same.
In a pinch, if you cannot wait for Configure to be educated, or if youhave a good hunch of where quux() might be available, you cantemporarily try the following:
```
  #if (defined(__FOONIX__) || defined(__BARNIX__))
   # define HAS_QUUX
   #endif
 
   ...
 
   #ifdef HAS_QUUX
   foo = quux();
   #endif
 
```
But in any case, try to keep the features and operating systemsseparate.

Problematic System Interfaces

malloc(0), realloc(0), calloc(0, 0) are non-portable. To be portableallocate at least one byte. (In general you should rarely need to workat this low level, but instead use the various malloc wrappers.)
snprintf() - the return type is unportable. Use my_snprintf() instead.

Security problems

Last but not least, here are various tips for safer coding.

Do not use gets()
Or we will publicly ridicule you. Seriously.
Do not use strcpy() or strcat() or strncpy() or strncat()
Use my_strlcpy() and my_strlcat() instead: they either use the nativeimplementation, or Perl's own implementation (borrowed from the publicdomain implementation of INN).
Do not use sprintf() or vsprintf()
If you really want just plain byte strings, use my_snprintf() andmy_vsnprintf() instead, which will try to use snprintf() andvsnprintf() if those safer APIs are available. If you want somethingfancier than a plain byte string, use SVs and Perl_sv_catpvf().

DEBUGGING

You can compile a special debugging version of Perl, which allows youto use the -D option of Perl to tell more about what Perl is doing.But sometimes there is no alternative than to dive in with a debugger,either to see the stack trace of a core dump (very useful in a bugreport), or trying to figure out what went wrong before the core dumphappened, or how did we end up having wrong or unexpected results.

Poking at Perl

To really poke around with Perl, you'll probably want to build Perl fordebugging, like this:

 ./Configure -d -D optimize=-g
  make

-g is a flag to the C compiler to have it produce debugginginformation which will allow us to step through a running program, andto see in which C function we are at (without the debugging informationwe might see only the numerical addresses of the functions, which isnot very helpful).

Configure will also turn on the DEBUGGING compilation symbolwhich enables all the internal debugging code in Perl. There are awhole bunch of things you can debug with this: perlrun lists themall, and the best way to find out about them is to play about withthem. The most useful options are probably

 l  Context (loop) stack processing
  t  Trace execution
  o  Method and overloading resolution
  c  String/numeric conversions

Some of the functionality of the debugging code can be achieved usingXS modules.

 -Dr => use re 'debug'
  -Dx => use O 'Debug'

Using a source-level debugger

If the debugging output of -D doesn't help you, it's time to stepthrough perl's execution with a source-level debugger.

We'll use gdb for our examples here; the principles will apply toany debugger (many vendors call their debugger dbx), but check themanual of the one you're using.

To fire up the debugger, type

 gdb ./perl

Or if you have a core dump:

 gdb ./perl core

You'll want to do that in your Perl source tree so the debugger canread the source code. You should see the copyright message, followed bythe prompt.

 (gdb)

help will get you into the documentation, but here are the mostuseful commands:

run [args]
Run the program with the given arguments.
break function_name
break source.c:xxx
Tells the debugger that we'll want to pause execution when we reacheither the named function (but see Internal Functions in perlguts!) orthe given line in the named source file.
step
Steps through the program a line at a time.
next
Steps through the program a line at a time, without descending intofunctions.
continue
Run until the next breakpoint.
finish
Run until the end of the current function, then stop again.
'enter'
Just pressing Enter will do the most recent operation again - it's ablessing when stepping through miles of source code.
print
Execute the given C code and print its results. WARNING: Perl makesheavy use of macros, and gdb does not necessarily support macros(see later gdb macro support). You'll have to substitute themyourself, or to invoke cpp on the source code files (see The .i Targets) So, for instance, you can't say
```
 print SvPV_nolen(sv)
 
```
but you have to say
```
 print Perl_sv_2pv_nolen(sv)
 
```

You may find it helpful to have a "macro dictionary", which you canproduce by saying cpp -dM perl.c | sort. Even then, cpp won'trecursively apply those macros for you.

gdb macro support

Recent versions of gdb have fairly good macro support, but in orderto use it you'll need to compile perl with macro definitions includedin the debugging information. Using gcc version 3.1, this meansconfiguring with -Doptimize=-g3. Other compilers might use adifferent switch (if they support debugging macros at all).

Dumping Perl Data Structures

One way to get around this macro hell is to use the dumping functionsin dump.c; these work a little like an internalDevel::Peek, but they also cover OPs and otherstructures that you can't get at from Perl. Let's take an example.We'll use the $a = $b + $c we used before, but give it a bit ofcontext: $b = "6XXXX"; $c = 2.3;. Where's a good place to stop andpoke around?

What about pp_add, the function we examined earlier to implement the+ operator:

 (gdb) break Perl_pp_add
  Breakpoint 1 at 0x46249f: file pp_hot.c, line 309.

Notice we use Perl_pp_add and not pp_add - seeInternal Functions in perlguts. With the breakpoint in place, we canrun our program:

 (gdb) run -e '$b = "6XXXX"; $c = 2.3; $a = $b + $c'

Lots of junk will go past as gdb reads in the relevant source files andlibraries, and then:

 Breakpoint 1, Perl_pp_add () at pp_hot.c:309
  309 dSP; dATARGET; tryAMAGICbin(add,opASSIGN);
  (gdb) step
  311   dPOPTOPnnrl_ul;
  (gdb)

We looked at this bit of code before, and we said thatdPOPTOPnnrl_ul arranges for two NVs to be placed into left andright - let's slightly expand it:

 #define dPOPTOPnnrl_ul  NV right = POPn; \
  SV *leftsv = TOPs; \
  NV left = USE_LEFT(leftsv) ? SvNV(leftsv) : 0.0

POPn takes the SV from the top of the stack and obtains its NVeither directly (if SvNOK is set) or by calling the sv_2nvfunction. TOPs takes the next SV from the top of the stack - yes,POPn uses TOPs - but doesn't remove it. We then use SvNV toget the NV from leftsv in the same way as before - yes, POPn usesSvNV.

Since we don't have an NV for $b, we'll have to use sv_2nv toconvert it. If we step again, we'll find ourselves there:

 Perl_sv_2nv (sv=0xa0675d0) at sv.c:1669
  1669 if (!sv)
  (gdb)

We can now use Perl_sv_dump to investigate the SV:

 SV = PV(0xa057cc0) at 0xa0675d0
  REFCNT = 1
  FLAGS = (POK,pPOK)
  PV = 0xa06a510 "6XXXX"\0
  CUR = 5
  LEN = 6
  $1 = void

We know we're going to get 6 from this, so let's finish thesubroutine:

 (gdb) finish
  Run till exit from #0  Perl_sv_2nv (sv=0xa0675d0) at sv.c:1671
  0x462669 in Perl_pp_add () at pp_hot.c:311
  311   dPOPTOPnnrl_ul;

We can also dump out this op: the current op is always stored inPL_op, and we can dump it with Perl_op_dump. This'll give ussimilar output to B::Debug.

 {
  13  TYPE = add  ===> 14
  TARG = 1
  FLAGS = (SCALAR,KIDS)
  {
  TYPE = null  ===> (12)
   (was rv2sv)
  FLAGS = (SCALAR,KIDS)
  {
  11  TYPE = gvsv  ===> 12
  FLAGS = (SCALAR)
  GV = main::b
  }
  }

# finish this later #

SOURCE CODE STATIC ANALYSIS

Various tools exist for analysing C source code statically, asopposed to dynamically, that is, without executing the code. It ispossible to detect resource leaks, undefined behaviour, typemismatches, portability problems, code paths that would cause illegalmemory accesses, and other similar problems by just parsing the C codeand looking at the resulting graph, what does it tell about theexecution and data flows. As a matter of fact, this is exactly how Ccompilers know to give warnings about dubious code.

lint, splint

The good old C code quality inspector, lint, is available in severalplatforms, but please be aware that there are several differentimplementations of it by different vendors, which means that the flagsare not identical across different platforms.

There is a lint variant called splint (Secure Programming Lint)available from http://www.splint.org/ that should compile on anyUnix-like platform.

There are lint and <splint> targets in Makefile, but you may have todiddle with the flags (see above).

Coverity

Coverity (http://www.coverity.com/) is a product similar to lint and asa testbed for their product they periodically check several open sourceprojects, and they give out accounts to open source developers to thedefect databases.

cpd (cut-and-paste detector)

The cpd tool detects cut-and-paste coding. If one instance of thecut-and-pasted code changes, all the other spots should probably bechanged, too. Therefore such code should probably be turned into asubroutine or a macro.

cpd (http://pmd.sourceforge.net/cpd.html) is part of the pmd project(http://pmd.sourceforge.net/). pmd was originally written for staticanalysis of Java code, but later the cpd part of it was extended toparse also C and C++.

Download the pmd-bin-X.Y.zip () from the SourceForge site, extract thepmd-X.Y.jar from it, and then run that on source code thusly:

  java -cp pmd-X.Y.jar net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /some/where/src --language c > cpd.txt

You may run into memory limits, in which case you should use the -Xmxoption:

  java -Xmx512M ...

gcc warnings

Though much can be written about the inconsistency and coverageproblems of gcc warnings (like -Wall not meaning "all the warnings",or some common portability problems not being covered by -Wall, or-ansi and -pedantic both being a poorly defined collection ofwarnings, and so forth), gcc is still a useful tool in keeping ourcoding nose clean.

The -Wall is by default on.

The -ansi (and its sidekick, -pedantic) would be nice to be onalways, but unfortunately they are not safe on all platforms, they canfor example cause fatal conflicts with the system headers (Solarisbeing a prime example). If Configure -Dgccansipedantic is used, thecflags frontend selects -ansi -pedantic for the platforms wherethey are known to be safe.

Starting from Perl 5.9.4 the following extra flags are added:

-Wendif-labels
-Wextra
-Wdeclaration-after-statement

The following flags would be nice to have but they would first needtheir own Augean stablemaster:

-Wpointer-arith
-Wshadow
-Wstrict-prototypes

The -Wtraditional is another example of the annoying tendency of gccto bundle a lot of warnings under one switch (it would be impossible todeploy in practice because it would complain a lot) but it does containsome warnings that would be beneficial to have available on their own,such as the warning about string constants inside macros containing themacro arguments: this behaved differently pre-ANSI than it does inANSI, and some C compilers are still in transition, AIX being anexample.

Warnings of other C compilers

Other C compilers (yes, there are other C compilers than gcc) oftenhave their "strict ANSI" or "strict ANSI with some portabilityextensions" modes on, like for example the Sun Workshop has its -Xamode on (though implicitly), or the DEC (these days, HP...) has its-std1 mode on.

MEMORY DEBUGGERS

NOTE 1: Running under memory debuggers such as Purify, valgrind, orThird Degree greatly slows down the execution: seconds become minutes,minutes become hours. For example as of Perl 5.8.1, theext/Encode/t/Unicode.t takes extraordinarily long to complete undere.g. Purify, Third Degree, and valgrind. Under valgrind it takes morethan six hours, even on a snappy computer. The said test must be doingsomething that is quite unfriendly for memory debuggers. If you don'tfeel like waiting, that you can simply kill away the perl process.

NOTE 2: To minimize the number of memory leak false alarms (seePERL_DESTRUCT_LEVEL for more information), you have to set theenvironment variable PERL_DESTRUCT_LEVEL to 2.

For csh-like shells:

 setenv PERL_DESTRUCT_LEVEL 2

For Bourne-type shells:

 PERL_DESTRUCT_LEVEL=2
  export PERL_DESTRUCT_LEVEL

In Unixy environments you can also use the env command:

 env PERL_DESTRUCT_LEVEL=2 valgrind ./perl -Ilib ...

NOTE 3: There are known memory leaks when there are compile-timeerrors within eval or require, seeing S_doeval in the call stack isa good sign of these. Fixing these leaks is non-trivial, unfortunately,but they must be fixed eventually.

NOTE 4: DynaLoader will not clean up after itself completelyunless Perl is built with the Configure option-Accflags=-DDL_UNLOAD_ALL_AT_EXIT.

Rational Software's Purify

Purify is a commercial tool that is helpful in identifying memoryoverruns, wild pointers, memory leaks and other such badness. Perl mustbe compiled in a specific way for optimal testing with Purify. Purifyis available under Windows NT, Solaris, HP-UX, SGI, and Siemens Unix.

Purify on Unix

On Unix, Purify creates a new Perl binary. To get the most benefit outof Purify, you should create the perl to Purify using:

 sh Configure -Accflags=-DPURIFY -Doptimize='-g' \
  -Uusemymalloc -Dusemultiplicity

where these arguments mean:

-Accflags=-DPURIFY
Disables Perl's arena memory allocation functions, as well as forcinguse of memory allocation functions derived from the system malloc.
-Doptimize='-g'
Adds debugging information so that you see the exact source statementswhere the problem occurs. Without this flag, all you will see is thesource filename of where the error occurred.
-Uusemymalloc
Disable Perl's malloc so that Purify can more closely monitorallocations and leaks. Using Perl's malloc will make Purify report mostleaks in the "potential" leaks category.
-Dusemultiplicity
Enabling the multiplicity option allows perl to clean up thoroughlywhen the interpreter shuts down, which reduces the number of bogus leakreports from Purify.

Once you've compiled a perl suitable for Purify'ing, then you can just:

 make pureperl

which creates a binary named 'pureperl' that has been Purify'ed. Thisbinary is used in place of the standard 'perl' binary when you want todebug Perl memory problems.

As an example, to show any memory leaks produced during the standardPerl testset you would create and run the Purify'ed perl as:

 make pureperl
  cd t
  ../pureperl -I../lib harness

which would run Perl on test.pl and report any memory problems.

Purify outputs messages in "Viewer" windows by default. If you don'thave a windowing environment or if you simply want the Purify output tounobtrusively go to a log file instead of to the interactive window,use these following options to output to the log file "perl.log":

 setenv PURIFYOPTIONS "-chain-length=25 -windows=no \
   -log-file=perl.log -append-logfile=yes"

If you plan to use the "Viewer" windows, then you only need thisoption:

 setenv PURIFYOPTIONS "-chain-length=25"

In Bourne-type shells:

 PURIFYOPTIONS="..."
  export PURIFYOPTIONS

or if you have the "env" utility:

 env PURIFYOPTIONS="..." ../pureperl ...

Purify on NT

Purify on Windows NT instruments the Perl binary 'perl.exe' on the fly. There are several options in the makefile you should change to get themost use out of Purify:

DEFINES
You should add -DPURIFY to the DEFINES line so the DEFINES line lookssomething like:
```
   DEFINES = -DWIN32 -D_CONSOLE -DNO_STRICT $(CRYPT_FLAG) -DPURIFY=1
 
```
to disable Perl's arena memory allocation functions, as well as toforce use of memory allocation functions derived from the systemmalloc.
USE_MULTI = define
Enabling the multiplicity option allows perl to clean up thoroughlywhen the interpreter shuts down, which reduces the number of bogus leakreports from Purify.
#PERL_MALLOC = define
Disable Perl's malloc so that Purify can more closely monitorallocations and leaks. Using Perl's malloc will make Purify report mostleaks in the "potential" leaks category.
CFG = Debug
Adds debugging information so that you see the exact source statementswhere the problem occurs. Without this flag, all you will see is thesource filename of where the error occurred.

As an example, to show any memory leaks produced during the standardPerl testset you would create and run Purify as:

 cd win32
  make
  cd ../t
  purify ../perl -I../lib harness

which would instrument Perl in memory, run Perl on test.pl, thenfinally report any memory problems.

valgrind

The excellent valgrind tool can be used to find out both memory leaksand illegal memory accesses. As of version 3.3.0, Valgrind onlysupports Linux on x86, x86-64 and PowerPC and Darwin (OS X) on x86 andx86-64). The special "test.valgrind" target can be used to run thetests under valgrind. Found errors and memory leaks are logged infiles named testfile.valgrind.

Valgrind also provides a cachegrind tool, invoked on perl as:

 VG_OPTS=--tool=cachegrind make test.valgrind

As system libraries (most notably glibc) are also triggering errors,valgrind allows to suppress such errors using suppression files. Thedefault suppression file that comes with valgrind already catches a lotof them. Some additional suppressions are defined in t/perl.supp.

To get valgrind and for more information see

 http://valgrind.org/

PROFILING

Depending on your platform there are various ways of profiling Perl.

There are two commonly used techniques of profiling executables:statistical time-sampling and basic-block counting.

The first method takes periodically samples of the CPU program counter,and since the program counter can be correlated with the code generatedfor functions, we get a statistical view of in which functions theprogram is spending its time. The caveats are that very small/fastfunctions have lower probability of showing up in the profile, and thatperiodically interrupting the program (this is usually done ratherfrequently, in the scale of milliseconds) imposes an additionaloverhead that may skew the results. The first problem can be alleviatedby running the code for longer (in general this is a good idea forprofiling), the second problem is usually kept in guard by theprofiling tools themselves.

The second method divides up the generated code into basic blocks.Basic blocks are sections of code that are entered only in thebeginning and exited only at the end. For example, a conditional jumpstarts a basic block. Basic block profiling usually works byinstrumenting the code by adding enter basic block #nnnnbook-keeping code to the generated code. During the execution of thecode the basic block counters are then updated appropriately. Thecaveat is that the added extra code can skew the results: again, theprofiling tools usually try to factor their own effects out of theresults.

Gprof Profiling

gprof is a profiling tool available in many Unix platforms, it usesstatistical time-sampling.

You can build a profiled version of perl called "perl.gprof" byinvoking the make target "perl.gprof" (What is required is that Perlmust be compiled using the -pg flag, you may need to re-Configure).Running the profiled version of Perl will create an output file calledgmon.out is created which contains the profiling data collectedduring the execution.

The gprof tool can then display the collected data in various ways.Usually gprof understands the following options:

-a
Suppress statically defined functions from the profile.
-b
Suppress the verbose descriptions in the profile.
-e routine
Exclude the given routine and its descendants from the profile.
-f routine
Display only the given routine and its descendants in the profile.
-s
Generate a summary file called gmon.sum which then may be given tosubsequent gprof runs to accumulate data over several runs.
-z
Display routines that have zero usage.

For more detailed explanation of the available commands and outputformats, see your own local documentation of gprof.

quick hint:

 $ sh Configure -des -Dusedevel -Doptimize='-pg' && make perl.gprof
  $ ./perl.gprof someprog # creates gmon.out in current directory
  $ gprof ./perl.gprof > out
  $ view out

GCC gcov Profiling

Starting from GCC 3.0 basic block profiling is officially availablefor the GNU CC.

You can build a profiled version of perl called perl.gcov byinvoking the make target "perl.gcov" (what is required that Perl mustbe compiled using gcc with the flags -fprofile-arcs -ftest-coverage,you may need to re-Configure).

Running the profiled version of Perl will cause profile output to begenerated. For each source file an accompanying ".da" file will becreated.

To display the results you use the "gcov" utility (which should beinstalled if you have gcc 3.0 or newer installed). gcov is run onsource code files, like this

 gcov sv.c

which will cause sv.c.gcov to be created. The .gcov files containthe source code annotated with relative frequencies of executionindicated by "#" markers.

Useful options of gcov include -b which will summarise the basicblock, branch, and function call coverage, and -c which instead ofrelative frequencies will use the actual counts. For more informationon the use of gcov and basic block profiling with gcc, see thelatest GNU CC manual, as of GCC 3.0 see

 http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc.html

and its section titled "8. gcov: a Test Coverage Program"

 http://gcc.gnu.org/onlinedocs/gcc-3.0/gcc_8.html#SEC132

quick hint:

 $ sh Configure -des -Dusedevel -Doptimize='-g' \
  -Accflags='-fprofile-arcs -ftest-coverage' \
  -Aldflags='-fprofile-arcs -ftest-coverage' && make perl.gcov
  $ rm -f regexec.c.gcov regexec.gcda
  $ ./perl.gcov
  $ gcov regexec.c
  $ view regexec.c.gcov

MISCELLANEOUS TRICKS

PERL_DESTRUCT_LEVEL

If you want to run any of the tests yourself manually using e.g.valgrind, or the pureperl or perl.third executables, please note thatby default perl does not explicitly cleanup all the memory it hasallocated (such as global memory arenas) but instead lets the exit() ofthe whole program "take care" of such allocations, also known as"global destruction of objects".

There is a way to tell perl to do complete cleanup: set the environmentvariable PERL_DESTRUCT_LEVEL to a non-zero value. The t/TEST wrapperdoes set this to 2, and this is what you need to do too, if you don'twant to see the "global leaks": For example, for "third-degreed" Perl:

env PERL_DESTRUCT_LEVEL=2 ./perl.third -Ilib t/foo/bar.t

(Note: the mod_perl apache module uses also this environment variablefor its own purposes and extended its semantics. Refer to the mod_perldocumentation for more information. Also, spawned threads do theequivalent of setting this variable to the value 1.)

If, at the end of a run you get the message N scalars leaked, youcan recompile with -DDEBUG_LEAKING_SCALARS, which will cause theaddresses of all those leaked SVs to be dumped along with details as towhere each SV was originally allocated. This information is alsodisplayed by Devel::Peek. Note that the extra details recorded witheach SV increases memory usage, so it shouldn't be used in productionenvironments. It also converts new_SV() from a macro into a realfunction, so you can use your favourite debugger to discover wherethose pesky SVs were allocated.

If you see that you're leaking memory at runtime, but neither valgrindnor -DDEBUG_LEAKING_SCALARS will find anything, you're probablyleaking SVs that are still reachable and will be properly cleaned upduring destruction of the interpreter. In such cases, using the -Dmswitch can point you to the source of the leak. If the executable wasbuilt with -DDEBUG_LEAKING_SCALARS, -Dm will output SVallocations in addition to memory allocations. Each SV allocation has adistinct serial number that will be written on creation and destructionof the SV. So if you're executing the leaking code in a loop, you needto look for SVs that are created, but never destroyed between eachcycle. If such an SV is found, set a conditional breakpoint withinnew_SV() and make it break only when PL_sv_serial is equal to theserial number of the leaking SV. Then you will catch the interpreter inexactly the state where the leaking SV is allocated, which issufficient in many cases to find the source of the leak.

As -Dm is using the PerlIO layer for output, it will by itselfallocate quite a bunch of SVs, which are hidden to avoid recursion. Youcan bypass the PerlIO layer if you use the SV logging provided by-DPERL_MEM_LOG instead.

PERL_MEM_LOG

If compiled with -DPERL_MEM_LOG, both memory and SV allocations gothrough logging functions, which is handy for breakpoint setting.

Unless -DPERL_MEM_LOG_NOIMPL is also compiled, the logging functionsread $ENV{PERL_MEM_LOG} to determine whether to log the event, and ifso how:

 $ENV{PERL_MEM_LOG} =~ /m/Log all memory ops
  $ENV{PERL_MEM_LOG} =~ /s/Log all SV ops
  $ENV{PERL_MEM_LOG} =~ /t/include timestamp in Log
  $ENV{PERL_MEM_LOG} =~ /^(\d+)/write to FD given (default is 2)

Memory logging is somewhat similar to -Dm but is independent of-DDEBUGGING, and at a higher level; all uses of Newx(), Renew(), andSafefree() are logged with the caller's source code file and linenumber (and C function name, if supported by the C compiler). Incontrast, -Dm is directly at the point of malloc(). SV logging issimilar.

Since the logging doesn't use PerlIO, all SV allocations are logged andno extra SV allocations are introduced by enabling the logging. Ifcompiled with -DDEBUG_LEAKING_SCALARS, the serial number for each SVallocation is also logged.

DDD over gdb

Those debugging perl with the DDD frontend over gdb may find thefollowing useful:

You can extend the data conversion shortcuts menu, so for example youcan display an SV's IV value with one click, without doing any typing.To do that simply edit ~/.ddd/init file and add after:

  ! Display shortcuts.
   Ddd*gdbDisplayShortcuts: \
   /t ()   // Convert to Bin\n\
   /d ()   // Convert to Dec\n\
   /x ()   // Convert to Hex\n\
   /o ()   // Convert to Oct(\n\

the following two lines:

  ((XPV*) (())->sv_any )->xpv_pv  // 2pvx\n\
   ((XPVIV*) (())->sv_any )->xiv_iv // 2ivx

so now you can do ivx and pvx lookups or you can plug there the sv_peek"conversion":

  Perl_sv_peek(my_perl, (SV*)()) // sv_peek

(The my_perl is for threaded builds.) Just remember that every line,but the last one, should end with \n\

Alternatively edit the init file interactively via: 3rd mouse button ->New Display -> Edit Menu

Note: you can define up to 20 conversion shortcuts in the gdb section.

Poison

If you see in a debugger a memory area mysteriously full of 0xABABABABor 0xEFEFEFEF, you may be seeing the effect of the Poison() macros, seeperlclib.

Read-only optrees

Under ithreads the optree is read only. If you want to enforce this, tocheck for write accesses from buggy code, compile with-DPL_OP_SLAB_ALLOC to enable the OP slab allocator and-DPERL_DEBUG_READONLY_OPS to enable code that allocates op memoryvia mmap, and sets it read-only at run time. Any write access to anop results in a SIGBUS and abort.

This code is intended for development only, and may not be portableeven to all Unix variants. Also, it is an 80% solution, in that itisn't able to make all ops read only. Specifically it

1
Only sets read-only on all slabs of ops at CHECK time, hence opsallocated later via require or eval will be re-write
2
Turns an entire slab of ops read-write if the refcount of any op in theslab needs to be decreased.
3
Turns an entire slab of ops read-write if any op from the slab isfreed.

It's not possible to turn the slabs to read-only after an actionrequiring read-write access, as either can happen during op treebuilding time, so there may still be legitimate write access.

However, as an 80% solution it is still effective, as currently itcatches a write access during the generation of Config.pm, whichmeans that we can't yet build perl with this enabled.

The .i Targets

You can expand the macros in a foo.c file by saying

 make foo.i

which will expand the macros using cpp. Don't be scared by the results.

AUTHOR

This document was originally written by Nathan Torkington, and ismaintained by the perl5-porters mailing list.

Source : perldoc.perl.org - Official documentation for the Perl programming language
Site maintained by Jon Allen (JJ) See the project page for more details
Documentation maintained by the Perl 5 Porters

(Sebelumnya) Walk through the creation of a ...

Description of the Perl regula ... (Berikutnya)

Link Bermanfaat

✺ Kuliah Online ✺ Kode Pos ✺ Kuliah Umum ✺ Kuliah Kelas Ekstensi ✺ Kuliah Jarak Jauh ✺ Kuliah Gratis Beasiswa S1 S2 ✺ Kampus Merdeka Belajar

eduNitas • Konsultan Pendidikan Tinggi (KPT) • PT. Gilland Ganesha • Gilland Group