NAME
XS::MagicExt - Provides PERL_MAGIC_ext manipulators for XS modules
VERSION
This document describes XS::MagicExt version 0.05.
SYNOPSIS
# in Makefile.PL
requires_xs 'XS::MagicExt'; # done by Module::Install::XSUtil
# in YourModule.pm
use XS::MagicExt;
/* Then, in YourModule.xs */
#include "magic_ext.h"
static MGVTBL id;
/* ... */
void foo(pTHX_ SV* sv){
SV* obj = newSViv(42);
/* ... */
mg = mgx_attach(sv, &id, obj);
mg = mgx_find(sv, &id);
mg = MGX_FIND(sv, &id);
mg = mgx_get(sv, &id);
if(SvOK(MG_obj(mg))){
/* ... */
}
mgx_detach(sv, &id);
}DESCRIPTION
XS::MagicExt provides MAGIC manipulators for XS modules.
MAGIC manipulators are an interface to sv_magicext(), mg_find(), and sv_unmagic(), which distinguish magic identities from others' MAGICs by MGVTBL.
FUNCTIONS
MAGIC* mgx_attach_with_ptr(SV* sv, MGVTBL* id, SV* obj, void* ptr, I32 len)
Attaches a MAGIC identified by id to sv with obj and ptr / len.
Similar to sv_magicext(sv, obj, PERL_MAGIC_ext, id, ptr, len), but does not increase the refcount of obj.
MAGIC* mgx_attach_with_sv(SV* sv, MGVTBL* id, SV* obj, SV* data)
Attaches a MAGIC identified by id to sv with obj and data, not increasing the refcount of data.
The same as mgx_attach_with_ptr(sv, id, obj, (SV*)ptr, HEf_SVKEY).
MAGIC* mgx_attach(SV* sv, MGVTBL* id, SV* obj)
Attaches a MAGIC identified by id to sv with obj.
The same as mgx_attach_with_ptr(sv, id, obj, NULL, 0).
MAGIC* mgx_find(SV* sv, const MGVTBL* id)
Finds a MAGIC identified by id.
If not found, it will return NULL.
MAGIC* mgx_get(SV* sv, const MGVTBL* id)
Finds a MAGIC identified by id.
If not found, it will die.
void mgx_detach(SV* sv, const MGVTBL* id)
Removes all the MAGICs identified by id.
MACROS
MAGIC* MGX_FIND(SV* sv, const MGVTBL* id)
Checks if sv has any MAGICs, and finds a MAGIC like mgx_find().
SV* MG_obj(MAGIC* mg)
The same as mg->mg_obj.
U16 MG_private(MAGIC* mg)
The same as mg->mg_private.
char* MG_ptr(mg)
The same as mg->mg_ptr.
char* MG_len(mg)
The same as mg->mg_len.
void* MG_vptr(mg)
The same as (void*)mg->mg_ptr.
SV* MG_sv(mg)
The same as (SV*)mg->mg_ptr.
MG_len(mg) must be HEf_SVKEY.
SV* MG_sv_set(mg, sv)
Sets sv to MG_sv(mg), and MG_len(mg) = HEf_SVKEY.
bool MG_ptr_is_sv(mg)
The same as MG_len(mg) == HEf_SVKEY.
DEPENDENCIES
Perl 5.8.1 or later, and a C compiler.
BUGS
No bugs have been reported.
Please report any bugs or feature requests to the author.
SEE ALSO
magic_ext.h.
sv.c.
mg.h.
mg.c.
AUTHOR
Goro Fuji (gfx) <gfuji(at)cpan.org>.
LICENSE AND COPYRIGHT
Copyright (c) 2009, Goro Fuji (gfx). Some rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.