This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Document gv_init*
authorFather Chrysostomos <sprout@cpan.org>
Fri, 23 Sep 2011 01:21:28 +0000 (18:21 -0700)
committerFather Chrysostomos <sprout@cpan.org>
Thu, 6 Oct 2011 20:00:57 +0000 (13:00 -0700)
embed.fnc
gv.c
proto.h

index 4b1ee0a..4ebe6f3 100644 (file)
--- a/embed.fnc
+++ b/embed.fnc
@@ -452,6 +452,8 @@ Ap  |void   |gv_fullname4   |NN SV* sv|NN const GV* gv|NULLOK const char* prefix|bool
 pMox   |GP *   |newGP          |NN GV *const gv
 pX     |void   |cvgv_set       |NN CV* cv|NULLOK GV* gv
 pX     |void   |cvstash_set    |NN CV* cv|NULLOK HV* stash
+Amd    |void   |gv_init        |NN GV* gv|NULLOK HV* stash \
+                                |NN const char* name|STRLEN len|int multi
 Ap     |void   |gv_init_sv     |NN GV* gv|NULLOK HV* stash|NN SV* namesv|int multi|U32 flags
 Ap     |void   |gv_init_pv     |NN GV* gv|NULLOK HV* stash|NN const char* name \
                                 |int multi|U32 flags
diff --git a/gv.c b/gv.c
index 4bb3625..5bc52d1 100644 (file)
--- a/gv.c
+++ b/gv.c
@@ -248,6 +248,46 @@ Perl_cvstash_set(pTHX_ CV *cv, HV *st)
        Perl_sv_add_backref(aTHX_ MUTABLE_SV(st), MUTABLE_SV(cv));
 }
 
+/*
+=for apidoc gv_init_pvn
+
+Converts a scalar into a typeglob.  This is an incoercible typeglob;
+assigning a reference to it will assign to one of its slots, instead of
+overwriting it as happens with typeglobs created by SvSetSV.  Converting
+any scalar that is SvOK() may produce unpredictable results and is reserved
+for perl's internal use.
+
+C<gv> is the scalar to be converted.
+
+C<stash> is the parent stash/package, if any.
+
+C<name> and C<len> give the name.  C<flags> can be set to SVf_UTF8 for a
+UTF8 string, or the return value of SvUTF8(sv).  The name must be unqualified; that is, it must not include the package name.  If C<gv> is a
+stash element, it is the caller's responsibility to ensure that the name
+passed to this function matches the name of the element.  If it does not
+match, perl's internal bookkeeping will get out of sync.
+
+C<multi>, when set to a true value, means to pretend that the GV has been
+seen before (i.e., suppress "Used once" warnings).
+
+=for apidoc gv_init
+
+The old form of gv_init_pvn().  It does not work with UTF8 strings, as it
+has no flags parameter.
+
+=for apidoc gv_init_pv
+
+Same as gv_init_pvn(), but takes a nul-terminated string for the name
+instead of separate char * and length parameters.
+
+=for apidoc gv_init_sv
+
+Same as gv_init_pvn(), but takes an SV * for the name instead of separate
+char * and length parameters.  C<flags> is currently unused.
+
+=cut
+*/
+
 void
 Perl_gv_init_sv(pTHX_ GV *gv, HV *stash, SV* namesv, int multi, U32 flags)
 {
diff --git a/proto.h b/proto.h
index 054387a..2e32f5f 100644 (file)
--- a/proto.h
+++ b/proto.h
@@ -1256,6 +1256,10 @@ PERL_CALLCONV void       Perl_gv_fullname4(pTHX_ SV* sv, const GV* gv, const char* pre
 PERL_CALLCONV CV*      Perl_gv_handler(pTHX_ HV* stash, I32 id)
                        __attribute__warn_unused_result__;
 
+/* PERL_CALLCONV void  gv_init(pTHX_ GV* gv, HV* stash, const char* name, STRLEN len, int multi)
+                       __attribute__nonnull__(pTHX_1)
+                       __attribute__nonnull__(pTHX_3); */
+
 PERL_CALLCONV void     Perl_gv_init_pv(pTHX_ GV* gv, HV* stash, const char* name, int multi, U32 flags)
                        __attribute__nonnull__(pTHX_1)
                        __attribute__nonnull__(pTHX_3);