3 * Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010,
4 * 2011, 2012 by Larry Wall and others
6 * You may distribute under the terms of either the GNU General Public
7 * License or the Artistic License, as specified in the README file.
12 * Anything that Hobbits had no immediate use for, but were unwilling to
13 * throw away, they called a mathom. Their dwellings were apt to become
14 * rather crowded with mathoms, and many of the presents that passed from
15 * hand to hand were of that sort.
17 * [p.5 of _The Lord of the Rings_: "Prologue"]
23 * This file contains mathoms, various binary artifacts from previous
24 * versions of Perl which we cannot completely remove from the core
25 * code. There are two reasons functions should be here:
27 * 1) A function has been replaced by a macro within a minor release,
28 * so XS modules compiled against an older release will expect to
29 * still be able to link against the function
30 * 2) A function Perl_foo(...) with #define foo Perl_foo(aTHX_ ...)
31 * has been replaced by a macro, e.g. #define foo(...) foo_flags(...,0)
32 * but XS code may still explicitly use the long form, i.e.
35 * NOTE: ALL FUNCTIONS IN THIS FILE should have an entry with the 'b' flag in
38 * To move a function to this file, simply cut and paste it here, and change
39 * its embed.fnc entry to additionally have the 'b' flag. If, for some reason
40 * a function you'd like to be treated as mathoms can't be moved from its
41 * current place, simply enclose it between
47 * and add the 'b' flag in embed.fnc.
49 * The compilation of this file can be suppressed; see INSTALL
51 * Some blurb for perlapi.pod:
53 head1 Obsolete backwards compatibility functions
55 Some of these are also deprecated. You can exclude these from
56 your compiled Perl by adding this option to Configure:
57 C<-Accflags='-DNO_MATHOMS'>
65 #define PERL_IN_MATHOMS_C
69 /* ..." warning: ISO C forbids an empty source file"
70 So make sure we have something in here by processing the headers anyway.
74 /* The functions in this file should be able to call other deprecated functions
75 * without a compiler warning */
76 GCC_DIAG_IGNORE(-Wdeprecated-declarations)
78 /* ref() is now a macro using Perl_doref;
79 * this version provided for binary compatibility only.
82 Perl_ref(pTHX_ OP *o, I32 type)
84 return doref(o, type, TRUE);
88 =for apidoc_section SV Handling
91 Unsets the RV status of the SV, and decrements the reference count of
92 whatever was being referenced by the RV. This can almost be thought of
93 as a reversal of C<newSVrv>. This is C<sv_unref_flags> with the C<flag>
94 being zero. See C<L</SvROK_off>>.
100 Perl_sv_unref(pTHX_ SV *sv)
102 PERL_ARGS_ASSERT_SV_UNREF;
104 sv_unref_flags(sv, 0);
110 Taint an SV. Use C<SvTAINTED_on> instead.
116 Perl_sv_taint(pTHX_ SV *sv)
118 PERL_ARGS_ASSERT_SV_TAINT;
120 sv_magic((sv), NULL, PERL_MAGIC_taint, NULL, 0);
123 /* sv_2iv() is now a macro using Perl_sv_2iv_flags();
124 * this function provided for binary compatibility only
128 Perl_sv_2iv(pTHX_ SV *sv)
130 PERL_ARGS_ASSERT_SV_2IV;
132 return sv_2iv_flags(sv, SV_GMAGIC);
135 /* sv_2uv() is now a macro using Perl_sv_2uv_flags();
136 * this function provided for binary compatibility only
140 Perl_sv_2uv(pTHX_ SV *sv)
142 PERL_ARGS_ASSERT_SV_2UV;
144 return sv_2uv_flags(sv, SV_GMAGIC);
147 /* sv_2nv() is now a macro using Perl_sv_2nv_flags();
148 * this function provided for binary compatibility only
152 Perl_sv_2nv(pTHX_ SV *sv)
154 return sv_2nv_flags(sv, SV_GMAGIC);
158 /* sv_2pv() is now a macro using Perl_sv_2pv_flags();
159 * this function provided for binary compatibility only
163 Perl_sv_2pv(pTHX_ SV *sv, STRLEN *lp)
165 PERL_ARGS_ASSERT_SV_2PV;
167 return sv_2pv_flags(sv, lp, SV_GMAGIC);
171 =for apidoc sv_2pv_nolen
173 Like C<sv_2pv()>, but doesn't return the length too. You should usually
174 use the macro wrapper C<SvPV_nolen(sv)> instead.
180 Perl_sv_2pv_nolen(pTHX_ SV *sv)
182 PERL_ARGS_ASSERT_SV_2PV_NOLEN;
183 return sv_2pv(sv, NULL);
187 =for apidoc sv_2pvbyte_nolen
189 Return a pointer to the byte-encoded representation of the SV.
190 May cause the SV to be downgraded from UTF-8 as a side-effect.
192 Usually accessed via the C<SvPVbyte_nolen> macro.
198 Perl_sv_2pvbyte_nolen(pTHX_ SV *sv)
200 PERL_ARGS_ASSERT_SV_2PVBYTE_NOLEN;
202 return sv_2pvbyte(sv, NULL);
206 =for apidoc sv_2pvutf8_nolen
208 Return a pointer to the UTF-8-encoded representation of the SV.
209 May cause the SV to be upgraded to UTF-8 as a side-effect.
211 Usually accessed via the C<SvPVutf8_nolen> macro.
217 Perl_sv_2pvutf8_nolen(pTHX_ SV *sv)
219 PERL_ARGS_ASSERT_SV_2PVUTF8_NOLEN;
221 return sv_2pvutf8(sv, NULL);
225 =for apidoc sv_force_normal
227 Undo various types of fakery on an SV: if the PV is a shared string, make
228 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
229 an C<xpvmg>. See also C<L</sv_force_normal_flags>>.
235 Perl_sv_force_normal(pTHX_ SV *sv)
237 PERL_ARGS_ASSERT_SV_FORCE_NORMAL;
239 sv_force_normal_flags(sv, 0);
242 /* sv_setsv() is now a macro using Perl_sv_setsv_flags();
243 * this function provided for binary compatibility only
247 Perl_sv_setsv(pTHX_ SV *dstr, SV *sstr)
249 PERL_ARGS_ASSERT_SV_SETSV;
251 sv_setsv_flags(dstr, sstr, SV_GMAGIC);
254 /* sv_catpvn() is now a macro using Perl_sv_catpvn_flags();
255 * this function provided for binary compatibility only
259 Perl_sv_catpvn(pTHX_ SV *dsv, const char* sstr, STRLEN slen)
261 PERL_ARGS_ASSERT_SV_CATPVN;
263 sv_catpvn_flags(dsv, sstr, slen, SV_GMAGIC);
267 =for apidoc sv_catpvn_mg
269 Like C<sv_catpvn>, but also handles 'set' magic.
275 Perl_sv_catpvn_mg(pTHX_ SV *sv, const char *ptr, STRLEN len)
277 PERL_ARGS_ASSERT_SV_CATPVN_MG;
279 sv_catpvn_flags(sv,ptr,len,SV_GMAGIC|SV_SMAGIC);
282 /* sv_catsv() is now a macro using Perl_sv_catsv_flags();
283 * this function provided for binary compatibility only
287 Perl_sv_catsv(pTHX_ SV *dstr, SV *sstr)
289 PERL_ARGS_ASSERT_SV_CATSV;
291 sv_catsv_flags(dstr, sstr, SV_GMAGIC);
295 =for apidoc sv_catsv_mg
297 Like C<sv_catsv>, but also handles 'set' magic.
303 Perl_sv_catsv_mg(pTHX_ SV *dsv, SV *ssv)
305 PERL_ARGS_ASSERT_SV_CATSV_MG;
307 sv_catsv_flags(dsv,ssv,SV_GMAGIC|SV_SMAGIC);
313 A private implementation of the C<SvIVx> macro for compilers which can't
314 cope with complex macro expressions. Always use the macro instead.
320 Perl_sv_iv(pTHX_ SV *sv)
322 PERL_ARGS_ASSERT_SV_IV;
326 return (IV)SvUVX(sv);
335 A private implementation of the C<SvUVx> macro for compilers which can't
336 cope with complex macro expressions. Always use the macro instead.
342 Perl_sv_uv(pTHX_ SV *sv)
344 PERL_ARGS_ASSERT_SV_UV;
349 return (UV)SvIVX(sv);
357 A private implementation of the C<SvNVx> macro for compilers which can't
358 cope with complex macro expressions. Always use the macro instead.
364 Perl_sv_nv(pTHX_ SV *sv)
366 PERL_ARGS_ASSERT_SV_NV;
376 Use the C<SvPV_nolen> macro instead
380 A private implementation of the C<SvPV> macro for compilers which can't
381 cope with complex macro expressions. Always use the macro instead.
387 Perl_sv_pvn(pTHX_ SV *sv, STRLEN *lp)
389 PERL_ARGS_ASSERT_SV_PVN;
395 return sv_2pv(sv, lp);
400 Perl_sv_pvn_nomg(pTHX_ SV *sv, STRLEN *lp)
402 PERL_ARGS_ASSERT_SV_PVN_NOMG;
408 return sv_2pv_flags(sv, lp, 0);
411 /* sv_pv() is now a macro using SvPV_nolen();
412 * this function provided for binary compatibility only
416 Perl_sv_pv(pTHX_ SV *sv)
418 PERL_ARGS_ASSERT_SV_PV;
423 return sv_2pv(sv, NULL);
426 /* sv_pvn_force() is now a macro using Perl_sv_pvn_force_flags();
427 * this function provided for binary compatibility only
431 Perl_sv_pvn_force(pTHX_ SV *sv, STRLEN *lp)
433 PERL_ARGS_ASSERT_SV_PVN_FORCE;
435 return sv_pvn_force_flags(sv, lp, SV_GMAGIC);
438 /* sv_pvbyte () is now a macro using Perl_sv_2pv_flags();
439 * this function provided for binary compatibility only
443 Perl_sv_pvbyte(pTHX_ SV *sv)
445 PERL_ARGS_ASSERT_SV_PVBYTE;
447 sv_utf8_downgrade(sv, FALSE);
452 =for apidoc sv_pvbyte
454 Use C<SvPVbyte_nolen> instead.
456 =for apidoc sv_pvbyten
458 A private implementation of the C<SvPVbyte> macro for compilers
459 which can't cope with complex macro expressions. Always use the macro
466 Perl_sv_pvbyten(pTHX_ SV *sv, STRLEN *lp)
468 PERL_ARGS_ASSERT_SV_PVBYTEN;
470 sv_utf8_downgrade(sv, FALSE);
471 return sv_pvn(sv,lp);
474 /* sv_pvutf8 () is now a macro using Perl_sv_2pv_flags();
475 * this function provided for binary compatibility only
479 Perl_sv_pvutf8(pTHX_ SV *sv)
481 PERL_ARGS_ASSERT_SV_PVUTF8;
488 =for apidoc sv_pvutf8
490 Use the C<SvPVutf8_nolen> macro instead
492 =for apidoc sv_pvutf8n
494 A private implementation of the C<SvPVutf8> macro for compilers
495 which can't cope with complex macro expressions. Always use the macro
502 Perl_sv_pvutf8n(pTHX_ SV *sv, STRLEN *lp)
504 PERL_ARGS_ASSERT_SV_PVUTF8N;
507 return sv_pvn(sv,lp);
510 /* sv_utf8_upgrade() is now a macro using sv_utf8_upgrade_flags();
511 * this function provided for binary compatibility only
515 Perl_sv_utf8_upgrade(pTHX_ SV *sv)
517 PERL_ARGS_ASSERT_SV_UTF8_UPGRADE;
519 return sv_utf8_upgrade_flags(sv, SV_GMAGIC);
523 Perl_fprintf_nocontext(PerlIO *stream, const char *format, ...)
528 /* Easier to special case this here than in embed.pl. (Look at what it
529 generates for proto.h) */
530 #ifdef PERL_IMPLICIT_CONTEXT
531 PERL_ARGS_ASSERT_FPRINTF_NOCONTEXT;
534 va_start(arglist, format);
535 ret = PerlIO_vprintf(stream, format, arglist);
541 Perl_printf_nocontext(const char *format, ...)
547 #ifdef PERL_IMPLICIT_CONTEXT
548 PERL_ARGS_ASSERT_PRINTF_NOCONTEXT;
551 va_start(arglist, format);
552 ret = PerlIO_vprintf(PerlIO_stdout(), format, arglist);
557 #if defined(HUGE_VAL) || (defined(USE_LONG_DOUBLE) && defined(HUGE_VALL))
559 * This hack is to force load of "huge" support from libm.a
560 * So it is in perl for (say) POSIX to use.
561 * Needed for SunOS with Sun's 'acc' for example.
566 # if defined(USE_LONG_DOUBLE) && defined(HUGE_VALL)
574 /* compatibility with versions <= 5.003. */
576 Perl_gv_fullname(pTHX_ SV *sv, const GV *gv)
578 PERL_ARGS_ASSERT_GV_FULLNAME;
580 gv_fullname3(sv, gv, sv == (const SV*)gv ? "*" : "");
583 /* compatibility with versions <= 5.003. */
585 Perl_gv_efullname(pTHX_ SV *sv, const GV *gv)
587 PERL_ARGS_ASSERT_GV_EFULLNAME;
589 gv_efullname3(sv, gv, sv == (const SV*)gv ? "*" : "");
593 Perl_gv_fullname3(pTHX_ SV *sv, const GV *gv, const char *prefix)
595 PERL_ARGS_ASSERT_GV_FULLNAME3;
597 gv_fullname4(sv, gv, prefix, TRUE);
601 Perl_gv_efullname3(pTHX_ SV *sv, const GV *gv, const char *prefix)
603 PERL_ARGS_ASSERT_GV_EFULLNAME3;
605 gv_efullname4(sv, gv, prefix, TRUE);
609 =for apidoc_section GV Handling
610 =for apidoc gv_fetchmethod
612 See L</gv_fetchmethod_autoload>.
618 Perl_gv_fetchmethod(pTHX_ HV *stash, const char *name)
620 PERL_ARGS_ASSERT_GV_FETCHMETHOD;
622 return gv_fetchmethod_autoload(stash, name, TRUE);
626 Perl_hv_iternext(pTHX_ HV *hv)
628 PERL_ARGS_ASSERT_HV_ITERNEXT;
630 return hv_iternext_flags(hv, 0);
634 Perl_hv_magic(pTHX_ HV *hv, GV *gv, int how)
636 PERL_ARGS_ASSERT_HV_MAGIC;
638 sv_magic(MUTABLE_SV(hv), MUTABLE_SV(gv), how, NULL, 0);
642 Perl_do_open(pTHX_ GV *gv, const char *name, I32 len, int as_raw,
643 int rawmode, int rawperm, PerlIO *supplied_fp)
645 PERL_ARGS_ASSERT_DO_OPEN;
647 return do_openn(gv, name, len, as_raw, rawmode, rawperm,
648 supplied_fp, (SV **) NULL, 0);
652 Perl_do_open9(pTHX_ GV *gv, const char *name, I32 len, int
654 int rawmode, int rawperm, PerlIO *supplied_fp, SV *svs,
657 PERL_ARGS_ASSERT_DO_OPEN9;
659 PERL_UNUSED_ARG(num_svs);
660 return do_openn(gv, name, len, as_raw, rawmode, rawperm,
661 supplied_fp, &svs, 1);
665 Perl_do_binmode(pTHX_ PerlIO *fp, int iotype, int mode)
667 /* The old body of this is now in non-LAYER part of perlio.c
668 * This is a stub for any XS code which might have been calling it.
670 const char *name = ":raw";
672 PERL_ARGS_ASSERT_DO_BINMODE;
674 #ifdef PERLIO_USING_CRLF
675 if (!(mode & O_BINARY))
678 return PerlIO_binmode(aTHX_ fp, iotype, mode, name);
683 Perl_do_aexec(pTHX_ SV *really, SV **mark, SV **sp)
685 PERL_ARGS_ASSERT_DO_AEXEC;
687 return do_aexec5(really, mark, sp, 0, 0);
691 /* Backwards compatibility. */
693 Perl_init_i18nl14n(pTHX_ int printwarn)
695 return init_i18nl10n(printwarn);
699 Perl_is_utf8_string_loc(const U8 *s, const STRLEN len, const U8 **ep)
701 PERL_ARGS_ASSERT_IS_UTF8_STRING_LOC;
703 return is_utf8_string_loclen(s, len, ep, 0);
707 =for apidoc_section SV Handling
708 =for apidoc sv_nolocking
710 Dummy routine which "locks" an SV when there is no locking module present.
711 Exists to avoid test for a C<NULL> function pointer and because it could
712 potentially warn under some level of strict-ness.
714 "Superseded" by C<sv_nosharing()>.
720 Perl_sv_nolocking(pTHX_ SV *sv)
728 =for apidoc sv_nounlocking
730 Dummy routine which "unlocks" an SV when there is no locking module present.
731 Exists to avoid test for a C<NULL> function pointer and because it could
732 potentially warn under some level of strict-ness.
734 "Superseded" by C<sv_nosharing()>.
738 PERL_UNLOCK_HOOK in intrpvar.h is the macro that refers to this, and guarantees
739 that mathoms gets loaded.
744 Perl_sv_nounlocking(pTHX_ SV *sv)
751 Perl_save_long(pTHX_ long int *longp)
753 PERL_ARGS_ASSERT_SAVE_LONG;
758 SSPUSHUV(SAVEt_LONG);
762 Perl_save_nogv(pTHX_ GV *gv)
764 PERL_ARGS_ASSERT_SAVE_NOGV;
768 SSPUSHUV(SAVEt_NSTAB);
772 Perl_save_list(pTHX_ SV **sarg, I32 maxsarg)
776 PERL_ARGS_ASSERT_SAVE_LIST;
778 for (i = 1; i <= maxsarg; i++) {
782 sv_setsv_nomg(sv,sarg[i]);
784 SSPUSHPTR(sarg[i]); /* remember the pointer */
785 SSPUSHPTR(sv); /* remember the value */
786 SSPUSHUV(SAVEt_ITEM);
791 =for apidoc sv_usepvn_mg
793 Like C<sv_usepvn>, but also handles 'set' magic.
799 Perl_sv_usepvn_mg(pTHX_ SV *sv, char *ptr, STRLEN len)
801 PERL_ARGS_ASSERT_SV_USEPVN_MG;
803 sv_usepvn_flags(sv,ptr,len, SV_SMAGIC);
807 =for apidoc sv_usepvn
809 Tells an SV to use C<ptr> to find its string value. Implemented by
810 calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
811 magic. See C<L</sv_usepvn_flags>>.
817 Perl_sv_usepvn(pTHX_ SV *sv, char *ptr, STRLEN len)
819 PERL_ARGS_ASSERT_SV_USEPVN;
821 sv_usepvn_flags(sv,ptr,len, 0);
825 =for apidoc_section Pack and Unpack
826 =for apidoc unpack_str
828 The engine implementing C<unpack()> Perl function. Note: parameters C<strbeg>,
829 C<new_s> and C<ocnt> are not used. This call should not be used, use
830 C<unpackstring> instead.
835 Perl_unpack_str(pTHX_ const char *pat, const char *patend, const char *s,
836 const char *strbeg, const char *strend, char **new_s, I32 ocnt,
839 PERL_ARGS_ASSERT_UNPACK_STR;
841 PERL_UNUSED_ARG(strbeg);
842 PERL_UNUSED_ARG(new_s);
843 PERL_UNUSED_ARG(ocnt);
845 return unpackstring(pat, patend, s, strend, flags);
851 The engine implementing C<pack()> Perl function. Note: parameters
852 C<next_in_list> and C<flags> are not used. This call should not be used; use
853 C<L</packlist>> instead.
859 Perl_pack_cat(pTHX_ SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
861 PERL_ARGS_ASSERT_PACK_CAT;
863 PERL_UNUSED_ARG(next_in_list);
864 PERL_UNUSED_ARG(flags);
866 packlist(cat, pat, patend, beglist, endlist);
870 Perl_hv_store_ent(pTHX_ HV *hv, SV *keysv, SV *val, U32 hash)
872 return (HE *)hv_common(hv, keysv, NULL, 0, 0, HV_FETCH_ISSTORE, val, hash);
876 Perl_hv_exists_ent(pTHX_ HV *hv, SV *keysv, U32 hash)
878 PERL_ARGS_ASSERT_HV_EXISTS_ENT;
880 return cBOOL(hv_common(hv, keysv, NULL, 0, 0, HV_FETCH_ISEXISTS, 0, hash));
884 Perl_hv_fetch_ent(pTHX_ HV *hv, SV *keysv, I32 lval, U32 hash)
886 PERL_ARGS_ASSERT_HV_FETCH_ENT;
888 return (HE *)hv_common(hv, keysv, NULL, 0, 0,
889 (lval ? HV_FETCH_LVALUE : 0), NULL, hash);
893 Perl_hv_delete_ent(pTHX_ HV *hv, SV *keysv, I32 flags, U32 hash)
895 PERL_ARGS_ASSERT_HV_DELETE_ENT;
897 return MUTABLE_SV(hv_common(hv, keysv, NULL, 0, 0, flags | HV_DELETE, NULL,
902 Perl_hv_store_flags(pTHX_ HV *hv, const char *key, I32 klen, SV *val, U32 hash,
905 return (SV**) hv_common(hv, NULL, key, klen, flags,
906 (HV_FETCH_ISSTORE|HV_FETCH_JUST_SV), val, hash);
910 Perl_hv_store(pTHX_ HV *hv, const char *key, I32 klen_i32, SV *val, U32 hash)
922 return (SV **) hv_common(hv, NULL, key, klen, flags,
923 (HV_FETCH_ISSTORE|HV_FETCH_JUST_SV), val, hash);
927 Perl_hv_exists(pTHX_ HV *hv, const char *key, I32 klen_i32)
932 PERL_ARGS_ASSERT_HV_EXISTS;
941 return cBOOL(hv_common(hv, NULL, key, klen, flags, HV_FETCH_ISEXISTS, 0, 0));
945 Perl_hv_fetch(pTHX_ HV *hv, const char *key, I32 klen_i32, I32 lval)
950 PERL_ARGS_ASSERT_HV_FETCH;
959 return (SV **) hv_common(hv, NULL, key, klen, flags,
960 lval ? (HV_FETCH_JUST_SV | HV_FETCH_LVALUE)
961 : HV_FETCH_JUST_SV, NULL, 0);
965 Perl_hv_delete(pTHX_ HV *hv, const char *key, I32 klen_i32, I32 flags)
970 PERL_ARGS_ASSERT_HV_DELETE;
974 k_flags = HVhek_UTF8;
979 return MUTABLE_SV(hv_common(hv, NULL, key, klen, k_flags, flags | HV_DELETE,
986 return MUTABLE_AV(newSV_type(SVt_PVAV));
987 /* sv_upgrade does AvREAL_only():
990 AvMAX(av) = AvFILLp(av) = -1; */
996 HV * const hv = MUTABLE_HV(newSV_type(SVt_PVHV));
1003 Perl_sv_insert(pTHX_ SV *const bigstr, const STRLEN offset, const STRLEN len,
1004 const char *const little, const STRLEN littlelen)
1006 PERL_ARGS_ASSERT_SV_INSERT;
1007 sv_insert_flags(bigstr, offset, len, little, littlelen, SV_GMAGIC);
1011 Perl_save_freesv(pTHX_ SV *sv)
1017 Perl_save_mortalizesv(pTHX_ SV *sv)
1019 PERL_ARGS_ASSERT_SAVE_MORTALIZESV;
1021 save_mortalizesv(sv);
1025 Perl_save_freeop(pTHX_ OP *o)
1031 Perl_save_freepv(pTHX_ char *pv)
1042 #ifdef PERL_DONT_CREATE_GVSV
1044 Perl_gv_SVadd(pTHX_ GV *gv)
1046 return gv_SVadd(gv);
1051 Perl_gv_AVadd(pTHX_ GV *gv)
1053 return gv_AVadd(gv);
1057 Perl_gv_HVadd(pTHX_ GV *gv)
1059 return gv_HVadd(gv);
1063 Perl_gv_IOadd(pTHX_ GV *gv)
1065 return gv_IOadd(gv);
1071 return MUTABLE_IO(newSV_type(SVt_PVIO));
1077 return my_stat_flags(SV_GMAGIC);
1083 return my_lstat_flags(SV_GMAGIC);
1087 Perl_sv_eq(pTHX_ SV *sv1, SV *sv2)
1089 return sv_eq_flags(sv1, sv2, SV_GMAGIC);
1092 #ifdef USE_LOCALE_COLLATE
1094 Perl_sv_collxfrm(pTHX_ SV *const sv, STRLEN *const nxp)
1096 PERL_ARGS_ASSERT_SV_COLLXFRM;
1097 return sv_collxfrm_flags(sv, nxp, SV_GMAGIC);
1101 Perl_mem_collxfrm(pTHX_ const char *input_string, STRLEN len, STRLEN *xlen)
1103 /* This function is retained for compatibility in case someone outside core
1104 * is using this (but it is undocumented) */
1106 PERL_ARGS_ASSERT_MEM_COLLXFRM;
1108 return _mem_collxfrm(input_string, len, xlen, FALSE);
1114 Perl_sv_2bool(pTHX_ SV *const sv)
1116 PERL_ARGS_ASSERT_SV_2BOOL;
1117 return sv_2bool_flags(sv, SV_GMAGIC);
1122 =for apidoc_section Custom Operators
1123 =for apidoc custom_op_name
1124 Return the name for a given custom op. This was once used by the C<OP_NAME>
1125 macro, but is no longer: it has only been kept for compatibility, and
1128 =for apidoc custom_op_desc
1129 Return the description of a given custom op. This was once used by the
1130 C<OP_DESC> macro, but is no longer: it has only been kept for
1131 compatibility, and should not be used.
1137 Perl_custom_op_name(pTHX_ const OP* o)
1139 PERL_ARGS_ASSERT_CUSTOM_OP_NAME;
1140 return XopENTRYCUSTOM(o, xop_name);
1144 Perl_custom_op_desc(pTHX_ const OP* o)
1146 PERL_ARGS_ASSERT_CUSTOM_OP_DESC;
1147 return XopENTRYCUSTOM(o, xop_desc);
1151 Perl_newSUB(pTHX_ I32 floor, OP *o, OP *proto, OP *block)
1153 return newATTRSUB(floor, o, proto, NULL, block);
1157 Perl_sv_mortalcopy(pTHX_ SV *const oldstr)
1159 return Perl_sv_mortalcopy_flags(aTHX_ oldstr, SV_GMAGIC);
1163 Perl_sv_copypv(pTHX_ SV *const dsv, SV *const ssv)
1165 PERL_ARGS_ASSERT_SV_COPYPV;
1167 sv_copypv_flags(dsv, ssv, SV_GMAGIC);
1170 UV /* Made into a function, so can be deprecated */
1171 NATIVE_TO_NEED(const UV enc, const UV ch)
1173 PERL_UNUSED_ARG(enc);
1177 UV /* Made into a function, so can be deprecated */
1178 ASCII_TO_NEED(const UV enc, const UV ch)
1180 PERL_UNUSED_ARG(enc);
1185 =for apidoc_section Unicode Support
1186 =for apidoc is_utf8_char
1188 Tests if some arbitrary number of bytes begins in a valid UTF-8
1189 character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC machines)
1190 character is a valid UTF-8 character. The actual number of bytes in the UTF-8
1191 character will be returned if it is valid, otherwise 0.
1193 This function is deprecated due to the possibility that malformed input could
1194 cause reading beyond the end of the input buffer. Use L</isUTF8_CHAR>
1200 Perl_is_utf8_char(const U8 *s)
1202 PERL_ARGS_ASSERT_IS_UTF8_CHAR;
1204 /* Assumes we have enough space, which is why this is deprecated. But the
1205 * UTF8_CHK_SKIP(s)) makes it safe for the common case of NUL-terminated
1207 return isUTF8_CHAR(s, s + UTF8_CHK_SKIP(s));
1211 =for apidoc is_utf8_char_buf
1213 This is identical to the macro L<perlapi/isUTF8_CHAR>.
1218 Perl_is_utf8_char_buf(const U8 *buf, const U8* buf_end)
1221 PERL_ARGS_ASSERT_IS_UTF8_CHAR_BUF;
1223 return isUTF8_CHAR(buf, buf_end);
1227 * Like L</utf8_to_uvuni_buf>(), but should only be called when it is known that
1228 * there are no malformations in the input UTF-8 string C<s>. Surrogates,
1229 * non-character code points, and non-Unicode code points are allowed */
1232 Perl_valid_utf8_to_uvuni(pTHX_ const U8 *s, STRLEN *retlen)
1234 PERL_UNUSED_CONTEXT;
1235 PERL_ARGS_ASSERT_VALID_UTF8_TO_UVUNI;
1237 return NATIVE_TO_UNI(valid_utf8_to_uvchr(s, retlen));
1241 =for apidoc utf8_to_uvuni
1243 Returns the Unicode code point of the first character in the string C<s>
1244 which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
1245 length, in bytes, of that character.
1247 Some, but not all, UTF-8 malformations are detected, and in fact, some
1248 malformed input could cause reading beyond the end of the input buffer, which
1249 is one reason why this function is deprecated. The other is that only in
1250 extremely limited circumstances should the Unicode versus native code point be
1251 of any interest to you. See L</utf8_to_uvuni_buf> for alternatives.
1253 If C<s> points to one of the detected malformations, and UTF8 warnings are
1254 enabled, zero is returned and C<*retlen> is set (if C<retlen> doesn't point to
1255 NULL) to -1. If those warnings are off, the computed value if well-defined (or
1256 the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen>
1257 is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the
1258 next possible position in C<s> that could begin a non-malformed character.
1259 See L<perlapi/utf8n_to_uvchr> for details on when the REPLACEMENT CHARACTER is returned.
1265 Perl_utf8_to_uvuni(pTHX_ const U8 *s, STRLEN *retlen)
1267 PERL_UNUSED_CONTEXT;
1268 PERL_ARGS_ASSERT_UTF8_TO_UVUNI;
1270 return NATIVE_TO_UNI(valid_utf8_to_uvchr(s, retlen));
1274 =for apidoc pad_compname_type
1276 Looks up the type of the lexical variable at position C<po> in the
1277 currently-compiling pad. If the variable is typed, the stash of the
1278 class to which it is typed is returned. If not, C<NULL> is returned.
1284 Perl_pad_compname_type(pTHX_ const PADOFFSET po)
1286 return PAD_COMPNAME_TYPE(po);
1289 /* return ptr to little string in big string, NULL if not found */
1290 /* The original version of this routine was donated by Corey Satten. */
1293 Perl_instr(const char *big, const char *little)
1295 PERL_ARGS_ASSERT_INSTR;
1297 return instr((char *) big, (char *) little);
1301 Perl_newSVsv(pTHX_ SV *const old)
1303 return newSVsv(old);
1307 Perl_sv_utf8_downgrade(pTHX_ SV *const sv, const bool fail_ok)
1309 PERL_ARGS_ASSERT_SV_UTF8_DOWNGRADE;
1311 return sv_utf8_downgrade(sv, fail_ok);
1315 Perl_sv_2pvutf8(pTHX_ SV *sv, STRLEN *const lp)
1317 PERL_ARGS_ASSERT_SV_2PVUTF8;
1319 return sv_2pvutf8(sv, lp);
1323 Perl_sv_2pvbyte(pTHX_ SV *sv, STRLEN *const lp)
1325 PERL_ARGS_ASSERT_SV_2PVBYTE;
1327 return sv_2pvbyte(sv, lp);
1331 Perl_uvuni_to_utf8(pTHX_ U8 *d, UV uv)
1333 PERL_ARGS_ASSERT_UVUNI_TO_UTF8;
1335 return uvoffuni_to_utf8_flags(d, uv, 0);
1339 =for apidoc utf8n_to_uvuni
1341 Instead use L<perlapi/utf8_to_uvchr_buf>, or rarely, L<perlapi/utf8n_to_uvchr>.
1343 This function was useful for code that wanted to handle both EBCDIC and
1344 ASCII platforms with Unicode properties, but starting in Perl v5.20, the
1345 distinctions between the platforms have mostly been made invisible to most
1346 code, so this function is quite unlikely to be what you want. If you do need
1347 this precise functionality, use instead
1348 C<L<NATIVE_TO_UNI(utf8_to_uvchr_buf(...))|perlapi/utf8_to_uvchr_buf>>
1349 or C<L<NATIVE_TO_UNI(utf8n_to_uvchr(...))|perlapi/utf8n_to_uvchr>>.
1355 Perl_utf8n_to_uvuni(pTHX_ const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
1357 PERL_ARGS_ASSERT_UTF8N_TO_UVUNI;
1359 return NATIVE_TO_UNI(utf8n_to_uvchr(s, curlen, retlen, flags));
1363 =for apidoc uvuni_to_utf8_flags
1365 Instead you almost certainly want to use L<perlapi/uvchr_to_utf8> or
1366 L<perlapi/uvchr_to_utf8_flags>.
1368 This function is a deprecated synonym for L</uvoffuni_to_utf8_flags>,
1369 which itself, while not deprecated, should be used only in isolated
1370 circumstances. These functions were useful for code that wanted to handle
1371 both EBCDIC and ASCII platforms with Unicode properties, but starting in Perl
1372 v5.20, the distinctions between the platforms have mostly been made invisible
1373 to most code, so this function is quite unlikely to be what you want.
1379 Perl_uvuni_to_utf8_flags(pTHX_ U8 *d, UV uv, UV flags)
1381 PERL_ARGS_ASSERT_UVUNI_TO_UTF8_FLAGS;
1383 return uvoffuni_to_utf8_flags(d, uv, flags);
1387 =for apidoc utf8_to_uvchr
1389 Returns the native code point of the first character in the string C<s>
1390 which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
1391 length, in bytes, of that character.
1393 Some, but not all, UTF-8 malformations are detected, and in fact, some
1394 malformed input could cause reading beyond the end of the input buffer, which
1395 is why this function is deprecated. Use L</utf8_to_uvchr_buf> instead.
1397 If C<s> points to one of the detected malformations, and UTF8 warnings are
1398 enabled, zero is returned and C<*retlen> is set (if C<retlen> isn't
1399 C<NULL>) to -1. If those warnings are off, the computed value if well-defined (or
1400 the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen>
1401 is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the
1402 next possible position in C<s> that could begin a non-malformed character.
1403 See L</utf8n_to_uvchr> for details on when the REPLACEMENT CHARACTER is returned.
1409 Perl_utf8_to_uvchr(pTHX_ const U8 *s, STRLEN *retlen)
1411 PERL_ARGS_ASSERT_UTF8_TO_UVCHR;
1413 /* This function is unsafe if malformed UTF-8 input is given it, which is
1414 * why the function is deprecated. If the first byte of the input
1415 * indicates that there are more bytes remaining in the sequence that forms
1416 * the character than there are in the input buffer, it can read past the
1417 * end. But we can make it safe if the input string happens to be
1418 * NUL-terminated, as many strings in Perl are, by refusing to read past a
1419 * NUL, which is what UTF8_CHK_SKIP() does. A NUL indicates the start of
1420 * the next character anyway. If the input isn't NUL-terminated, the
1421 * function remains unsafe, as it always has been. */
1423 return utf8_to_uvchr_buf(s, s + UTF8_CHK_SKIP(s), retlen);
1428 #endif /* NO_MATHOMS */
1431 * ex: set ts=8 sts=4 sw=4 et: