.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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 "XML::LibXML::Devel 3"
.TH XML::LibXML::Devel 3 "2016-07-24" "perl v5.16.3" "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"
XML::LibXML::Devel \- makes functions from LibXML.xs available
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&  /**********************************************
\&   * C functions you want to access
\&   */
\&  xmlNode *return_node();
\&  void receive_node(xmlNode *);
\&
\&  ###############################################
\&  # XS Code
\&  void *
\&    xs_return_node
\&    CODE:
\&        RETVAL = return_node();
\&    OUTPUT:
\&        RETVAL
\&
\&  void
\&    xs_receive_node
\&        void *n
\&    CODE:
\&        receive_node(n);
\&
\&  ###############################################
\&  # Perl code
\&  use XML::LibXML::Devel;
\&
\&  sub return_node
\&  {
\&    my $raw_node = xs_return_node();
\&    my $node = XML::LibXML::Devel::node_to_perl($raw_node);
\&    XML::LibXML::Devel::refcnt_inc($raw_node);
\&    return $node;
\&  }
\&
\&  sub receive_node
\&  {
\&    my ($node) = @_;
\&    my $raw_node = XML::LibXML::Devel::node_from_perl($node);
\&    xs_receive_node($raw_node);
\&    XML::LibXML::Devel::refcnt_inc($raw_node);
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`XML::LibXML::Devel\*(C'\fR makes functions from LibXML.xs available that
are needed to wrap libxml2 nodes in and out of XML::LibXML::Nodes.
This gives cleaner dependencies than using LibXML.so directly.
.PP
To \s-1XS\s0 a library that uses libxml2 nodes the first step is to
do this so that xmlNodePtr is passed as void *. These raw nodes
are then turned into libxml nodes by using this \f(CW\*(C`Devel\*(C'\fR functions.
.PP
Be aware that this module is currently rather experimental. The function
names may change if I \s-1XS\s0 more functions and introduce a reasonable
naming convention.
.PP
Be also aware that this module is a great tool to cause segfaults and
introduce memory leaks. It does however provide a partial cure by making
\&\f(CW\*(C`xmlMemUsed\*(C'\fR available as \f(CW\*(C`mem_used\*(C'\fR.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "\s-1NODE MANAGEMENT\s0"
.IX Subsection "NODE MANAGEMENT"
.IP "node_to_perl" 1
.IX Item "node_to_perl"
.Vb 1
\&  node_to_perl($raw_node);
.Ve
.Sp
Returns a LibXML::Node object. This has a proxy node with a reference
counter and an owner attached. The raw node will be deleted as soon
as the reference counter reaches zero.
If the C library is keeping a
pointer to the raw node, you need to call refcnt_inc immediately.
You also need to replace xmlFreeNode by a call to refcnt_dec.
.IP "node_to_perl" 1
.IX Item "node_to_perl"
.Vb 1
\&  node_from_perl($node);
.Ve
.Sp
Returns a raw node. This is a void * pointer and you can do nothing
but passing it to functions that treat it as an xmlNodePtr. The
raw node will be freed as soon as its reference counter reaches zero.
If the C library is keeping a
pointer to the raw node, you need to call refcnt_inc immediately.
You also need to replace xmlFreeNode by a call to refcnt_dec.
.IP "refcnt_inc" 1
.IX Item "refcnt_inc"
.Vb 1
\&  refcnt_inc($raw_node);
.Ve
.Sp
Increments the raw nodes reference counter. The raw node must already
be known to perl to have a reference counter.
.IP "refcnt_dec" 1
.IX Item "refcnt_dec"
.Vb 1
\&  refcnt_dec($raw_node);
.Ve
.Sp
Decrements the raw nodes reference counter and returns the value it
had before. if the counter becomes zero or less,
this method will free the proxy node holding the reference counter.
If the node is part of a
subtree, refcnt_dec will fix the reference counts and delete
the subtree if it is not required any more.
.IP "refcnt" 1
.IX Item "refcnt"
.Vb 1
\&  refcnt($raw_node);
.Ve
.Sp
Returns the value of the reference counter.
.IP "fix_owner" 1
.IX Item "fix_owner"
.Vb 1
\&  fix_owner($raw_node, $raw_parent);
.Ve
.Sp
This functions fixes the reference counts for an entire subtree.
it is very important to fix an entire subtree after node operations
where the documents or the owner node may get changed. this method is
aware about nodes that already belong to a certain owner node.
.SS "\s-1MEMORY DEBUGGING\s0"
.IX Subsection "MEMORY DEBUGGING"
.ie n .IP "$ENV{\s-1DEBUG_MEMORY\s0}" 1
.el .IP "\f(CW$ENV\fR{\s-1DEBUG_MEMORY\s0}" 1
.IX Item "$ENV{DEBUG_MEMORY}"
.Vb 2
\&  BEGIN {$ENV{DEBUG_MEMORY} = 1;};
\&  use XML::LibXML;
.Ve
.Sp
This turns on libxml2 memory debugging. It must be set before
XML::LibXML is loaded.
.IP "mem_used" 1
.IX Item "mem_used"
.Vb 1
\&  mem_used();
.Ve
.Sp
Returns the number of bytes currently allocated.
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None by default.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This was created to support the needs of Apache2::ModXml2. So this
can serve as an example.
.SH "AUTHOR"
.IX Header "AUTHOR"
Joachim Zobel <jz\-2011@heute\-morgen.de>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2011 by Joachim Zobel
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.1 or,
at your option, any later version of Perl 5 you may have available.