|
All of Perl's internal functions which will be exposed to the outside world are be prefixed
by Perl_ so that they will not conflict with XS functions or functions used in a
program in which Perl is embedded. Similarly, all global variables begin with PL_.
(By convention, static functions start with S_)
Inside the Perl core, you can get at the functions either with or without the Perl_
prefix, thanks to a bunch of defines that live in embed.h. This header file is
generated automatically from embed.pl. embed.pl also creates the prototyping
header files for the internal functions, generates the documentation and a lot of other bits
and pieces. It's important that when you add a new function to the core or change an existing
one, you change the data in the table at the end of embed.pl as well. Here's a sample
entry from that table:
Apd |SV** |av_fetch |AV* ar|I32 key|I32 lval
|
|
The second column is the return type, the third column the name. Columns after that are the
arguments. The first column is a set of flags:
- A
- This function is a part of the public API.
- p
- This function has a
Perl_ prefix; ie, it is defined as Perl_av_fetch
- d
- This function has documentation using the
apidoc feature which we'll look
at in a second.
Other available flags are:
- s
- This is a static function and is defined as
S_whatever, and usually called
within the sources as whatever(...).
- n
- This does not use
aTHX_ and pTHX to pass interpreter context.
(See perlguts/Background
and PERL_IMPLICIT_CONTEXT.)
- r
- This function never returns;
croak, exit and friends.
- f
-
This function takes a variable number of arguments, printf style. The
argument list should end with ..., like this:
Afprd |void |croak |const char* pat|...
|
|
- M
- This function is part of the experimental development API, and may change or disappear
without notice.
- o
- This function should not have a compatibility macro to define, say,
Perl_parse
to parse. It must be called as Perl_parse.
- j
- This function is not a member of
CPerlObj. If you don't know what this
means, don't use it.
- x
- This function isn't exported out of the Perl core.
If you edit embed.pl, you will need to run make regen_headers to force
a rebuild of embed.h and other auto-generated files.
If you are printing IVs, UVs, or NVS instead of the stdio(3) style formatting codes like %d,
%ld, %f, you should use the following macros for portability
IVdf IV in decimal
UVuf UV in decimal
UVof UV in octal
UVxf UV in hexadecimal
NVef NV %e-like
NVff NV %f-like
NVgf NV %g-like
|
|
These will take care of 64-bit integers and long doubles. For example:
printf("IV is %"IVdf"\n", iv);
|
|
The IVdf will expand to whatever is the correct format for the IVs.
If you are printing addresses of pointers, use UVxf combined with PTR2UV(), do not use %lx
or %p.
Because pointer size does not necessarily equal integer size, use the follow macros to do
it right.
PTR2UV(pointer)
PTR2IV(pointer)
PTR2NV(pointer)
INT2PTR(pointertotype, integer)
|
|
For example:
IV iv = ...;
SV *sv = INT2PTR(SV*, iv);
|
|
and
AV *av = ...;
UV uv = PTR2UV(av);
|
|
There's an effort going on to document the internal functions and automatically produce
reference manuals from them - perlapi
is one such manual which details all the functions which are available to XS writers. perlintern is the
autogenerated manual for the functions which are not part of the API and are supposedly for
internal use only.
Source documentation is created by putting POD comments into the C source, like this:
/*
=for apidoc sv_setiv
Copies an integer into the given SV. Does not handle 'set' magic. See
C<sv_setiv_mg>.
=cut
*/
|
|
Please try and supply some documentation if you add functions to the Perl core.
|
|
