++ed by:

167 PAUSE users
144 non-PAUSE users.

Andrew Main (Zefram)
and 1 contributors

Magical Functions

"Magic" is special data attached to SV structures in order to give them "magical" properties. When any Perl code tries to read from, or assign to, an SV marked as magical, it calls the 'get' or 'set' function associated with that SV's magic. A get is called prior to reading an SV, in order to give it a chance to update its internal value (get on $. writes the line number of the last read filehandle into to the SV's IV slot), while set is called after an SV has been written to, in order to allow it to make use of its changed value (set on $/ copies the SV's new value to the PL_rs global variable).

Magic is implemented as a linked list of MAGIC structures attached to the SV. Each MAGIC struct holds the type of the magic, a pointer to an array of functions that implement the get(), set(), length() etc functions, plus space for some flags and pointers. For example, a tied variable has a MAGIC structure that contains a pointer to the object associated with the tie.


#include "EXTERN.h" #define PERL_IN_MG_C #include "perl.h"

#if defined(HAS_GETGROUPS) || defined(HAS_SETGROUPS) # ifdef I_GRP # include <grp.h> # endif #endif

#if defined(HAS_SETGROUPS) # ifndef NGROUPS # define NGROUPS 32 # endif #endif

#ifdef __hpux # include <sys/pstat.h> #endif

#ifdef HAS_PRCTL_SET_NAME # include <sys/prctl.h> #endif

#if defined(HAS_SIGACTION) && defined(SA_SIGINFO) Signal_t Perl_csighandler(int sig, siginfo_t *, void *); #else Signal_t Perl_csighandler(int sig); #endif

#ifdef __Lynx__ /* Missing protos on LynxOS */ void setruid(uid_t id); void seteuid(uid_t id); void setrgid(uid_t id); void setegid(uid_t id); #endif

/* * Use the "DESTRUCTOR" scope cleanup to reinstate magic. */

struct magic_state { SV* mgs_sv; I32 mgs_ss_ix; U32 mgs_magical; bool mgs_readonly; bool mgs_bumped; }; /* MGS is typedef'ed to struct magic_state in perl.h */

STATIC void S_save_magic(pTHX_ I32 mgs_ix, SV *sv) { dVAR; MGS* mgs; bool bumped = FALSE;


    /* we shouldn't really be called here with RC==0, but it can sometimes
     * happen via mg_clear() (which also shouldn't be called when RC==0,
     * but it can happen). Handle this case gracefully(ish) by not RC++
     * and thus avoiding the resultant double free */
    if (SvREFCNT(sv) > 0) {
    /* guard against sv getting freed midway through the mg clearing,
     * by holding a private reference for the duration. */
        bumped = TRUE;

    /* Turning READONLY off for a copy-on-write scalar (including shared
       hash keys) is a bad idea.  */
    if (SvIsCOW(sv))
      sv_force_normal_flags(sv, 0);

    SAVEDESTRUCTOR_X(S_restore_magic, INT2PTR(void*, (IV)mgs_ix));

    mgs = SSPTR(mgs_ix, MGS*);
    mgs->mgs_sv = sv;
    mgs->mgs_magical = SvMAGICAL(sv);
    mgs->mgs_readonly = SvREADONLY(sv) != 0;
    mgs->mgs_ss_ix = PL_savestack_ix;   /* points after the saved destructor */
    mgs->mgs_bumped = bumped;

    if (!(SvFLAGS(sv) & (SVf_IOK|SVf_NOK|SVf_POK))) {
        /* No public flags are set, so promote any private flags to public.  */
        SvFLAGS(sv) |= (SvFLAGS(sv) & (SVp_IOK|SVp_NOK|SVp_POK)) >> PRIVSHIFT;

/* =for apidoc mg_magical

Turns on the magical status of an SV. See sv_magic.

Do magic after a value is retrieved from the SV. See sv_magic.

Do magic after a value is assigned to the SV. See sv_magic.

Report on the SV's length. See sv_magic.

Clear something magical that the SV represents. See sv_magic.

Finds the magic pointer for type matching the SV. See sv_magic.

Finds the magic pointer of type with the given vtbl for the SV. See sv_magicext.

Copies the magic from one SV to another. See sv_magic.

Copy some of the magic from an existing SV to new localized version of that SV. Container magic (eg %ENV, $1, tie) gets copied, value magic doesn't (eg taint, pos).

If setmagic is false then no set magic will be called on the new (empty) SV. This typically means that assignment will soon follow (e.g. 'local $x = $y'), and that will handle the magic.

Free any magic storage used by the SV. See sv_magic.

Remove any magic of type how from the SV sv. See "sv_magic".

Invoke a magic method (like FETCH).

sv and mg are the tied thingy and the tie magic.

meth is the name of the method to call.

argc is the number of args (in addition to $self) to pass to the method.

The flags can be:

    G_DISCARD     invoke method with G_DISCARD flag and don't
                  return a value
    G_UNDEF_FILL  fill the stack with argc pointers to

The arguments themselves are any values following the flags argument.

Returns the SV (if any) returned by the method, or NULL on failure.

Triggered by a store to %^H, records the key/value pair to PL_compiling.cop_hints_hash. It is assumed that hints aren't storing anything that would need a deep copy. Maybe we should warn if we find a reference.

Triggered by a delete from %^H, records the key to PL_compiling.cop_hints_hash.

Triggered by clearing %^H, resets PL_compiling.cop_hints_hash.