X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=08420967a83f26791ab7cf8d87e2f51380a8c08d;hb=b03ad8f690c4dcc613a1ec77d747e2d429945b16;hp=0b915ddba6cc4651d5f6e6ec461ce50437ae0f1d;hpb=94bdecf9800c3bee967274854f7adf2933ffd42b;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 0b915dd..0842096 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -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. =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. @@ -646,6 +658,32 @@ Found in file perl.c =back +=head1 Functions in file pp_pack.c + + +=over 8 + +=item pack_cat + +The engine implementing pack() Perl function. + + void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) + +=for hackers +Found in file pp_pack.c + +=item unpack_str + +The engine implementing unpack() Perl function. + + I32 unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags) + +=for hackers +Found in file pp_pack.c + + +=back + =head1 Global Variables =over 8 @@ -780,6 +818,20 @@ C apply equally to these functions. =for hackers Found in file gv.c +=item gv_fetchmeth_autoload + +Same as gv_fetchmeth(), but looks for autoloaded subroutines too. +Returns a glob for the subroutine. + +For an autoloaded subroutine without a GV, will create a GV even +if C. For an autoloaded subroutine without a stub, GvCV() +of the result may be zero. + + GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level) + +=for hackers +Found in file gv.c + =item gv_stashpv Returns a pointer to the stash for a specified package. C should @@ -1048,6 +1100,7 @@ NOTE: Before version 5.004_65, C 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. + I32 hv_iterinit(HV* tb) =for hackers @@ -1078,6 +1131,14 @@ Found in file hv.c Returns entries from a hash iterator. See C. +You may call C or C 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, so you must not discard +your iterator immediately else the entry will leak - call C to +trigger the resource deallocation. + HE* hv_iternext(HV* tb) =for hackers @@ -1093,6 +1154,26 @@ operation. =for hackers Found in file hv.c +=item hv_iternext_flags + +Returns entries from a hash iterator. See C and C. +The C 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 value is a normal read-write SV for which +C 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 @@ -1266,6 +1347,16 @@ argument more than once. =for hackers Found in file sv.h +=item SvLOCK + +Arranges for a mutual exclusion lock to be obtained on sv if a suitable module +has been loaded. + + void SvLOCK(SV* sv) + +=for hackers +Found in file sv.h + =item SvSETMAGIC Invokes C on an SV if it has 'set' magic. This macro evaluates its @@ -1285,6 +1376,15 @@ Like C, but does any set magic required afterwards. =for hackers Found in file sv.h +=item SvSetMagicSV_nosteal + +Like C, but does any set magic required afterwards. + + void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.h + =item SvSetSV Calls C if dsv is not the same as ssv. May evaluate arguments @@ -1305,6 +1405,16 @@ ssv. May evaluate arguments more than once. =for hackers Found in file sv.h +=item SvSHARE + +Arranges for sv to be shared between threads if a suitable module +has been loaded. + + void SvSHARE(SV* sv) + +=for hackers +Found in file sv.h + =back @@ -1377,6 +1487,16 @@ memory is zeroed with C. =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 function. @@ -1407,19 +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. Returns a pointer to a newly allocated +string which is a duplicate of C. The size of the string is +determined by C. The memory allocated for the new string can +be freed with the C 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 indicates number of bytes to -copy. This does not use an SV. +Perl's version of what C would be if it existed. Returns a +pointer to a newly allocated string which is a duplicate of the first +C bytes from C. The memory allocated for the new string can be +freed with the C function. + + char* savepvn(const char* pv, I32 len) - char* savepvn(const char* sv, I32 len) +=for hackers +Found in file util.c + +=item savesharedpv + +A version of C which allocates the duplicate string in memory +which is shared between threads. + + char* savesharedpv(const char* pv) =for hackers Found in file util.c @@ -1750,77 +1885,6 @@ Found in file op.c =back -=head1 Shared SV Functions - -=over 8 - -=item sharedsv_find - -Tries to find if a given SV has a shared backend, either by -looking at magic, or by checking if it is tied again threads::shared. - - shared_sv* sharedsv_find(SV* sv) - -=for hackers -Found in file sharedsv.c - -=item sharedsv_init - -Saves a space for keeping SVs wider than an interpreter, -currently only stores a pointer to the first interpreter. - - void sharedsv_init() - -=for hackers -Found in file sharedsv.c - -=item sharedsv_lock - -Recursive locks on a sharedsv. -Locks are dynamically scoped at the level of the first lock. - void sharedsv_lock(shared_sv* ssv) - -=for hackers -Found in file sharedsv.c - -=item sharedsv_new - -Allocates a new shared sv struct, you must yourself create the SV/AV/HV. - shared_sv* sharedsv_new() - -=for hackers -Found in file sharedsv.c - -=item sharedsv_thrcnt_dec - -Decrements the threadcount of a shared sv. When a threads frontend is freed -this function should be called. - - void sharedsv_thrcnt_dec(shared_sv* ssv) - -=for hackers -Found in file sharedsv.c - -=item sharedsv_thrcnt_inc - -Increments the threadcount of a sharedsv. - void sharedsv_thrcnt_inc(shared_sv* ssv) - -=for hackers -Found in file sharedsv.c - -=item sharedsv_unlock - -Recursively unlocks a shared sv. - - void sharedsv_unlock(shared_sv* ssv) - -=for hackers -Found in file sharedsv.c - - -=back - =head1 Stack Manipulation Macros =over 8 @@ -2791,8 +2855,9 @@ Found in file sv.h =item SvPV -Returns a pointer to the string in the SV, or a stringified form of the SV -if the SV does not contain a string. Handles 'get' magic. See also +Returns a pointer to the string in the SV, or a stringified form of +the SV if the SV does not contain a string. The SV may cache the +stringified version becoming C. Handles 'get' magic. See also C for a version which guarantees to evaluate sv only once. char* SvPV(SV* sv, STRLEN len) @@ -2899,29 +2964,30 @@ Like C, but converts sv to utf8 first if necessary. =for hackers Found in file sv.h -=item SvPVX +=item SvPVx -Returns a pointer to the physical string in the SV. The SV must contain a -string. +A version of C which guarantees to evaluate sv only once. - char* SvPVX(SV* sv) + char* SvPVx(SV* sv, STRLEN len) =for hackers Found in file sv.h -=item SvPVx +=item SvPVX -A version of C which guarantees to evaluate sv only once. +Returns a pointer to the physical string in the SV. The SV must contain a +string. - char* SvPVx(SV* sv, STRLEN len) + char* SvPVX(SV* sv) =for hackers Found in file sv.h =item SvPV_force -Like but will force the SV into becoming a string (SvPOK). You want -force if you are going to update the SvPVX directly. +Like C but will force the SV into containing just a string +(C). You want force if you are going to update the C +directly. char* SvPV_force(SV* sv, STRLEN len) @@ -2930,8 +2996,9 @@ Found in file sv.h =item SvPV_force_nomg -Like but will force the SV into becoming a string (SvPOK). You want -force if you are going to update the SvPVX directly. Doesn't process magic. +Like C but will force the SV into containing just a string +(C). You want force if you are going to update the C +directly. Doesn't process magic. char* SvPV_force_nomg(SV* sv, STRLEN len) @@ -2940,8 +3007,9 @@ Found in file sv.h =item SvPV_nolen -Returns a pointer to the string in the SV, or a stringified form of the SV -if the SV does not contain a string. Handles 'get' magic. +Returns a pointer to the string in the SV, or a stringified form of +the SV if the SV does not contain a string. The SV may cache the +stringified form becoming C. Handles 'get' magic. char* SvPV_nolen(SV* sv) @@ -3011,16 +3079,6 @@ Dereferences an RV to return the SV. =for hackers Found in file sv.h -=item SvSetMagicSV_nosteal - -Like C, but does any set magic required afterwards. - - - void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - =item SvSTASH Returns the stash of the SV. @@ -3091,6 +3149,17 @@ Returns the type of the SV. See C. =for hackers Found in file sv.h +=item SvUNLOCK + +Releases a mutual exclusion lock on sv if a suitable module +has been loaded. + + + void SvUNLOCK(SV* sv) + +=for hackers +Found in file sv.h + =item SvUOK Returns a boolean indicating whether the SV contains an unsigned integer. @@ -3148,22 +3217,22 @@ for a version which guarantees to evaluate sv only once. =for hackers Found in file sv.h -=item SvUVx +=item SvUVX -Coerces the given SV to an unsigned integer and returns it. Guarantees to -evaluate sv only once. Use the more efficient C otherwise. +Returns the raw value in the SV's UV slot, without checks or conversions. +Only use when you are sure SvIOK is true. See also C. - UV SvUVx(SV* sv) + UV SvUVX(SV* sv) =for hackers Found in file sv.h -=item SvUVX +=item SvUVx -Returns the raw value in the SV's UV slot, without checks or conversions. -Only use when you are sure SvIOK is true. See also C. +Coerces the given SV to an unsigned integer and returns it. Guarantees to +evaluate sv only once. Use the more efficient C otherwise. - UV SvUVX(SV* sv) + UV SvUVx(SV* sv) =for hackers Found in file sv.h @@ -3509,6 +3578,21 @@ settings. =for hackers Found in file sv.c +=item sv_copypv + +Copies a stringified representation of the source SV into the +destination SV. Automatically performs any necessary mg_get and +coercion of numeric values into strings. Guaranteed to preserve +UTF-8 flag even from overloaded objects. Similar in nature to +sv_2pv[_flags] but operates directly on an SV instead of just the +string. Mostly uses sv_2pv_flags to do its work, except when that +would lose the UTF-8'ness of the PV. + + void sv_copypv(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.c + =item sv_dec Auto-decrement of the value in the SV, doing string to numeric conversion @@ -3674,13 +3758,32 @@ 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. -C is assumed to contain an C if C<(name && namelen == HEf_SVKEY)> - void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) =for hackers 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. + +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' + +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 + +(This is now used as a subroutine by sv_magic.) + + MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen ) + +=for hackers +Found in file sv.c + =item sv_mortalcopy Creates a new SV which is a copy of the original SV (using C). @@ -3715,6 +3818,39 @@ instead. =for hackers Found in file sv.c +=item sv_nolocking + +Dummy routine which "locks" an SV when there is no locking module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nolocking(SV *) + +=for hackers +Found in file util.c + +=item sv_nosharing + +Dummy routine which "shares" an SV when there is no sharing module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nosharing(SV *) + +=for hackers +Found in file util.c + +=item sv_nounlocking + +Dummy routine which "unlocks" an SV when there is no locking module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nounlocking(SV *) + +=for hackers +Found in file util.c + =item sv_nv A private implementation of the C macro for compilers which can't @@ -3751,8 +3887,7 @@ Found in file sv.c =item sv_pv -A private implementation of the C macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. +Use the C macro instead char* sv_pv(SV *sv) @@ -3761,9 +3896,7 @@ Found in file sv.c =item sv_pvbyte -A private implementation of the C macro for compilers -which can't cope with complex macro expressions. Always use the macro -instead. +Use C instead. char* sv_pvbyte(SV *sv) @@ -3829,9 +3962,7 @@ Found in file sv.c =item sv_pvutf8 -A private implementation of the C macro for compilers -which can't cope with complex macro expressions. Always use the macro -instead. +Use the C macro instead char* sv_pvutf8(SV *sv) @@ -3981,25 +4112,6 @@ Like C, 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. - - void sv_setpviv(SV* sv, IV num) - -=for hackers -Found in file sv.c - -=item sv_setpviv_mg - -Like C, 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 parameter indicates the number of @@ -4114,7 +4226,6 @@ You probably want to use one of the assortment of wrappers, such as C, C, C and C. - void sv_setsv(SV* dsv, SV* ssv) =for hackers @@ -4298,6 +4409,9 @@ This may not be possible if the PV contains non-byte encoding characters; if this is the case, either returns false or, if C is not true, croaks. +This is not as a general purpose Unicode to byte encoding interface: +use the Encode extension for that. + NOTE: this function is experimental and may change or be removed without notice. @@ -4324,6 +4438,9 @@ Forces the SV to string form if it is not already. Always sets the SvUTF8 flag to avoid future validity checks even if all the bytes have hibit clear. +This is not as a general purpose byte encoding to Unicode interface: +use the Encode extension for that. + STRLEN sv_utf8_upgrade(SV *sv) =for hackers @@ -4338,6 +4455,9 @@ if all the bytes have hibit clear. If C has C bit set, will C on C if appropriate, else not. C and C are implemented in terms of this function. +This is not as a general purpose byte encoding to Unicode interface: +use the Encode extension for that. + STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags) =for hackers @@ -4449,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) @@ -4475,7 +4595,14 @@ Found in file utf8.c Build to the scalar dsv a displayable version of the string spv, length len, the displayable version being at most pvlim bytes long (if longer, the rest is truncated and "..." will be appended). -The flags argument is currently unused but available for future extensions. + +The flags argument can have UNI_DISPLAY_ISPRINT set to display +isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH +to display the \\[nrfta\\] as the backslashed versions (like '\n') +(UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\). +UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both +UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on. + The pointer to the PV of the dsv is returned. char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags) @@ -4504,9 +4631,11 @@ Found in file sv.c =item sv_uni_display Build to the scalar dsv a displayable version of the scalar sv, -he displayable version being at most pvlim bytes long +the displayable version being at most pvlim bytes long (if longer, the rest is truncated and "..." will be appended). -The flags argument is currently unused but available for future extensions. + +The flags argument is as in pv_uni_display(). + The pointer to the PV of the dsv is returned. char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags) @@ -4523,16 +4652,18 @@ The "ustrp" is a pointer to the character buffer to put the conversion result to. The "lenp" is a pointer to the length of the result. -The "swash" is a pointer to the swash to use. +The "swashp" is a pointer to the swash to use. -The "normal" is a string like "ToLower" which means the swash -$utf8::ToLower, which is stored in lib/unicore/To/Lower.pl, -and loaded by SWASHGET, using lib/utf8_heavy.pl. +Both the special and normal mappings are stored lib/unicore/To/Foo.pl, +and loaded by SWASHGET, using lib/utf8_heavy.pl. The special (usually, +but not always, a multicharacter mapping), is tried first. + +The "special" is a string like "utf8::ToSpecLower", which means the +hash %utf8::ToSpecLower. The access to the hash is through +Perl_to_utf8_case(). -The "special" is a string like "utf8::ToSpecLower", which means -the hash %utf8::ToSpecLower, which is stored in the same file, -lib/unicore/To/Lower.pl, and also loaded by SWASHGET. The access -to the hash is by Perl_to_utf8_case(). +The "normal" is a string like "ToLower" which means the swash +%utf8::ToLower. UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special)