XML::LibXML::Devel(3)

✨ NAME ✨

XML::LibXML::Devel — makes functions from LibXML.xs available 💅

(also hi bestie, this is the manual page for XML::LibXML::Devel, section 3 of the User Contributed Perl Documentation, and it's a lot 🫶)

---

🌸 SYNOPSIS 🌸

okay so here's the whole vibe — C side, XS side, Perl side:

/**********************************************
 * 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);
}

---

💜 DESCRIPTION 💜

So XML::LibXML::Devel makes functions from LibXML.xs available that are needed to wrap libxml2 nodes in and out of XML::LibXML::Nodes. The whole point? It gives you cleaner dependencies than using LibXML.so directly. iconic behaviour honestly 💅

To XS a library that uses libxml2 nodes, the first step is to do this so that xmlNodePtr is passed as void *. Those raw nodes then get turned into libxml nodes by using these "Devel" functions. no cap.

bestie, real talk: this module is currently rather experimental. The function names may change if I XS more functions and introduce a reasonable naming convention. so don't get too attached to the names okay 😭

also, be aware that this module is a great tool to cause segfaults and introduce memory leaks. 💀 It does however provide a partial cure by making xmlMemUsed available as mem_used.

---

🎀 FUNCTIONS 🎀

🦋 NODE MANAGEMENT 🦋

node_to_perl

node_to_perl($raw_node);

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

node_to_perl

ok so the original heading for this one literally says node_to_perl again — not me messing up, we're keeping it exactly as the source has it 🙈

node_from_perl($node);

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. same energy, different direction 🔥

refcnt_inc

refcnt_inc($raw_node);

Increments the raw nodes reference counter. The raw node must already be known to perl to have a reference counter. 🫶

refcnt_dec

refcnt_dec($raw_node);

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. lowkey doing the most, highkey necessary 💅

refcnt

refcnt($raw_node);

Returns the value of the reference counter. that's it, that's the function ✨

fix_owner

fix_owner($raw_node, $raw_parent);

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. do not skip this one bestie, it's giving self-care for your memory model 🧚

🌈 MEMORY DEBUGGING 🌈

$ENV{DEBUG_MEMORY}

BEGIN {$ENV{DEBUG_MEMORY} = 1;};
use XML::LibXML;

This turns on libxml2 memory debugging. It must be set before XML::LibXML is loaded. timing is everything, queen 👑

mem_used

mem_used();

Returns the number of bytes currently allocated. 📊

⭐ EXPORT ⭐

None by default.

---

🌟 SEE ALSO 🌟

This was created to support the needs of Apache2::ModXml2. So this can serve as an example. 🫶

---

👑 AUTHOR 👑

Joachim Zobel <jz-2011@heute-morgen.de>

---

💖 COPYRIGHT AND LICENSE 💖

Copyright (C) 2011 by Joachim Zobel

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.

---

and that's the whole page bestie, tysm for reading 💜 this was XML::LibXML::Devel from perl v5.42.2, dated 2026-05-25 — go forth and wrap those nodes responsibly 🎀✨