.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Devel::CallChecker 3pm"
.TH Devel::CallChecker 3pm "2019-02-20" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Devel::CallChecker \- custom op checking attached to subroutines
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    # to generate header prior to XS compilation
\&
\&    perl \-MDevel::CallChecker=callchecker0_h \e
\&        \-e \*(Aqprint callchecker0_h\*(Aq > callchecker0.h
\&
\&    # in Perl part of module
\&
\&    use Devel::CallChecker;
\&
\&    /* in XS */
\&
\&    #include "callchecker0.h"
\&
\&    cv_get_call_checker(cv, &ckfun, &ckobj);
\&    static OP *my_ckfun(pTHX_ OP *o, GV *namegv, SV *ckobj);
\&    cv_set_call_checker(cv, my_ckfun, ckobj);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module makes some new features of the Perl 5.14.0 C \s-1API\s0 available
to \s-1XS\s0 modules running on older versions of Perl.  The features are
centred around the function \f(CW\*(C`cv_set_call_checker\*(C'\fR, which allows \s-1XS\s0
code to attach a magical annotation to a Perl subroutine, resulting in
resolvable calls to that subroutine being mutated at compile time by
arbitrary C code.  This module makes \f(CW\*(C`cv_set_call_checker\*(C'\fR and several
supporting functions available.  (It is possible to achieve the effect
of \f(CW\*(C`cv_set_call_checker\*(C'\fR from \s-1XS\s0 code on much earlier Perl versions,
but it is painful to achieve without the centralised facility.)
.PP
This module provides the implementation of the functions at runtime (on
Perls where they are not provided by the core).  It also, at compile time,
supplies the C header file and link library which provide access to the
functions.  In normal use, \*(L"callchecker0_h\*(R" and \*(L"callchecker_linkable\*(R"
should be called at build time (not authoring time) for the module that
wishes to use the C functions.
.SH "CONSTANTS"
.IX Header "CONSTANTS"
.IP "callchecker0_h" 4
.IX Item "callchecker0_h"
Content of a C header file, intended to be named "\f(CW\*(C`callchecker0.h\*(C'\fR".
It is to be included in \s-1XS\s0 code, and \f(CW\*(C`perl.h\*(C'\fR must be included first.
When the \s-1XS\s0 module is loaded at runtime, the \f(CW\*(C`Devel::CallChecker\*(C'\fR
module must be loaded first.  This will result in the Perl \s-1API\s0 functions
\&\f(CW\*(C`rv2cv_op_cv\*(C'\fR, \f(CW\*(C`ck_entersub_args_list\*(C'\fR, \f(CW\*(C`ck_entersub_args_proto\*(C'\fR,
\&\f(CW\*(C`ck_entersub_args_proto_or_list\*(C'\fR, \f(CW\*(C`cv_get_call_checker\*(C'\fR, and
\&\f(CW\*(C`cv_set_call_checker\*(C'\fR, as defined below and in the Perl 5.14.0 \s-1API,\s0
being available to the \s-1XS\s0 code.
.IP "callchecker_linkable" 4
.IX Item "callchecker_linkable"
List of names of files that must be used as additional objects when
linking an \s-1XS\s0 module that uses the C functions supplied by this module.
This list will be empty on many platforms.
.SH "C FUNCTIONS"
.IX Header "C FUNCTIONS"
.IP "rv2cv_op_cv" 4
.IX Item "rv2cv_op_cv"
Examines an op, which is expected to identify a subroutine at runtime,
and attempts to determine at compile time which subroutine it identifies.
This is normally used during Perl compilation to determine whether
a prototype can be applied to a function call.  \fIcvop\fR is the op
being considered, normally an \f(CW\*(C`rv2cv\*(C'\fR op.  A pointer to the identified
subroutine is returned, if it could be determined statically, and a null
pointer is returned if it was not possible to determine statically.
.Sp
Whether the subroutine is statically identifiable is determined in
accordance with the prevailing standards of the Perl version being used.
The same criteria are used that the core uses to determine whether to
apply a prototype to a subroutine call.  From version 5.11.2 onwards, the
subroutine can be determined if the \s-1RV\s0 that the \f(CW\*(C`rv2cv\*(C'\fR is to operate
on is provided by a suitable \f(CW\*(C`gv\*(C'\fR or \f(CW\*(C`const\*(C'\fR op.  Prior to 5.11.2,
only a \f(CW\*(C`gv\*(C'\fR op will do.  A \f(CW\*(C`gv\*(C'\fR op is suitable if the \s-1GV\s0's \s-1CV\s0 slot
is populated.  A \f(CW\*(C`const\*(C'\fR op is suitable if the constant value must be
an \s-1RV\s0 pointing to a \s-1CV.\s0  Details of this process may change in future
versions of Perl.
.Sp
If the \f(CW\*(C`rv2cv\*(C'\fR op has the \f(CW\*(C`OPpENTERSUB_AMPER\*(C'\fR flag set then no attempt
is made to identify the subroutine statically: this flag is used to
suppress compile-time magic on a subroutine call, forcing it to use
default runtime behaviour.
.Sp
If \fIflags\fR has the bit \f(CW\*(C`RV2CVOPCV_MARK_EARLY\*(C'\fR set, then the handling
of a \s-1GV\s0 reference is modified.  If a \s-1GV\s0 was examined and its \s-1CV\s0 slot was
found to be empty, then the \f(CW\*(C`gv\*(C'\fR op has the \f(CW\*(C`OPpEARLY_CV\*(C'\fR flag set.
If the op is not optimised away, and the \s-1CV\s0 slot is later populated with
a subroutine having a prototype, that flag eventually triggers the warning
\&\*(L"called too early to check prototype\*(R".
.Sp
If \fIflags\fR has the bit \f(CW\*(C`RV2CVOPCV_RETURN_NAME_GV\*(C'\fR set, then instead
of returning a pointer to the subroutine it returns a pointer to the
\&\s-1GV\s0 giving the most appropriate name for the subroutine in this context.
Normally this is just the \f(CW\*(C`CvGV\*(C'\fR of the subroutine, but for an anonymous
(\f(CW\*(C`CvANON\*(C'\fR) subroutine that is referenced through a \s-1GV\s0 it will be the
referencing \s-1GV.\s0  The resulting \f(CW\*(C`GV*\*(C'\fR is cast to \f(CW\*(C`CV*\*(C'\fR to be returned.
A null pointer is returned as usual if there is no statically-determinable
subroutine.
.Sp
.Vb 1
\&    CV *rv2cv_op_cv(OP *cvop, U32 flags)
.Ve
.IP "cv_get_call_checker" 4
.IX Item "cv_get_call_checker"
Retrieves the function that will be used to fix up a call to \fIcv\fR.
Specifically, the function is applied to an \f(CW\*(C`entersub\*(C'\fR op tree for a
subroutine call, not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified
at compile time as \fIcv\fR.
.Sp
The C\-level function pointer is returned in \fI*ckfun_p\fR, and an \s-1SV\s0
argument for it is returned in \fI*ckobj_p\fR.  The function is intended
to be called in this manner:
.Sp
.Vb 1
\&    entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
.Ve
.Sp
In this call, \fIentersubop\fR is a pointer to the \f(CW\*(C`entersub\*(C'\fR op,
which may be replaced by the check function, and \fInamegv\fR is a \s-1GV\s0
supplying the name that should be used by the check function to refer
to the callee of the \f(CW\*(C`entersub\*(C'\fR op if it needs to emit any diagnostics.
It is permitted to apply the check function in non-standard situations,
such as to a call to a different subroutine or to a method call.
.Sp
By default, the function is
Perl_ck_entersub_args_proto_or_list,
and the \s-1SV\s0 parameter is \fIcv\fR itself.  This implements standard
prototype processing.  It can be changed, for a particular subroutine,
by \*(L"cv_set_call_checker\*(R".
.Sp
.Vb 2
\&    void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
\&            SV **ckobj_p)
.Ve
.IP "cv_set_call_checker" 4
.IX Item "cv_set_call_checker"
Sets the function that will be used to fix up a call to \fIcv\fR.
Specifically, the function is applied to an \f(CW\*(C`entersub\*(C'\fR op tree for a
subroutine call, not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified
at compile time as \fIcv\fR.
.Sp
The C\-level function pointer is supplied in \fIckfun\fR, and an \s-1SV\s0 argument
for it is supplied in \fIckobj\fR.  The function is intended to be called
in this manner:
.Sp
.Vb 1
\&    entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
.Ve
.Sp
In this call, \fIentersubop\fR is a pointer to the \f(CW\*(C`entersub\*(C'\fR op,
which may be replaced by the check function, and \fInamegv\fR is a \s-1GV\s0
supplying the name that should be used by the check function to refer
to the callee of the \f(CW\*(C`entersub\*(C'\fR op if it needs to emit any diagnostics.
It is permitted to apply the check function in non-standard situations,
such as to a call to a different subroutine or to a method call.
.Sp
The current setting for a particular \s-1CV\s0 can be retrieved by
\&\*(L"cv_get_call_checker\*(R".
.Sp
.Vb 2
\&    void cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
\&            SV *ckobj)
.Ve
.IP "ck_entersub_args_list" 4
.IX Item "ck_entersub_args_list"
Performs the default fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR
op tree.  This consists of applying list context to each of the
argument ops.  This is the standard treatment used on a call marked
with \f(CW\*(C`&\*(C'\fR, or a method call, or a call through a subroutine reference,
or any other call where the callee can't be identified at compile time,
or a call where the callee has no prototype.
.Sp
.Vb 1
\&    OP *ck_entersub_args_list(OP *entersubop)
.Ve
.IP "ck_entersub_args_proto" 4
.IX Item "ck_entersub_args_proto"
Performs the fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR op tree
based on a subroutine prototype.  This makes various modifications to
the argument ops, from applying context up to inserting \f(CW\*(C`refgen\*(C'\fR ops,
and checking the number and syntactic types of arguments, as directed by
the prototype.  This is the standard treatment used on a subroutine call,
not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified at compile time
and has a prototype.
.Sp
\&\fIprotosv\fR supplies the subroutine prototype to be applied to the call.
It may be a normal defined scalar, of which the string value will be used.
Alternatively, for convenience, it may be a subroutine object (a \f(CW\*(C`CV*\*(C'\fR
that has been cast to \f(CW\*(C`SV*\*(C'\fR) which has a prototype.  The prototype
supplied, in whichever form, does not need to match the actual callee
referenced by the op tree.
.Sp
If the argument ops disagree with the prototype, for example by having
an unacceptable number of arguments, a valid op tree is returned anyway.
The error is reflected in the parser state, normally resulting in a single
exception at the top level of parsing which covers all the compilation
errors that occurred.  In the error message, the callee is referred to
by the name defined by the \fInamegv\fR parameter.
.Sp
.Vb 2
\&    OP *ck_entersub_args_proto(OP *entersubop, GV *namegv,
\&            SV *protosv)
.Ve
.IP "ck_entersub_args_proto_or_list" 4
.IX Item "ck_entersub_args_proto_or_list"
Performs the fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR op tree either
based on a subroutine prototype or using default list-context processing.
This is the standard treatment used on a subroutine call, not marked
with \f(CW\*(C`&\*(C'\fR, where the callee can be identified at compile time.
.Sp
\&\fIprotosv\fR supplies the subroutine prototype to be applied to the call,
or indicates that there is no prototype.  It may be a normal scalar,
in which case if it is defined then the string value will be used
as a prototype, and if it is undefined then there is no prototype.
Alternatively, for convenience, it may be a subroutine object (a \f(CW\*(C`CV*\*(C'\fR
that has been cast to \f(CW\*(C`SV*\*(C'\fR), of which the prototype will be used if it
has one.  The prototype (or lack thereof) supplied, in whichever form,
does not need to match the actual callee referenced by the op tree.
.Sp
If the argument ops disagree with the prototype, for example by having
an unacceptable number of arguments, a valid op tree is returned anyway.
The error is reflected in the parser state, normally resulting in a single
exception at the top level of parsing which covers all the compilation
errors that occurred.  In the error message, the callee is referred to
by the name defined by the \fInamegv\fR parameter.
.Sp
.Vb 2
\&    OP *ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
\&            SV *protosv)
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
B::CallChecker,
Devel::CallParser,
\&\*(L"cv_set_call_checker\*(R" in perlapi
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew Main (Zefram) <zefram@fysh.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2011, 2012, 2013, 2015, 2017
Andrew Main (Zefram) <zefram@fysh.org>
.SH "LICENSE"
.IX Header "LICENSE"
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.