From: Steve Hay Date: Fri, 29 Oct 2004 14:12:02 +0000 (+0000) Subject: Document sv_magic() changes brought about by sv_magicext() X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=2d8d5d5aa55d3bc73a36db1fc2d8bcfe8bb20516;p=p5sagit%2Fp5-mst-13.2.git Document sv_magic() changes brought about by sv_magicext() Change 14335 made sv_magic() a wrapper to a new sv_magicext(), but didn't update the documentation for sv_magic() to reflect the changed handling of the name/namlen arguments. Also correct a couple of typos, and mention sv_magicext() in perlguts. p4raw-id: //depot/perl@23432 --- diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 4de6b5e..896dcc4 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -4287,6 +4287,9 @@ Found in file sv.c Adds magic to an SV. First upgrades C to type C if necessary, then adds a new magic item of type C to the head of the magic list. +See C (which C now calls) for a description of the +handling of the C and C arguments. + void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) =for hackers @@ -4295,18 +4298,18 @@ Found in file sv.c =item sv_magicext Adds magic to an SV, upgrading it if necessary. Applies the -supplied vtable and returns pointer to the magic added. +supplied vtable and returns a pointer to the magic added. -Note that sv_magicext will allow things that sv_magic will not. -In particular you can add magic to SvREADONLY SVs and and more than -one instance of the same 'how' +Note that C will allow things that C will not. +In particular, you can add magic to SvREADONLY SVs, and add more than +one instance of the same 'how'. -I C is greater then zero then a savepvn() I of C is stored, -if C is zero then C is stored as-is and - as another special -case - if C<(name && namelen == HEf_SVKEY)> then C is assumed to contain -an C and has its REFCNT incremented +If C is greater than zero then a C I of C is +stored, if C is zero then C is stored as-is and - as another +special case - if C<(name && namlen == HEf_SVKEY)> then C is assumed +to contain an C and is stored as-is with its REFCNT incremented. -(This is now used as a subroutine by sv_magic.) +(This is now used as a subroutine by C.) MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen ) @@ -4755,8 +4758,9 @@ function if the source SV needs to be reused. Does not handle 'set' magic. Loosely speaking, it performs a copy-by-value, obliterating any previous content of the destination. If the C parameter has the C bit set, will C on -C if appropriate, else not. C and C are -implemented in terms of this function. +C if appropriate, else not. If the C parameter has the +C bit set then the buffers of temps will not be stolen. +and C are implemented in terms of this function. You probably want to use one of the assortment of wrappers, such as C, C, C and diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 99c79d0..5eb46d2 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -926,8 +926,11 @@ SV. The C and C arguments are used to associate a string with the magic, typically the name of a variable. C is stored in the -C field and if C is non-null and C E= 0 a malloc'd -copy of the name is stored in C field. +C field and if C is non-null then either a C copy of +C or C itself is stored in the C field, depending on +whether C is greater than zero or equal to zero respectively. As a +special case, if C<(name && namlen == HEf_SVKEY)> then C is assumed +to contain an C and is stored as-is with its REFCNT incremented. The sv_magic function uses C to determine which, if any, predefined "Magic Virtual Table" should be assigned to the C field. @@ -944,6 +947,9 @@ count of the C object is incremented. If it is the same, or if the C argument is C, or if it is a NULL pointer, then C is merely stored, without the reference count being incremented. +See also C in L for a more flexible way to add magic +to an SV. + There is also a function to add magic to an C: void hv_magic(HV *hv, GV *gv, int how); diff --git a/sv.c b/sv.c index aec9802..f3575ad 100644 --- a/sv.c +++ b/sv.c @@ -5314,18 +5314,18 @@ Perl_newSV(pTHX_ STRLEN len) =for apidoc sv_magicext Adds magic to an SV, upgrading it if necessary. Applies the -supplied vtable and returns pointer to the magic added. +supplied vtable and returns a pointer to the magic added. -Note that sv_magicext will allow things that sv_magic will not. -In particular you can add magic to SvREADONLY SVs and and more than -one instance of the same 'how' +Note that C will allow things that C will not. +In particular, you can add magic to SvREADONLY SVs, and add more than +one instance of the same 'how'. -I C is greater then zero then a savepvn() I of C is stored, -if C is zero then C is stored as-is and - as another special -case - if C<(name && namelen == HEf_SVKEY)> then C is assumed to contain -an C and has its REFCNT incremented +If C is greater than zero then a C I of C is +stored, if C is zero then C is stored as-is and - as another +special case - if C<(name && namlen == HEf_SVKEY)> then C is assumed +to contain an C and is stored as-is with its REFCNT incremented. -(This is now used as a subroutine by sv_magic.) +(This is now used as a subroutine by C.) =cut */ @@ -5404,6 +5404,9 @@ Perl_sv_magicext(pTHX_ SV* sv, SV* obj, int how, MGVTBL *vtable, Adds magic to an SV. First upgrades C to type C if necessary, then adds a new magic item of type C to the head of the magic list. +See C (which C now calls) for a description of the +handling of the C and C arguments. + =cut */