This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
"thread failed to start: " is better than "Died:".
[perl5.git] / pod / perlapi.pod
index 0a11945..0842096 100644 (file)
@@ -297,6 +297,8 @@ Sort an array. Here is an example:
 
     sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
 
+See lib/sort.pm for details about controlling the sorting algorithm.
+
        void    sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp)
 
 =for hackers
@@ -576,6 +578,16 @@ method, similar to C<use Foo::Bar VERSION LIST>.
 =for hackers
 Found in file op.c
 
+=item nothreadhook
+
+Stub that provides thread hook for perl_destruct when there are
+no threads.
+
+       int     nothreadhook()
+
+=for hackers
+Found in file perl.c
+
 =item perl_alloc
 
 Allocates a new Perl interpreter.  See L<perlembed>.
@@ -1088,6 +1100,7 @@ NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
 hash buckets that happen to be in use.  If you still need that esoteric
 value, you can get it through the macro C<HvFILL(tb)>.
 
+
        I32     hv_iterinit(HV* tb)
 
 =for hackers
@@ -1118,6 +1131,14 @@ Found in file hv.c
 
 Returns entries from a hash iterator.  See C<hv_iterinit>.
 
+You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
+iterator currently points to, without losing your place or invalidating your
+iterator.  Note that in this case the current entry is deleted from the hash
+with your iterator holding the last reference to it.  Your iterator is flagged
+to free the entry on the next call to C<hv_iternext>, so you must not discard
+your iterator immediately else the entry will leak - call C<hv_iternext> to
+trigger the resource deallocation.
+
        HE*     hv_iternext(HV* tb)
 
 =for hackers
@@ -1133,6 +1154,26 @@ operation.
 =for hackers
 Found in file hv.c
 
+=item hv_iternext_flags
+
+Returns entries from a hash iterator.  See C<hv_iterinit> and C<hv_iternext>.
+The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
+set the placeholders keys (for restricted hashes) will be returned in addition
+to normal keys. By default placeholders are automatically skipped over.
+Currently a placeholder is implemented with a value that is literally
+<&Perl_sv_undef> (a regular C<undef> value is a normal read-write SV for which
+C<!SvOK> is false). Note that the implementation of placeholders and
+restricted hashes may change, and the implementation currently is
+insufficiently abstracted for any change to be tidy.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+       HE*     hv_iternext_flags(HV* tb, I32 flags)
+
+=for hackers
+Found in file hv.c
+
 =item hv_iterval
 
 Returns the value from the current position of the hash iterator.  See
@@ -1446,6 +1487,16 @@ memory is zeroed with C<memzero>.
 =for hackers
 Found in file handy.h
 
+=item Poison
+
+Fill up memory with a pattern (byte 0xAB over and over again) that
+hopefully catches attempts to access uninitialized memory.
+
+       void    Poison(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
 =item Renew
 
 The XSUB-writer's interface to the C C<realloc> function.
@@ -1476,30 +1527,34 @@ Found in file handy.h
 
 =item savepv
 
-Copy a string to a safe spot.  This does not use an SV.
+Perl's version of C<strdup()>. Returns a pointer to a newly allocated
+string which is a duplicate of C<pv>. The size of the string is
+determined by C<strlen()>. The memory allocated for the new string can
+be freed with the C<Safefree()> function.
 
-       char*   savepv(const char* sv)
+       char*   savepv(const char* pv)
 
 =for hackers
 Found in file util.c
 
 =item savepvn
 
-Copy a string to a safe spot.  The C<len> indicates number of bytes to
-copy. If pointer is NULL allocate space for a string of size specified.
-This does not use an SV.
+Perl's version of what C<strndup()> would be if it existed. Returns a
+pointer to a newly allocated string which is a duplicate of the first
+C<len> bytes from C<pv>. The memory allocated for the new string can be
+freed with the C<Safefree()> function.
 
-       char*   savepvn(const char* sv, I32 len)
+       char*   savepvn(const char* pv, I32 len)
 
 =for hackers
 Found in file util.c
 
 =item savesharedpv
 
-Copy a string to a safe spot in memory shared between threads.
-This does not use an SV.
+A version of C<savepv()> which allocates the duplicate string in memory
+which is shared between threads.
 
-       char*   savesharedpv(const char* sv)
+       char*   savesharedpv(const char* pv)
 
 =for hackers
 Found in file util.c
@@ -2584,22 +2639,22 @@ version which guarantees to evaluate sv only once.
 =for hackers
 Found in file sv.h
 
-=item SvIVX
+=item SvIVx
 
-Returns the raw value in the SV's IV slot, without checks or conversions.
-Only use when you are sure SvIOK is true. See also C<SvIV()>.
+Coerces the given SV to an integer and returns it. Guarantees to evaluate
+sv only once. Use the more efficient C<SvIV> otherwise.
 
-       IV      SvIVX(SV* sv)
+       IV      SvIVx(SV* sv)
 
 =for hackers
 Found in file sv.h
 
-=item SvIVx
+=item SvIVX
 
-Coerces the given SV to an integer and returns it. Guarantees to evaluate
-sv only once. Use the more efficient C<SvIV> otherwise.
+Returns the raw value in the SV's IV slot, without checks or conversions.
+Only use when you are sure SvIOK is true. See also C<SvIV()>.
 
-       IV      SvIVx(SV* sv)
+       IV      SvIVX(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -2699,22 +2754,22 @@ which guarantees to evaluate sv only once.
 =for hackers
 Found in file sv.h
 
-=item SvNVx
+=item SvNVX
 
-Coerces the given SV to a double and returns it. Guarantees to evaluate
-sv only once. Use the more efficient C<SvNV> otherwise.
+Returns the raw value in the SV's NV slot, without checks or conversions.
+Only use when you are sure SvNOK is true. See also C<SvNV()>.
 
-       NV      SvNVx(SV* sv)
+       NV      SvNVX(SV* sv)
 
 =for hackers
 Found in file sv.h
 
-=item SvNVX
+=item SvNVx
 
-Returns the raw value in the SV's NV slot, without checks or conversions.
-Only use when you are sure SvNOK is true. See also C<SvNV()>.
+Coerces the given SV to a double and returns it. Guarantees to evaluate
+sv only once. Use the more efficient C<SvNV> otherwise.
 
-       NV      SvNVX(SV* sv)
+       NV      SvNVx(SV* sv)
 
 =for hackers
 Found in file sv.h
@@ -3832,8 +3887,7 @@ Found in file sv.c
 
 =item sv_pv
 
-A private implementation of the C<SvPV_nolen> macro for compilers which can't
-cope with complex macro expressions. Always use the macro instead.
+Use the C<SvPV_nolen> macro instead
 
        char*   sv_pv(SV *sv)
 
@@ -3842,9 +3896,7 @@ Found in file sv.c
 
 =item sv_pvbyte
 
-A private implementation of the C<SvPVbyte_nolen> macro for compilers
-which can't cope with complex macro expressions. Always use the macro
-instead.
+Use C<SvPVbyte_nolen> instead.
 
        char*   sv_pvbyte(SV *sv)
 
@@ -3910,9 +3962,7 @@ Found in file sv.c
 
 =item sv_pvutf8
 
-A private implementation of the C<SvPVutf8_nolen> macro for compilers
-which can't cope with complex macro expressions. Always use the macro
-instead.
+Use the C<SvPVutf8_nolen> macro instead
 
        char*   sv_pvutf8(SV *sv)
 
@@ -4062,25 +4112,6 @@ Like C<sv_setpvf>, but also handles 'set' magic.
 =for hackers
 Found in file sv.c
 
-=item sv_setpviv
-
-Copies an integer into the given SV, also updating its string value.
-Does not handle 'set' magic.  See C<sv_setpviv_mg>.
-
-       void    sv_setpviv(SV* sv, IV num)
-
-=for hackers
-Found in file sv.c
-
-=item sv_setpviv_mg
-
-Like C<sv_setpviv>, but also handles 'set' magic.
-
-       void    sv_setpviv_mg(SV *sv, IV iv)
-
-=for hackers
-Found in file sv.c
-
 =item sv_setpvn
 
 Copies a string into an SV.  The C<len> parameter indicates the number of
@@ -4195,7 +4226,6 @@ You probably want to use one of the assortment of wrappers, such as
 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
 C<SvSetMagicSV_nosteal>.
 
-
        void    sv_setsv(SV* dsv, SV* ssv)
 
 =for hackers
@@ -4539,9 +4569,9 @@ Found in file utf8.c
 =item is_utf8_char
 
 Tests if some arbitrary number of bytes begins in a valid UTF-8
-character.  Note that an INVARIANT (i.e. ASCII) character is a valid UTF-8 character.
-The actual number of bytes in the UTF-8 character will be returned if
-it is valid, otherwise 0.
+character.  Note that an INVARIANT (i.e. ASCII) character is a valid
+UTF-8 character.  The actual number of bytes in the UTF-8 character
+will be returned if it is valid, otherwise 0.
 
        STRLEN  is_utf8_char(U8 *p)