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

#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; U32 mgs_flags; I32 mgs_ss_ix; }; /* 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;

    PERL_ARGS_ASSERT_SAVE_MAGIC;

    assert(SvMAGICAL(sv));
    /* 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_flags = SvMAGICAL(sv) | SvREADONLY(sv);
    mgs->mgs_ss_ix = PL_savestack_ix;   /* points after the saved destructor */

    SvMAGICAL_off(sv);
    SvREADONLY_off(sv);
    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.

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).

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

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.