1=head1 NAME 2 3perlapi - autogenerated documentation for the perl public API 4 5=head1 DESCRIPTION 6X<Perl API> X<API> X<api> 7 8This file contains the documentation of the perl public API generated by 9embed.pl, specifically a listing of functions, macros, flags, and variables 10that may be used by extension writers. The interfaces of any functions that 11are not listed here are subject to change without notice. For this reason, 12blindly using functions listed in proto.h is to be avoided when writing 13extensions. 14 15Note that all Perl API global variables must be referenced with the C<PL_> 16prefix. Some macros are provided for compatibility with the older, 17unadorned names, but this support may be disabled in a future release. 18 19The listing is alphabetical, case insensitive. 20 21 22=head1 "Gimme" Values 23 24=over 8 25 26=item GIMME 27X<GIMME> 28 29A backward-compatible version of C<GIMME_V> which can only return 30C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>. 31Deprecated. Use C<GIMME_V> instead. 32 33 U32 GIMME 34 35=for hackers 36Found in file op.h 37 38=item GIMME_V 39X<GIMME_V> 40 41The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>, 42C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context, 43respectively. 44 45 U32 GIMME_V 46 47=for hackers 48Found in file op.h 49 50=item G_ARRAY 51X<G_ARRAY> 52 53Used to indicate list context. See C<GIMME_V>, C<GIMME> and 54L<perlcall>. 55 56=for hackers 57Found in file cop.h 58 59=item G_DISCARD 60X<G_DISCARD> 61 62Indicates that arguments returned from a callback should be discarded. See 63L<perlcall>. 64 65=for hackers 66Found in file cop.h 67 68=item G_EVAL 69X<G_EVAL> 70 71Used to force a Perl C<eval> wrapper around a callback. See 72L<perlcall>. 73 74=for hackers 75Found in file cop.h 76 77=item G_NOARGS 78X<G_NOARGS> 79 80Indicates that no arguments are being sent to a callback. See 81L<perlcall>. 82 83=for hackers 84Found in file cop.h 85 86=item G_SCALAR 87X<G_SCALAR> 88 89Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and 90L<perlcall>. 91 92=for hackers 93Found in file cop.h 94 95=item G_VOID 96X<G_VOID> 97 98Used to indicate void context. See C<GIMME_V> and L<perlcall>. 99 100=for hackers 101Found in file cop.h 102 103 104=back 105 106=head1 Array Manipulation Functions 107 108=over 8 109 110=item AvFILL 111X<AvFILL> 112 113Same as C<av_len()>. Deprecated, use C<av_len()> instead. 114 115 int AvFILL(AV* av) 116 117=for hackers 118Found in file av.h 119 120=item av_clear 121X<av_clear> 122 123Clears an array, making it empty. Does not free the memory used by the 124array itself. 125 126 void av_clear(AV* ar) 127 128=for hackers 129Found in file av.c 130 131=item av_delete 132X<av_delete> 133 134Deletes the element indexed by C<key> from the array. Returns the 135deleted element. If C<flags> equals C<G_DISCARD>, the element is freed 136and null is returned. 137 138 SV* av_delete(AV* ar, I32 key, I32 flags) 139 140=for hackers 141Found in file av.c 142 143=item av_exists 144X<av_exists> 145 146Returns true if the element indexed by C<key> has been initialized. 147 148This relies on the fact that uninitialized array elements are set to 149C<&PL_sv_undef>. 150 151 bool av_exists(AV* ar, I32 key) 152 153=for hackers 154Found in file av.c 155 156=item av_extend 157X<av_extend> 158 159Pre-extend an array. The C<key> is the index to which the array should be 160extended. 161 162 void av_extend(AV* ar, I32 key) 163 164=for hackers 165Found in file av.c 166 167=item av_fetch 168X<av_fetch> 169 170Returns the SV at the specified index in the array. The C<key> is the 171index. If C<lval> is set then the fetch will be part of a store. Check 172that the return value is non-null before dereferencing it to a C<SV*>. 173 174See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for 175more information on how to use this function on tied arrays. 176 177 SV** av_fetch(AV* ar, I32 key, I32 lval) 178 179=for hackers 180Found in file av.c 181 182=item av_fill 183X<av_fill> 184 185Ensure than an array has a given number of elements, equivalent to 186Perl's C<$#array = $fill;>. 187 188 void av_fill(AV* ar, I32 fill) 189 190=for hackers 191Found in file av.c 192 193=item av_len 194X<av_len> 195 196Returns the highest index in the array. Returns -1 if the array is 197empty. 198 199 I32 av_len(AV* ar) 200 201=for hackers 202Found in file av.c 203 204=item av_make 205X<av_make> 206 207Creates a new AV and populates it with a list of SVs. The SVs are copied 208into the array, so they may be freed after the call to av_make. The new AV 209will have a reference count of 1. 210 211 AV* av_make(I32 size, SV** svp) 212 213=for hackers 214Found in file av.c 215 216=item av_pop 217X<av_pop> 218 219Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array 220is empty. 221 222 SV* av_pop(AV* ar) 223 224=for hackers 225Found in file av.c 226 227=item av_push 228X<av_push> 229 230Pushes an SV onto the end of the array. The array will grow automatically 231to accommodate the addition. 232 233 void av_push(AV* ar, SV* val) 234 235=for hackers 236Found in file av.c 237 238=item av_shift 239X<av_shift> 240 241Shifts an SV off the beginning of the array. 242 243 SV* av_shift(AV* ar) 244 245=for hackers 246Found in file av.c 247 248=item av_store 249X<av_store> 250 251Stores an SV in an array. The array index is specified as C<key>. The 252return value will be NULL if the operation failed or if the value did not 253need to be actually stored within the array (as in the case of tied 254arrays). Otherwise it can be dereferenced to get the original C<SV*>. Note 255that the caller is responsible for suitably incrementing the reference 256count of C<val> before the call, and decrementing it if the function 257returned NULL. 258 259See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for 260more information on how to use this function on tied arrays. 261 262 SV** av_store(AV* ar, I32 key, SV* val) 263 264=for hackers 265Found in file av.c 266 267=item av_undef 268X<av_undef> 269 270Undefines the array. Frees the memory used by the array itself. 271 272 void av_undef(AV* ar) 273 274=for hackers 275Found in file av.c 276 277=item av_unshift 278X<av_unshift> 279 280Unshift the given number of C<undef> values onto the beginning of the 281array. The array will grow automatically to accommodate the addition. You 282must then use C<av_store> to assign values to these new elements. 283 284 void av_unshift(AV* ar, I32 num) 285 286=for hackers 287Found in file av.c 288 289=item get_av 290X<get_av> 291 292Returns the AV of the specified Perl array. If C<create> is set and the 293Perl variable does not exist then it will be created. If C<create> is not 294set and the variable does not exist then NULL is returned. 295 296NOTE: the perl_ form of this function is deprecated. 297 298 AV* get_av(const char* name, I32 create) 299 300=for hackers 301Found in file perl.c 302 303=item newAV 304X<newAV> 305 306Creates a new AV. The reference count is set to 1. 307 308 AV* newAV() 309 310=for hackers 311Found in file av.c 312 313=item sortsv 314X<sortsv> 315 316Sort an array. Here is an example: 317 318 sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale); 319 320See lib/sort.pm for details about controlling the sorting algorithm. 321 322 void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp) 323 324=for hackers 325Found in file pp_sort.c 326 327 328=back 329 330=head1 Callback Functions 331 332=over 8 333 334=item call_argv 335X<call_argv> 336 337Performs a callback to the specified Perl sub. See L<perlcall>. 338 339NOTE: the perl_ form of this function is deprecated. 340 341 I32 call_argv(const char* sub_name, I32 flags, char** argv) 342 343=for hackers 344Found in file perl.c 345 346=item call_method 347X<call_method> 348 349Performs a callback to the specified Perl method. The blessed object must 350be on the stack. See L<perlcall>. 351 352NOTE: the perl_ form of this function is deprecated. 353 354 I32 call_method(const char* methname, I32 flags) 355 356=for hackers 357Found in file perl.c 358 359=item call_pv 360X<call_pv> 361 362Performs a callback to the specified Perl sub. See L<perlcall>. 363 364NOTE: the perl_ form of this function is deprecated. 365 366 I32 call_pv(const char* sub_name, I32 flags) 367 368=for hackers 369Found in file perl.c 370 371=item call_sv 372X<call_sv> 373 374Performs a callback to the Perl sub whose name is in the SV. See 375L<perlcall>. 376 377NOTE: the perl_ form of this function is deprecated. 378 379 I32 call_sv(SV* sv, I32 flags) 380 381=for hackers 382Found in file perl.c 383 384=item ENTER 385X<ENTER> 386 387Opening bracket on a callback. See C<LEAVE> and L<perlcall>. 388 389 ENTER; 390 391=for hackers 392Found in file scope.h 393 394=item eval_pv 395X<eval_pv> 396 397Tells Perl to C<eval> the given string and return an SV* result. 398 399NOTE: the perl_ form of this function is deprecated. 400 401 SV* eval_pv(const char* p, I32 croak_on_error) 402 403=for hackers 404Found in file perl.c 405 406=item eval_sv 407X<eval_sv> 408 409Tells Perl to C<eval> the string in the SV. 410 411NOTE: the perl_ form of this function is deprecated. 412 413 I32 eval_sv(SV* sv, I32 flags) 414 415=for hackers 416Found in file perl.c 417 418=item FREETMPS 419X<FREETMPS> 420 421Closing bracket for temporaries on a callback. See C<SAVETMPS> and 422L<perlcall>. 423 424 FREETMPS; 425 426=for hackers 427Found in file scope.h 428 429=item LEAVE 430X<LEAVE> 431 432Closing bracket on a callback. See C<ENTER> and L<perlcall>. 433 434 LEAVE; 435 436=for hackers 437Found in file scope.h 438 439=item SAVETMPS 440X<SAVETMPS> 441 442Opening bracket for temporaries on a callback. See C<FREETMPS> and 443L<perlcall>. 444 445 SAVETMPS; 446 447=for hackers 448Found in file scope.h 449 450 451=back 452 453=head1 Character classes 454 455=over 8 456 457=item isALNUM 458X<isALNUM> 459 460Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric 461character (including underscore) or digit. 462 463 bool isALNUM(char ch) 464 465=for hackers 466Found in file handy.h 467 468=item isALPHA 469X<isALPHA> 470 471Returns a boolean indicating whether the C C<char> is an ASCII alphabetic 472character. 473 474 bool isALPHA(char ch) 475 476=for hackers 477Found in file handy.h 478 479=item isDIGIT 480X<isDIGIT> 481 482Returns a boolean indicating whether the C C<char> is an ASCII 483digit. 484 485 bool isDIGIT(char ch) 486 487=for hackers 488Found in file handy.h 489 490=item isLOWER 491X<isLOWER> 492 493Returns a boolean indicating whether the C C<char> is a lowercase 494character. 495 496 bool isLOWER(char ch) 497 498=for hackers 499Found in file handy.h 500 501=item isSPACE 502X<isSPACE> 503 504Returns a boolean indicating whether the C C<char> is whitespace. 505 506 bool isSPACE(char ch) 507 508=for hackers 509Found in file handy.h 510 511=item isUPPER 512X<isUPPER> 513 514Returns a boolean indicating whether the C C<char> is an uppercase 515character. 516 517 bool isUPPER(char ch) 518 519=for hackers 520Found in file handy.h 521 522=item toLOWER 523X<toLOWER> 524 525Converts the specified character to lowercase. 526 527 char toLOWER(char ch) 528 529=for hackers 530Found in file handy.h 531 532=item toUPPER 533X<toUPPER> 534 535Converts the specified character to uppercase. 536 537 char toUPPER(char ch) 538 539=for hackers 540Found in file handy.h 541 542 543=back 544 545=head1 Cloning an interpreter 546 547=over 8 548 549=item perl_clone 550X<perl_clone> 551 552Create and return a new interpreter by cloning the current one. 553 554perl_clone takes these flags as parameters: 555 556CLONEf_COPY_STACKS - is used to, well, copy the stacks also, 557without it we only clone the data and zero the stacks, 558with it we copy the stacks and the new perl interpreter is 559ready to run at the exact same point as the previous one. 560The pseudo-fork code uses COPY_STACKS while the 561threads->new doesn't. 562 563CLONEf_KEEP_PTR_TABLE 564perl_clone keeps a ptr_table with the pointer of the old 565variable as a key and the new variable as a value, 566this allows it to check if something has been cloned and not 567clone it again but rather just use the value and increase the 568refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill 569the ptr_table using the function 570C<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>, 571reason to keep it around is if you want to dup some of your own 572variable who are outside the graph perl scans, example of this 573code is in threads.xs create 574 575CLONEf_CLONE_HOST 576This is a win32 thing, it is ignored on unix, it tells perls 577win32host code (which is c++) to clone itself, this is needed on 578win32 if you want to run two threads at the same time, 579if you just want to do some stuff in a separate perl interpreter 580and then throw it away and return to the original one, 581you don't need to do anything. 582 583 PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags) 584 585=for hackers 586Found in file sv.c 587 588 589=back 590 591=head1 CV Manipulation Functions 592 593=over 8 594 595=item CvSTASH 596X<CvSTASH> 597 598Returns the stash of the CV. 599 600 HV* CvSTASH(CV* cv) 601 602=for hackers 603Found in file cv.h 604 605=item get_cv 606X<get_cv> 607 608Returns the CV of the specified Perl subroutine. If C<create> is set and 609the Perl subroutine does not exist then it will be declared (which has the 610same effect as saying C<sub name;>). If C<create> is not set and the 611subroutine does not exist then NULL is returned. 612 613NOTE: the perl_ form of this function is deprecated. 614 615 CV* get_cv(const char* name, I32 create) 616 617=for hackers 618Found in file perl.c 619 620 621=back 622 623=head1 Embedding Functions 624 625=over 8 626 627=item cv_undef 628X<cv_undef> 629 630Clear out all the active components of a CV. This can happen either 631by an explicit C<undef &foo>, or by the reference count going to zero. 632In the former case, we keep the CvOUTSIDE pointer, so that any anonymous 633children can still follow the full lexical scope chain. 634 635 void cv_undef(CV* cv) 636 637=for hackers 638Found in file op.c 639 640=item load_module 641X<load_module> 642 643Loads the module whose name is pointed to by the string part of name. 644Note that the actual module name, not its filename, should be given. 645Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of 646PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS 647(or 0 for no flags). ver, if specified, provides version semantics 648similar to C<use Foo::Bar VERSION>. The optional trailing SV* 649arguments can be used to specify arguments to the module's import() 650method, similar to C<use Foo::Bar VERSION LIST>. 651 652 void load_module(U32 flags, SV* name, SV* ver, ...) 653 654=for hackers 655Found in file op.c 656 657=item nothreadhook 658X<nothreadhook> 659 660Stub that provides thread hook for perl_destruct when there are 661no threads. 662 663 int nothreadhook() 664 665=for hackers 666Found in file perl.c 667 668=item perl_alloc 669X<perl_alloc> 670 671Allocates a new Perl interpreter. See L<perlembed>. 672 673 PerlInterpreter* perl_alloc() 674 675=for hackers 676Found in file perl.c 677 678=item perl_construct 679X<perl_construct> 680 681Initializes a new Perl interpreter. See L<perlembed>. 682 683 void perl_construct(PerlInterpreter* interp) 684 685=for hackers 686Found in file perl.c 687 688=item perl_destruct 689X<perl_destruct> 690 691Shuts down a Perl interpreter. See L<perlembed>. 692 693 int perl_destruct(PerlInterpreter* interp) 694 695=for hackers 696Found in file perl.c 697 698=item perl_free 699X<perl_free> 700 701Releases a Perl interpreter. See L<perlembed>. 702 703 void perl_free(PerlInterpreter* interp) 704 705=for hackers 706Found in file perl.c 707 708=item perl_parse 709X<perl_parse> 710 711Tells a Perl interpreter to parse a Perl script. See L<perlembed>. 712 713 int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env) 714 715=for hackers 716Found in file perl.c 717 718=item perl_run 719X<perl_run> 720 721Tells a Perl interpreter to run. See L<perlembed>. 722 723 int perl_run(PerlInterpreter* interp) 724 725=for hackers 726Found in file perl.c 727 728=item require_pv 729X<require_pv> 730 731Tells Perl to C<require> the file named by the string argument. It is 732analogous to the Perl code C<eval "require '$file'">. It's even 733implemented that way; consider using load_module instead. 734 735NOTE: the perl_ form of this function is deprecated. 736 737 void require_pv(const char* pv) 738 739=for hackers 740Found in file perl.c 741 742 743=back 744 745=head1 Functions in file pp_pack.c 746 747 748=over 8 749 750=item packlist 751X<packlist> 752 753The engine implementing pack() Perl function. 754 755 void packlist(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist) 756 757=for hackers 758Found in file pp_pack.c 759 760=item pack_cat 761X<pack_cat> 762 763The engine implementing pack() Perl function. Note: parameters next_in_list and 764flags are not used. This call should not be used; use packlist instead. 765 766 void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) 767 768=for hackers 769Found in file pp_pack.c 770 771=item unpackstring 772X<unpackstring> 773 774The engine implementing unpack() Perl function. C<unpackstring> puts the 775extracted list items on the stack and returns the number of elements. 776Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function. 777 778 I32 unpackstring(char *pat, char *patend, char *s, char *strend, U32 flags) 779 780=for hackers 781Found in file pp_pack.c 782 783=item unpack_str 784X<unpack_str> 785 786The engine implementing unpack() Perl function. Note: parameters strbeg, new_s 787and ocnt are not used. This call should not be used, use unpackstring instead. 788 789 I32 unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags) 790 791=for hackers 792Found in file pp_pack.c 793 794 795=back 796 797=head1 Global Variables 798 799=over 8 800 801=item PL_modglobal 802X<PL_modglobal> 803 804C<PL_modglobal> is a general purpose, interpreter global HV for use by 805extensions that need to keep information on a per-interpreter basis. 806In a pinch, it can also be used as a symbol table for extensions 807to share data among each other. It is a good idea to use keys 808prefixed by the package name of the extension that owns the data. 809 810 HV* PL_modglobal 811 812=for hackers 813Found in file intrpvar.h 814 815=item PL_na 816X<PL_na> 817 818A convenience variable which is typically used with C<SvPV> when one 819doesn't care about the length of the string. It is usually more efficient 820to either declare a local variable and use that instead or to use the 821C<SvPV_nolen> macro. 822 823 STRLEN PL_na 824 825=for hackers 826Found in file thrdvar.h 827 828=item PL_sv_no 829X<PL_sv_no> 830 831This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as 832C<&PL_sv_no>. 833 834 SV PL_sv_no 835 836=for hackers 837Found in file intrpvar.h 838 839=item PL_sv_undef 840X<PL_sv_undef> 841 842This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>. 843 844 SV PL_sv_undef 845 846=for hackers 847Found in file intrpvar.h 848 849=item PL_sv_yes 850X<PL_sv_yes> 851 852This is the C<true> SV. See C<PL_sv_no>. Always refer to this as 853C<&PL_sv_yes>. 854 855 SV PL_sv_yes 856 857=for hackers 858Found in file intrpvar.h 859 860 861=back 862 863=head1 GV Functions 864 865=over 8 866 867=item GvSV 868X<GvSV> 869 870Return the SV from the GV. 871 872 SV* GvSV(GV* gv) 873 874=for hackers 875Found in file gv.h 876 877=item gv_fetchmeth 878X<gv_fetchmeth> 879 880Returns the glob with the given C<name> and a defined subroutine or 881C<NULL>. The glob lives in the given C<stash>, or in the stashes 882accessible via @ISA and UNIVERSAL::. 883 884The argument C<level> should be either 0 or -1. If C<level==0>, as a 885side-effect creates a glob with the given C<name> in the given C<stash> 886which in the case of success contains an alias for the subroutine, and sets 887up caching info for this glob. Similarly for all the searched stashes. 888 889This function grants C<"SUPER"> token as a postfix of the stash name. The 890GV returned from C<gv_fetchmeth> may be a method cache entry, which is not 891visible to Perl code. So when calling C<call_sv>, you should not use 892the GV directly; instead, you should use the method's CV, which can be 893obtained from the GV with the C<GvCV> macro. 894 895 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level) 896 897=for hackers 898Found in file gv.c 899 900=item gv_fetchmethod 901X<gv_fetchmethod> 902 903See L<gv_fetchmethod_autoload>. 904 905 GV* gv_fetchmethod(HV* stash, const char* name) 906 907=for hackers 908Found in file gv.c 909 910=item gv_fetchmethod_autoload 911X<gv_fetchmethod_autoload> 912 913Returns the glob which contains the subroutine to call to invoke the method 914on the C<stash>. In fact in the presence of autoloading this may be the 915glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is 916already setup. 917 918The third parameter of C<gv_fetchmethod_autoload> determines whether 919AUTOLOAD lookup is performed if the given method is not present: non-zero 920means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. 921Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload> 922with a non-zero C<autoload> parameter. 923 924These functions grant C<"SUPER"> token as a prefix of the method name. Note 925that if you want to keep the returned glob for a long time, you need to 926check for it being "AUTOLOAD", since at the later time the call may load a 927different subroutine due to $AUTOLOAD changing its value. Use the glob 928created via a side effect to do this. 929 930These functions have the same side-effects and as C<gv_fetchmeth> with 931C<level==0>. C<name> should be writable if contains C<':'> or C<' 932''>. The warning against passing the GV returned by C<gv_fetchmeth> to 933C<call_sv> apply equally to these functions. 934 935 GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload) 936 937=for hackers 938Found in file gv.c 939 940=item gv_fetchmeth_autoload 941X<gv_fetchmeth_autoload> 942 943Same as gv_fetchmeth(), but looks for autoloaded subroutines too. 944Returns a glob for the subroutine. 945 946For an autoloaded subroutine without a GV, will create a GV even 947if C<level < 0>. For an autoloaded subroutine without a stub, GvCV() 948of the result may be zero. 949 950 GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level) 951 952=for hackers 953Found in file gv.c 954 955=item gv_stashpv 956X<gv_stashpv> 957 958Returns a pointer to the stash for a specified package. C<name> should 959be a valid UTF-8 string and must be null-terminated. If C<create> is set 960then the package will be created if it does not already exist. If C<create> 961is not set and the package does not exist then NULL is returned. 962 963 HV* gv_stashpv(const char* name, I32 create) 964 965=for hackers 966Found in file gv.c 967 968=item gv_stashpvn 969X<gv_stashpvn> 970 971Returns a pointer to the stash for a specified package. C<name> should 972be a valid UTF-8 string. The C<namelen> parameter indicates the length of 973the C<name>, in bytes. If C<create> is set then the package will be 974created if it does not already exist. If C<create> is not set and the 975package does not exist then NULL is returned. 976 977 HV* gv_stashpvn(const char* name, U32 namelen, I32 create) 978 979=for hackers 980Found in file gv.c 981 982=item gv_stashsv 983X<gv_stashsv> 984 985Returns a pointer to the stash for a specified package, which must be a 986valid UTF-8 string. See C<gv_stashpv>. 987 988 HV* gv_stashsv(SV* sv, I32 create) 989 990=for hackers 991Found in file gv.c 992 993 994=back 995 996=head1 Handy Values 997 998=over 8 999 1000=item Nullav 1001X<Nullav> 1002 1003Null AV pointer. 1004 1005=for hackers 1006Found in file av.h 1007 1008=item Nullch 1009X<Nullch> 1010 1011Null character pointer. 1012 1013=for hackers 1014Found in file handy.h 1015 1016=item Nullcv 1017X<Nullcv> 1018 1019Null CV pointer. 1020 1021=for hackers 1022Found in file cv.h 1023 1024=item Nullhv 1025X<Nullhv> 1026 1027Null HV pointer. 1028 1029=for hackers 1030Found in file hv.h 1031 1032=item Nullsv 1033X<Nullsv> 1034 1035Null SV pointer. 1036 1037=for hackers 1038Found in file handy.h 1039 1040 1041=back 1042 1043=head1 Hash Manipulation Functions 1044 1045=over 8 1046 1047=item get_hv 1048X<get_hv> 1049 1050Returns the HV of the specified Perl hash. If C<create> is set and the 1051Perl variable does not exist then it will be created. If C<create> is not 1052set and the variable does not exist then NULL is returned. 1053 1054NOTE: the perl_ form of this function is deprecated. 1055 1056 HV* get_hv(const char* name, I32 create) 1057 1058=for hackers 1059Found in file perl.c 1060 1061=item HEf_SVKEY 1062X<HEf_SVKEY> 1063 1064This flag, used in the length slot of hash entries and magic structures, 1065specifies the structure contains an C<SV*> pointer where a C<char*> pointer 1066is to be expected. (For information only--not to be used). 1067 1068=for hackers 1069Found in file hv.h 1070 1071=item HeHASH 1072X<HeHASH> 1073 1074Returns the computed hash stored in the hash entry. 1075 1076 U32 HeHASH(HE* he) 1077 1078=for hackers 1079Found in file hv.h 1080 1081=item HeKEY 1082X<HeKEY> 1083 1084Returns the actual pointer stored in the key slot of the hash entry. The 1085pointer may be either C<char*> or C<SV*>, depending on the value of 1086C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are 1087usually preferable for finding the value of a key. 1088 1089 void* HeKEY(HE* he) 1090 1091=for hackers 1092Found in file hv.h 1093 1094=item HeKLEN 1095X<HeKLEN> 1096 1097If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry 1098holds an C<SV*> key. Otherwise, holds the actual length of the key. Can 1099be assigned to. The C<HePV()> macro is usually preferable for finding key 1100lengths. 1101 1102 STRLEN HeKLEN(HE* he) 1103 1104=for hackers 1105Found in file hv.h 1106 1107=item HePV 1108X<HePV> 1109 1110Returns the key slot of the hash entry as a C<char*> value, doing any 1111necessary dereferencing of possibly C<SV*> keys. The length of the string 1112is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do 1113not care about what the length of the key is, you may use the global 1114variable C<PL_na>, though this is rather less efficient than using a local 1115variable. Remember though, that hash keys in perl are free to contain 1116embedded nulls, so using C<strlen()> or similar is not a good way to find 1117the length of hash keys. This is very similar to the C<SvPV()> macro 1118described elsewhere in this document. 1119 1120 char* HePV(HE* he, STRLEN len) 1121 1122=for hackers 1123Found in file hv.h 1124 1125=item HeSVKEY 1126X<HeSVKEY> 1127 1128Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not 1129contain an C<SV*> key. 1130 1131 SV* HeSVKEY(HE* he) 1132 1133=for hackers 1134Found in file hv.h 1135 1136=item HeSVKEY_force 1137X<HeSVKEY_force> 1138 1139Returns the key as an C<SV*>. Will create and return a temporary mortal 1140C<SV*> if the hash entry contains only a C<char*> key. 1141 1142 SV* HeSVKEY_force(HE* he) 1143 1144=for hackers 1145Found in file hv.h 1146 1147=item HeSVKEY_set 1148X<HeSVKEY_set> 1149 1150Sets the key to a given C<SV*>, taking care to set the appropriate flags to 1151indicate the presence of an C<SV*> key, and returns the same 1152C<SV*>. 1153 1154 SV* HeSVKEY_set(HE* he, SV* sv) 1155 1156=for hackers 1157Found in file hv.h 1158 1159=item HeVAL 1160X<HeVAL> 1161 1162Returns the value slot (type C<SV*>) stored in the hash entry. 1163 1164 SV* HeVAL(HE* he) 1165 1166=for hackers 1167Found in file hv.h 1168 1169=item HvNAME 1170X<HvNAME> 1171 1172Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>. 1173 1174 char* HvNAME(HV* stash) 1175 1176=for hackers 1177Found in file hv.h 1178 1179=item hv_clear 1180X<hv_clear> 1181 1182Clears a hash, making it empty. 1183 1184 void hv_clear(HV* tb) 1185 1186=for hackers 1187Found in file hv.c 1188 1189=item hv_clear_placeholders 1190X<hv_clear_placeholders> 1191 1192Clears any placeholders from a hash. If a restricted hash has any of its keys 1193marked as readonly and the key is subsequently deleted, the key is not actually 1194deleted but is marked by assigning it a value of &PL_sv_placeholder. This tags 1195it so it will be ignored by future operations such as iterating over the hash, 1196but will still allow the hash to have a value reassigned to the key at some 1197future point. This function clears any such placeholder keys from the hash. 1198See Hash::Util::lock_keys() for an example of its use. 1199 1200 void hv_clear_placeholders(HV* hb) 1201 1202=for hackers 1203Found in file hv.c 1204 1205=item hv_delete 1206X<hv_delete> 1207 1208Deletes a key/value pair in the hash. The value SV is removed from the 1209hash and returned to the caller. The C<klen> is the length of the key. 1210The C<flags> value will normally be zero; if set to G_DISCARD then NULL 1211will be returned. 1212 1213 SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags) 1214 1215=for hackers 1216Found in file hv.c 1217 1218=item hv_delete_ent 1219X<hv_delete_ent> 1220 1221Deletes a key/value pair in the hash. The value SV is removed from the 1222hash and returned to the caller. The C<flags> value will normally be zero; 1223if set to G_DISCARD then NULL will be returned. C<hash> can be a valid 1224precomputed hash value, or 0 to ask for it to be computed. 1225 1226 SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash) 1227 1228=for hackers 1229Found in file hv.c 1230 1231=item hv_exists 1232X<hv_exists> 1233 1234Returns a boolean indicating whether the specified hash key exists. The 1235C<klen> is the length of the key. 1236 1237 bool hv_exists(HV* tb, const char* key, I32 klen) 1238 1239=for hackers 1240Found in file hv.c 1241 1242=item hv_exists_ent 1243X<hv_exists_ent> 1244 1245Returns a boolean indicating whether the specified hash key exists. C<hash> 1246can be a valid precomputed hash value, or 0 to ask for it to be 1247computed. 1248 1249 bool hv_exists_ent(HV* tb, SV* key, U32 hash) 1250 1251=for hackers 1252Found in file hv.c 1253 1254=item hv_fetch 1255X<hv_fetch> 1256 1257Returns the SV which corresponds to the specified key in the hash. The 1258C<klen> is the length of the key. If C<lval> is set then the fetch will be 1259part of a store. Check that the return value is non-null before 1260dereferencing it to an C<SV*>. 1261 1262See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more 1263information on how to use this function on tied hashes. 1264 1265 SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval) 1266 1267=for hackers 1268Found in file hv.c 1269 1270=item hv_fetch_ent 1271X<hv_fetch_ent> 1272 1273Returns the hash entry which corresponds to the specified key in the hash. 1274C<hash> must be a valid precomputed hash number for the given C<key>, or 0 1275if you want the function to compute it. IF C<lval> is set then the fetch 1276will be part of a store. Make sure the return value is non-null before 1277accessing it. The return value when C<tb> is a tied hash is a pointer to a 1278static location, so be sure to make a copy of the structure if you need to 1279store it somewhere. 1280 1281See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more 1282information on how to use this function on tied hashes. 1283 1284 HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash) 1285 1286=for hackers 1287Found in file hv.c 1288 1289=item hv_iterinit 1290X<hv_iterinit> 1291 1292Prepares a starting point to traverse a hash table. Returns the number of 1293keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is 1294currently only meaningful for hashes without tie magic. 1295 1296NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of 1297hash buckets that happen to be in use. If you still need that esoteric 1298value, you can get it through the macro C<HvFILL(tb)>. 1299 1300 1301 I32 hv_iterinit(HV* tb) 1302 1303=for hackers 1304Found in file hv.c 1305 1306=item hv_iterkey 1307X<hv_iterkey> 1308 1309Returns the key from the current position of the hash iterator. See 1310C<hv_iterinit>. 1311 1312 char* hv_iterkey(HE* entry, I32* retlen) 1313 1314=for hackers 1315Found in file hv.c 1316 1317=item hv_iterkeysv 1318X<hv_iterkeysv> 1319 1320Returns the key as an C<SV*> from the current position of the hash 1321iterator. The return value will always be a mortal copy of the key. Also 1322see C<hv_iterinit>. 1323 1324 SV* hv_iterkeysv(HE* entry) 1325 1326=for hackers 1327Found in file hv.c 1328 1329=item hv_iternext 1330X<hv_iternext> 1331 1332Returns entries from a hash iterator. See C<hv_iterinit>. 1333 1334You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the 1335iterator currently points to, without losing your place or invalidating your 1336iterator. Note that in this case the current entry is deleted from the hash 1337with your iterator holding the last reference to it. Your iterator is flagged 1338to free the entry on the next call to C<hv_iternext>, so you must not discard 1339your iterator immediately else the entry will leak - call C<hv_iternext> to 1340trigger the resource deallocation. 1341 1342 HE* hv_iternext(HV* tb) 1343 1344=for hackers 1345Found in file hv.c 1346 1347=item hv_iternextsv 1348X<hv_iternextsv> 1349 1350Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one 1351operation. 1352 1353 SV* hv_iternextsv(HV* hv, char** key, I32* retlen) 1354 1355=for hackers 1356Found in file hv.c 1357 1358=item hv_iternext_flags 1359X<hv_iternext_flags> 1360 1361Returns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>. 1362The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is 1363set the placeholders keys (for restricted hashes) will be returned in addition 1364to normal keys. By default placeholders are automatically skipped over. 1365Currently a placeholder is implemented with a value that is 1366C<&Perl_sv_placeholder>. Note that the implementation of placeholders and 1367restricted hashes may change, and the implementation currently is 1368insufficiently abstracted for any change to be tidy. 1369 1370NOTE: this function is experimental and may change or be 1371removed without notice. 1372 1373 HE* hv_iternext_flags(HV* tb, I32 flags) 1374 1375=for hackers 1376Found in file hv.c 1377 1378=item hv_iterval 1379X<hv_iterval> 1380 1381Returns the value from the current position of the hash iterator. See 1382C<hv_iterkey>. 1383 1384 SV* hv_iterval(HV* tb, HE* entry) 1385 1386=for hackers 1387Found in file hv.c 1388 1389=item hv_magic 1390X<hv_magic> 1391 1392Adds magic to a hash. See C<sv_magic>. 1393 1394 void hv_magic(HV* hv, GV* gv, int how) 1395 1396=for hackers 1397Found in file hv.c 1398 1399=item hv_scalar 1400X<hv_scalar> 1401 1402Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied. 1403 1404 SV* hv_scalar(HV* hv) 1405 1406=for hackers 1407Found in file hv.c 1408 1409=item hv_store 1410X<hv_store> 1411 1412Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is 1413the length of the key. The C<hash> parameter is the precomputed hash 1414value; if it is zero then Perl will compute it. The return value will be 1415NULL if the operation failed or if the value did not need to be actually 1416stored within the hash (as in the case of tied hashes). Otherwise it can 1417be dereferenced to get the original C<SV*>. Note that the caller is 1418responsible for suitably incrementing the reference count of C<val> before 1419the call, and decrementing it if the function returned NULL. Effectively 1420a successful hv_store takes ownership of one reference to C<val>. This is 1421usually what you want; a newly created SV has a reference count of one, so 1422if all your code does is create SVs then store them in a hash, hv_store 1423will own the only reference to the new SV, and your code doesn't need to do 1424anything further to tidy up. hv_store is not implemented as a call to 1425hv_store_ent, and does not create a temporary SV for the key, so if your 1426key data is not already in SV form then use hv_store in preference to 1427hv_store_ent. 1428 1429See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more 1430information on how to use this function on tied hashes. 1431 1432 SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash) 1433 1434=for hackers 1435Found in file hv.c 1436 1437=item hv_store_ent 1438X<hv_store_ent> 1439 1440Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash> 1441parameter is the precomputed hash value; if it is zero then Perl will 1442compute it. The return value is the new hash entry so created. It will be 1443NULL if the operation failed or if the value did not need to be actually 1444stored within the hash (as in the case of tied hashes). Otherwise the 1445contents of the return value can be accessed using the C<He?> macros 1446described here. Note that the caller is responsible for suitably 1447incrementing the reference count of C<val> before the call, and 1448decrementing it if the function returned NULL. Effectively a successful 1449hv_store_ent takes ownership of one reference to C<val>. This is 1450usually what you want; a newly created SV has a reference count of one, so 1451if all your code does is create SVs then store them in a hash, hv_store 1452will own the only reference to the new SV, and your code doesn't need to do 1453anything further to tidy up. Note that hv_store_ent only reads the C<key>; 1454unlike C<val> it does not take ownership of it, so maintaining the correct 1455reference count on C<key> is entirely the caller's responsibility. hv_store 1456is not implemented as a call to hv_store_ent, and does not create a temporary 1457SV for the key, so if your key data is not already in SV form then use 1458hv_store in preference to hv_store_ent. 1459 1460See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more 1461information on how to use this function on tied hashes. 1462 1463 HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash) 1464 1465=for hackers 1466Found in file hv.c 1467 1468=item hv_undef 1469X<hv_undef> 1470 1471Undefines the hash. 1472 1473 void hv_undef(HV* tb) 1474 1475=for hackers 1476Found in file hv.c 1477 1478=item newHV 1479X<newHV> 1480 1481Creates a new HV. The reference count is set to 1. 1482 1483 HV* newHV() 1484 1485=for hackers 1486Found in file hv.c 1487 1488 1489=back 1490 1491=head1 Magical Functions 1492 1493=over 8 1494 1495=item mg_clear 1496X<mg_clear> 1497 1498Clear something magical that the SV represents. See C<sv_magic>. 1499 1500 int mg_clear(SV* sv) 1501 1502=for hackers 1503Found in file mg.c 1504 1505=item mg_copy 1506X<mg_copy> 1507 1508Copies the magic from one SV to another. See C<sv_magic>. 1509 1510 int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen) 1511 1512=for hackers 1513Found in file mg.c 1514 1515=item mg_find 1516X<mg_find> 1517 1518Finds the magic pointer for type matching the SV. See C<sv_magic>. 1519 1520 MAGIC* mg_find(SV* sv, int type) 1521 1522=for hackers 1523Found in file mg.c 1524 1525=item mg_free 1526X<mg_free> 1527 1528Free any magic storage used by the SV. See C<sv_magic>. 1529 1530 int mg_free(SV* sv) 1531 1532=for hackers 1533Found in file mg.c 1534 1535=item mg_get 1536X<mg_get> 1537 1538Do magic after a value is retrieved from the SV. See C<sv_magic>. 1539 1540 int mg_get(SV* sv) 1541 1542=for hackers 1543Found in file mg.c 1544 1545=item mg_length 1546X<mg_length> 1547 1548Report on the SV's length. See C<sv_magic>. 1549 1550 U32 mg_length(SV* sv) 1551 1552=for hackers 1553Found in file mg.c 1554 1555=item mg_magical 1556X<mg_magical> 1557 1558Turns on the magical status of an SV. See C<sv_magic>. 1559 1560 void mg_magical(SV* sv) 1561 1562=for hackers 1563Found in file mg.c 1564 1565=item mg_set 1566X<mg_set> 1567 1568Do magic after a value is assigned to the SV. See C<sv_magic>. 1569 1570 int mg_set(SV* sv) 1571 1572=for hackers 1573Found in file mg.c 1574 1575=item SvGETMAGIC 1576X<SvGETMAGIC> 1577 1578Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its 1579argument more than once. 1580 1581 void SvGETMAGIC(SV* sv) 1582 1583=for hackers 1584Found in file sv.h 1585 1586=item SvLOCK 1587X<SvLOCK> 1588 1589Arranges for a mutual exclusion lock to be obtained on sv if a suitable module 1590has been loaded. 1591 1592 void SvLOCK(SV* sv) 1593 1594=for hackers 1595Found in file sv.h 1596 1597=item SvSETMAGIC 1598X<SvSETMAGIC> 1599 1600Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its 1601argument more than once. 1602 1603 void SvSETMAGIC(SV* sv) 1604 1605=for hackers 1606Found in file sv.h 1607 1608=item SvSetMagicSV 1609X<SvSetMagicSV> 1610 1611Like C<SvSetSV>, but does any set magic required afterwards. 1612 1613 void SvSetMagicSV(SV* dsb, SV* ssv) 1614 1615=for hackers 1616Found in file sv.h 1617 1618=item SvSetMagicSV_nosteal 1619X<SvSetMagicSV_nosteal> 1620 1621Like C<SvSetSV_nosteal>, but does any set magic required afterwards. 1622 1623 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) 1624 1625=for hackers 1626Found in file sv.h 1627 1628=item SvSetSV 1629X<SvSetSV> 1630 1631Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments 1632more than once. 1633 1634 void SvSetSV(SV* dsb, SV* ssv) 1635 1636=for hackers 1637Found in file sv.h 1638 1639=item SvSetSV_nosteal 1640X<SvSetSV_nosteal> 1641 1642Calls a non-destructive version of C<sv_setsv> if dsv is not the same as 1643ssv. May evaluate arguments more than once. 1644 1645 void SvSetSV_nosteal(SV* dsv, SV* ssv) 1646 1647=for hackers 1648Found in file sv.h 1649 1650=item SvSHARE 1651X<SvSHARE> 1652 1653Arranges for sv to be shared between threads if a suitable module 1654has been loaded. 1655 1656 void SvSHARE(SV* sv) 1657 1658=for hackers 1659Found in file sv.h 1660 1661=item SvUNLOCK 1662X<SvUNLOCK> 1663 1664Releases a mutual exclusion lock on sv if a suitable module 1665has been loaded. 1666 1667 void SvUNLOCK(SV* sv) 1668 1669=for hackers 1670Found in file sv.h 1671 1672 1673=back 1674 1675=head1 Memory Management 1676 1677=over 8 1678 1679=item Copy 1680X<Copy> 1681 1682The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the 1683source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is 1684the type. May fail on overlapping copies. See also C<Move>. 1685 1686 void Copy(void* src, void* dest, int nitems, type) 1687 1688=for hackers 1689Found in file handy.h 1690 1691=item CopyD 1692X<CopyD> 1693 1694Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call 1695optimise. 1696 1697 void * CopyD(void* src, void* dest, int nitems, type) 1698 1699=for hackers 1700Found in file handy.h 1701 1702=item Move 1703X<Move> 1704 1705The XSUB-writer's interface to the C C<memmove> function. The C<src> is the 1706source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is 1707the type. Can do overlapping moves. See also C<Copy>. 1708 1709 void Move(void* src, void* dest, int nitems, type) 1710 1711=for hackers 1712Found in file handy.h 1713 1714=item MoveD 1715X<MoveD> 1716 1717Like C<Move> but returns dest. Useful for encouraging compilers to tail-call 1718optimise. 1719 1720 void * MoveD(void* src, void* dest, int nitems, type) 1721 1722=for hackers 1723Found in file handy.h 1724 1725=item Newx 1726X<Newx> 1727 1728The XSUB-writer's interface to the C C<malloc> function. 1729 1730 void Newx(void* ptr, int nitems, type) 1731 1732=for hackers 1733Found in file handy.h 1734 1735=item Newxc 1736X<Newxc> 1737 1738The XSUB-writer's interface to the C C<malloc> function, with 1739cast. 1740 1741 void Newxc(void* ptr, int nitems, type, cast) 1742 1743=for hackers 1744Found in file handy.h 1745 1746=item Newxz 1747X<Newxz> 1748 1749The XSUB-writer's interface to the C C<malloc> function. The allocated 1750memory is zeroed with C<memzero>. 1751 1752In 5.9.3, we removed the 1st parameter, a debug aid, from the api. It 1753was used to uniquely identify each usage of these allocation 1754functions, but was deemed unnecessary with the availability of better 1755memory tracking tools, valgrind for example. 1756 1757 void Newxz(void* ptr, int nitems, type) 1758 1759=for hackers 1760Found in file handy.h 1761 1762=item Poison 1763X<Poison> 1764 1765Fill up memory with a pattern (byte 0xAB over and over again) that 1766hopefully catches attempts to access uninitialized memory. 1767 1768 void Poison(void* dest, int nitems, type) 1769 1770=for hackers 1771Found in file handy.h 1772 1773=item Renew 1774X<Renew> 1775 1776The XSUB-writer's interface to the C C<realloc> function. 1777 1778 void Renew(void* ptr, int nitems, type) 1779 1780=for hackers 1781Found in file handy.h 1782 1783=item Renewc 1784X<Renewc> 1785 1786The XSUB-writer's interface to the C C<realloc> function, with 1787cast. 1788 1789 void Renewc(void* ptr, int nitems, type, cast) 1790 1791=for hackers 1792Found in file handy.h 1793 1794=item Safefree 1795X<Safefree> 1796 1797The XSUB-writer's interface to the C C<free> function. 1798 1799 void Safefree(void* ptr) 1800 1801=for hackers 1802Found in file handy.h 1803 1804=item savepv 1805X<savepv> 1806 1807Perl's version of C<strdup()>. Returns a pointer to a newly allocated 1808string which is a duplicate of C<pv>. The size of the string is 1809determined by C<strlen()>. The memory allocated for the new string can 1810be freed with the C<Safefree()> function. 1811 1812 char* savepv(const char* pv) 1813 1814=for hackers 1815Found in file util.c 1816 1817=item savepvn 1818X<savepvn> 1819 1820Perl's version of what C<strndup()> would be if it existed. Returns a 1821pointer to a newly allocated string which is a duplicate of the first 1822C<len> bytes from C<pv>. The memory allocated for the new string can be 1823freed with the C<Safefree()> function. 1824 1825 char* savepvn(const char* pv, I32 len) 1826 1827=for hackers 1828Found in file util.c 1829 1830=item savesharedpv 1831X<savesharedpv> 1832 1833A version of C<savepv()> which allocates the duplicate string in memory 1834which is shared between threads. 1835 1836 char* savesharedpv(const char* pv) 1837 1838=for hackers 1839Found in file util.c 1840 1841=item savesvpv 1842X<savesvpv> 1843 1844A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from 1845the passed in SV using C<SvPV()> 1846 1847 char* savesvpv(SV* sv) 1848 1849=for hackers 1850Found in file util.c 1851 1852=item StructCopy 1853X<StructCopy> 1854 1855This is an architecture-independent macro to copy one structure to another. 1856 1857 void StructCopy(type src, type dest, type) 1858 1859=for hackers 1860Found in file handy.h 1861 1862=item Zero 1863X<Zero> 1864 1865The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the 1866destination, C<nitems> is the number of items, and C<type> is the type. 1867 1868 void Zero(void* dest, int nitems, type) 1869 1870=for hackers 1871Found in file handy.h 1872 1873=item ZeroD 1874X<ZeroD> 1875 1876Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call 1877optimise. 1878 1879 void * ZeroD(void* dest, int nitems, type) 1880 1881=for hackers 1882Found in file handy.h 1883 1884 1885=back 1886 1887=head1 Miscellaneous Functions 1888 1889=over 8 1890 1891=item fbm_compile 1892X<fbm_compile> 1893 1894Analyses the string in order to make fast searches on it using fbm_instr() 1895-- the Boyer-Moore algorithm. 1896 1897 void fbm_compile(SV* sv, U32 flags) 1898 1899=for hackers 1900Found in file util.c 1901 1902=item fbm_instr 1903X<fbm_instr> 1904 1905Returns the location of the SV in the string delimited by C<str> and 1906C<strend>. It returns C<Nullch> if the string can't be found. The C<sv> 1907does not have to be fbm_compiled, but the search will not be as fast 1908then. 1909 1910 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags) 1911 1912=for hackers 1913Found in file util.c 1914 1915=item form 1916X<form> 1917 1918Takes a sprintf-style format pattern and conventional 1919(non-SV) arguments and returns the formatted string. 1920 1921 (char *) Perl_form(pTHX_ const char* pat, ...) 1922 1923can be used any place a string (char *) is required: 1924 1925 char * s = Perl_form("%d.%d",major,minor); 1926 1927Uses a single private buffer so if you want to format several strings you 1928must explicitly copy the earlier strings away (and free the copies when you 1929are done). 1930 1931 char* form(const char* pat, ...) 1932 1933=for hackers 1934Found in file util.c 1935 1936=item getcwd_sv 1937X<getcwd_sv> 1938 1939Fill the sv with current working directory 1940 1941 int getcwd_sv(SV* sv) 1942 1943=for hackers 1944Found in file util.c 1945 1946=item strEQ 1947X<strEQ> 1948 1949Test two strings to see if they are equal. Returns true or false. 1950 1951 bool strEQ(char* s1, char* s2) 1952 1953=for hackers 1954Found in file handy.h 1955 1956=item strGE 1957X<strGE> 1958 1959Test two strings to see if the first, C<s1>, is greater than or equal to 1960the second, C<s2>. Returns true or false. 1961 1962 bool strGE(char* s1, char* s2) 1963 1964=for hackers 1965Found in file handy.h 1966 1967=item strGT 1968X<strGT> 1969 1970Test two strings to see if the first, C<s1>, is greater than the second, 1971C<s2>. Returns true or false. 1972 1973 bool strGT(char* s1, char* s2) 1974 1975=for hackers 1976Found in file handy.h 1977 1978=item strLE 1979X<strLE> 1980 1981Test two strings to see if the first, C<s1>, is less than or equal to the 1982second, C<s2>. Returns true or false. 1983 1984 bool strLE(char* s1, char* s2) 1985 1986=for hackers 1987Found in file handy.h 1988 1989=item strLT 1990X<strLT> 1991 1992Test two strings to see if the first, C<s1>, is less than the second, 1993C<s2>. Returns true or false. 1994 1995 bool strLT(char* s1, char* s2) 1996 1997=for hackers 1998Found in file handy.h 1999 2000=item strNE 2001X<strNE> 2002 2003Test two strings to see if they are different. Returns true or 2004false. 2005 2006 bool strNE(char* s1, char* s2) 2007 2008=for hackers 2009Found in file handy.h 2010 2011=item strnEQ 2012X<strnEQ> 2013 2014Test two strings to see if they are equal. The C<len> parameter indicates 2015the number of bytes to compare. Returns true or false. (A wrapper for 2016C<strncmp>). 2017 2018 bool strnEQ(char* s1, char* s2, STRLEN len) 2019 2020=for hackers 2021Found in file handy.h 2022 2023=item strnNE 2024X<strnNE> 2025 2026Test two strings to see if they are different. The C<len> parameter 2027indicates the number of bytes to compare. Returns true or false. (A 2028wrapper for C<strncmp>). 2029 2030 bool strnNE(char* s1, char* s2, STRLEN len) 2031 2032=for hackers 2033Found in file handy.h 2034 2035=item sv_nolocking 2036X<sv_nolocking> 2037 2038Dummy routine which "locks" an SV when there is no locking module present. 2039Exists to avoid test for a NULL function pointer and because it could potentially warn under 2040some level of strict-ness. 2041 2042 void sv_nolocking(SV *) 2043 2044=for hackers 2045Found in file util.c 2046 2047=item sv_nosharing 2048X<sv_nosharing> 2049 2050Dummy routine which "shares" an SV when there is no sharing module present. 2051Exists to avoid test for a NULL function pointer and because it could potentially warn under 2052some level of strict-ness. 2053 2054 void sv_nosharing(SV *) 2055 2056=for hackers 2057Found in file util.c 2058 2059=item sv_nounlocking 2060X<sv_nounlocking> 2061 2062Dummy routine which "unlocks" an SV when there is no locking module present. 2063Exists to avoid test for a NULL function pointer and because it could potentially warn under 2064some level of strict-ness. 2065 2066 void sv_nounlocking(SV *) 2067 2068=for hackers 2069Found in file util.c 2070 2071 2072=back 2073 2074=head1 Numeric functions 2075 2076=over 8 2077 2078=item grok_bin 2079X<grok_bin> 2080 2081converts a string representing a binary number to numeric form. 2082 2083On entry I<start> and I<*len> give the string to scan, I<*flags> gives 2084conversion flags, and I<result> should be NULL or a pointer to an NV. 2085The scan stops at the end of the string, or the first invalid character. 2086Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an 2087invalid character will also trigger a warning. 2088On return I<*len> is set to the length of the scanned string, 2089and I<*flags> gives output flags. 2090 2091If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear, 2092and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin> 2093returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags, 2094and writes the value to I<*result> (or the value is discarded if I<result> 2095is NULL). 2096 2097The binary number may optionally be prefixed with "0b" or "b" unless 2098C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If 2099C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary 2100number may use '_' characters to separate digits. 2101 2102 UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result) 2103 2104=for hackers 2105Found in file numeric.c 2106 2107=item grok_hex 2108X<grok_hex> 2109 2110converts a string representing a hex number to numeric form. 2111 2112On entry I<start> and I<*len> give the string to scan, I<*flags> gives 2113conversion flags, and I<result> should be NULL or a pointer to an NV. 2114The scan stops at the end of the string, or the first invalid character. 2115Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an 2116invalid character will also trigger a warning. 2117On return I<*len> is set to the length of the scanned string, 2118and I<*flags> gives output flags. 2119 2120If the value is <= UV_MAX it is returned as a UV, the output flags are clear, 2121and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex> 2122returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags, 2123and writes the value to I<*result> (or the value is discarded if I<result> 2124is NULL). 2125 2126The hex number may optionally be prefixed with "0x" or "x" unless 2127C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If 2128C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex 2129number may use '_' characters to separate digits. 2130 2131 UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result) 2132 2133=for hackers 2134Found in file numeric.c 2135 2136=item grok_number 2137X<grok_number> 2138 2139Recognise (or not) a number. The type of the number is returned 2140(0 if unrecognised), otherwise it is a bit-ORed combination of 2141IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT, 2142IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h). 2143 2144If the value of the number can fit an in UV, it is returned in the *valuep 2145IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV 2146will never be set unless *valuep is valid, but *valuep may have been assigned 2147to during processing even though IS_NUMBER_IN_UV is not set on return. 2148If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when 2149valuep is non-NULL, but no actual assignment (or SEGV) will occur. 2150 2151IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were 2152seen (in which case *valuep gives the true value truncated to an integer), and 2153IS_NUMBER_NEG if the number is negative (in which case *valuep holds the 2154absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the 2155number is larger than a UV. 2156 2157 int grok_number(const char *pv, STRLEN len, UV *valuep) 2158 2159=for hackers 2160Found in file numeric.c 2161 2162=item grok_numeric_radix 2163X<grok_numeric_radix> 2164 2165Scan and skip for a numeric decimal separator (radix). 2166 2167 bool grok_numeric_radix(const char **sp, const char *send) 2168 2169=for hackers 2170Found in file numeric.c 2171 2172=item grok_oct 2173X<grok_oct> 2174 2175converts a string representing an octal number to numeric form. 2176 2177On entry I<start> and I<*len> give the string to scan, I<*flags> gives 2178conversion flags, and I<result> should be NULL or a pointer to an NV. 2179The scan stops at the end of the string, or the first invalid character. 2180Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an 2181invalid character will also trigger a warning. 2182On return I<*len> is set to the length of the scanned string, 2183and I<*flags> gives output flags. 2184 2185If the value is <= UV_MAX it is returned as a UV, the output flags are clear, 2186and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct> 2187returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags, 2188and writes the value to I<*result> (or the value is discarded if I<result> 2189is NULL). 2190 2191If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal 2192number may use '_' characters to separate digits. 2193 2194 UV grok_oct(char* start, STRLEN* len_p, I32* flags, NV *result) 2195 2196=for hackers 2197Found in file numeric.c 2198 2199=item scan_bin 2200X<scan_bin> 2201 2202For backwards compatibility. Use C<grok_bin> instead. 2203 2204 NV scan_bin(char* start, STRLEN len, STRLEN* retlen) 2205 2206=for hackers 2207Found in file numeric.c 2208 2209=item scan_hex 2210X<scan_hex> 2211 2212For backwards compatibility. Use C<grok_hex> instead. 2213 2214 NV scan_hex(char* start, STRLEN len, STRLEN* retlen) 2215 2216=for hackers 2217Found in file numeric.c 2218 2219=item scan_oct 2220X<scan_oct> 2221 2222For backwards compatibility. Use C<grok_oct> instead. 2223 2224 NV scan_oct(char* start, STRLEN len, STRLEN* retlen) 2225 2226=for hackers 2227Found in file numeric.c 2228 2229 2230=back 2231 2232=head1 Optree Manipulation Functions 2233 2234=over 8 2235 2236=item cv_const_sv 2237X<cv_const_sv> 2238 2239If C<cv> is a constant sub eligible for inlining. returns the constant 2240value returned by the sub. Otherwise, returns NULL. 2241 2242Constant subs can be created with C<newCONSTSUB> or as described in 2243L<perlsub/"Constant Functions">. 2244 2245 SV* cv_const_sv(CV* cv) 2246 2247=for hackers 2248Found in file op.c 2249 2250=item newCONSTSUB 2251X<newCONSTSUB> 2252 2253Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is 2254eligible for inlining at compile-time. 2255 2256 CV* newCONSTSUB(HV* stash, char* name, SV* sv) 2257 2258=for hackers 2259Found in file op.c 2260 2261=item newXS 2262X<newXS> 2263 2264Used by C<xsubpp> to hook up XSUBs as Perl subs. 2265 2266=for hackers 2267Found in file op.c 2268 2269 2270=back 2271 2272=head1 Pad Data Structures 2273 2274=over 8 2275 2276=item pad_sv 2277X<pad_sv> 2278 2279Get the value at offset po in the current pad. 2280Use macro PAD_SV instead of calling this function directly. 2281 2282 SV* pad_sv(PADOFFSET po) 2283 2284=for hackers 2285Found in file pad.c 2286 2287 2288=back 2289 2290=head1 Stack Manipulation Macros 2291 2292=over 8 2293 2294=item dMARK 2295X<dMARK> 2296 2297Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and 2298C<dORIGMARK>. 2299 2300 dMARK; 2301 2302=for hackers 2303Found in file pp.h 2304 2305=item dORIGMARK 2306X<dORIGMARK> 2307 2308Saves the original stack mark for the XSUB. See C<ORIGMARK>. 2309 2310 dORIGMARK; 2311 2312=for hackers 2313Found in file pp.h 2314 2315=item dSP 2316X<dSP> 2317 2318Declares a local copy of perl's stack pointer for the XSUB, available via 2319the C<SP> macro. See C<SP>. 2320 2321 dSP; 2322 2323=for hackers 2324Found in file pp.h 2325 2326=item EXTEND 2327X<EXTEND> 2328 2329Used to extend the argument stack for an XSUB's return values. Once 2330used, guarantees that there is room for at least C<nitems> to be pushed 2331onto the stack. 2332 2333 void EXTEND(SP, int nitems) 2334 2335=for hackers 2336Found in file pp.h 2337 2338=item MARK 2339X<MARK> 2340 2341Stack marker variable for the XSUB. See C<dMARK>. 2342 2343=for hackers 2344Found in file pp.h 2345 2346=item mPUSHi 2347X<mPUSHi> 2348 2349Push an integer onto the stack. The stack must have room for this element. 2350Handles 'set' magic. Does not use C<TARG>. See also C<PUSHi>, C<mXPUSHi> 2351and C<XPUSHi>. 2352 2353 void mPUSHi(IV iv) 2354 2355=for hackers 2356Found in file pp.h 2357 2358=item mPUSHn 2359X<mPUSHn> 2360 2361Push a double onto the stack. The stack must have room for this element. 2362Handles 'set' magic. Does not use C<TARG>. See also C<PUSHn>, C<mXPUSHn> 2363and C<XPUSHn>. 2364 2365 void mPUSHn(NV nv) 2366 2367=for hackers 2368Found in file pp.h 2369 2370=item mPUSHp 2371X<mPUSHp> 2372 2373Push a string onto the stack. The stack must have room for this element. 2374The C<len> indicates the length of the string. Handles 'set' magic. Does 2375not use C<TARG>. See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>. 2376 2377 void mPUSHp(char* str, STRLEN len) 2378 2379=for hackers 2380Found in file pp.h 2381 2382=item mPUSHu 2383X<mPUSHu> 2384 2385Push an unsigned integer onto the stack. The stack must have room for this 2386element. Handles 'set' magic. Does not use C<TARG>. See also C<PUSHu>, 2387C<mXPUSHu> and C<XPUSHu>. 2388 2389 void mPUSHu(UV uv) 2390 2391=for hackers 2392Found in file pp.h 2393 2394=item mXPUSHi 2395X<mXPUSHi> 2396 2397Push an integer onto the stack, extending the stack if necessary. Handles 2398'set' magic. Does not use C<TARG>. See also C<XPUSHi>, C<mPUSHi> and 2399C<PUSHi>. 2400 2401 void mXPUSHi(IV iv) 2402 2403=for hackers 2404Found in file pp.h 2405 2406=item mXPUSHn 2407X<mXPUSHn> 2408 2409Push a double onto the stack, extending the stack if necessary. Handles 2410'set' magic. Does not use C<TARG>. See also C<XPUSHn>, C<mPUSHn> and 2411C<PUSHn>. 2412 2413 void mXPUSHn(NV nv) 2414 2415=for hackers 2416Found in file pp.h 2417 2418=item mXPUSHp 2419X<mXPUSHp> 2420 2421Push a string onto the stack, extending the stack if necessary. The C<len> 2422indicates the length of the string. Handles 'set' magic. Does not use 2423C<TARG>. See also C<XPUSHp>, C<mPUSHp> and C<PUSHp>. 2424 2425 void mXPUSHp(char* str, STRLEN len) 2426 2427=for hackers 2428Found in file pp.h 2429 2430=item mXPUSHu 2431X<mXPUSHu> 2432 2433Push an unsigned integer onto the stack, extending the stack if necessary. 2434Handles 'set' magic. Does not use C<TARG>. See also C<XPUSHu>, C<mPUSHu> 2435and C<PUSHu>. 2436 2437 void mXPUSHu(UV uv) 2438 2439=for hackers 2440Found in file pp.h 2441 2442=item ORIGMARK 2443X<ORIGMARK> 2444 2445The original stack mark for the XSUB. See C<dORIGMARK>. 2446 2447=for hackers 2448Found in file pp.h 2449 2450=item POPi 2451X<POPi> 2452 2453Pops an integer off the stack. 2454 2455 IV POPi 2456 2457=for hackers 2458Found in file pp.h 2459 2460=item POPl 2461X<POPl> 2462 2463Pops a long off the stack. 2464 2465 long POPl 2466 2467=for hackers 2468Found in file pp.h 2469 2470=item POPn 2471X<POPn> 2472 2473Pops a double off the stack. 2474 2475 NV POPn 2476 2477=for hackers 2478Found in file pp.h 2479 2480=item POPp 2481X<POPp> 2482 2483Pops a string off the stack. Deprecated. New code should use POPpx. 2484 2485 char* POPp 2486 2487=for hackers 2488Found in file pp.h 2489 2490=item POPpbytex 2491X<POPpbytex> 2492 2493Pops a string off the stack which must consist of bytes i.e. characters < 256. 2494 2495 char* POPpbytex 2496 2497=for hackers 2498Found in file pp.h 2499 2500=item POPpx 2501X<POPpx> 2502 2503Pops a string off the stack. 2504 2505 char* POPpx 2506 2507=for hackers 2508Found in file pp.h 2509 2510=item POPs 2511X<POPs> 2512 2513Pops an SV off the stack. 2514 2515 SV* POPs 2516 2517=for hackers 2518Found in file pp.h 2519 2520=item PUSHi 2521X<PUSHi> 2522 2523Push an integer onto the stack. The stack must have room for this element. 2524Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be 2525called to declare it. Do not call multiple C<TARG>-oriented macros to 2526return lists from XSUB's - see C<mPUSHi> instead. See also C<XPUSHi> and 2527C<mXPUSHi>. 2528 2529 void PUSHi(IV iv) 2530 2531=for hackers 2532Found in file pp.h 2533 2534=item PUSHMARK 2535X<PUSHMARK> 2536 2537Opening bracket for arguments on a callback. See C<PUTBACK> and 2538L<perlcall>. 2539 2540 void PUSHMARK(SP) 2541 2542=for hackers 2543Found in file pp.h 2544 2545=item PUSHmortal 2546X<PUSHmortal> 2547 2548Push a new mortal SV onto the stack. The stack must have room for this 2549element. Does not handle 'set' magic. Does not use C<TARG>. See also 2550C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>. 2551 2552 void PUSHmortal() 2553 2554=for hackers 2555Found in file pp.h 2556 2557=item PUSHn 2558X<PUSHn> 2559 2560Push a double onto the stack. The stack must have room for this element. 2561Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be 2562called to declare it. Do not call multiple C<TARG>-oriented macros to 2563return lists from XSUB's - see C<mPUSHn> instead. See also C<XPUSHn> and 2564C<mXPUSHn>. 2565 2566 void PUSHn(NV nv) 2567 2568=for hackers 2569Found in file pp.h 2570 2571=item PUSHp 2572X<PUSHp> 2573 2574Push a string onto the stack. The stack must have room for this element. 2575The C<len> indicates the length of the string. Handles 'set' magic. Uses 2576C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it. Do not 2577call multiple C<TARG>-oriented macros to return lists from XSUB's - see 2578C<mPUSHp> instead. See also C<XPUSHp> and C<mXPUSHp>. 2579 2580 void PUSHp(char* str, STRLEN len) 2581 2582=for hackers 2583Found in file pp.h 2584 2585=item PUSHs 2586X<PUSHs> 2587 2588Push an SV onto the stack. The stack must have room for this element. 2589Does not handle 'set' magic. Does not use C<TARG>. See also C<PUSHmortal>, 2590C<XPUSHs> and C<XPUSHmortal>. 2591 2592 void PUSHs(SV* sv) 2593 2594=for hackers 2595Found in file pp.h 2596 2597=item PUSHu 2598X<PUSHu> 2599 2600Push an unsigned integer onto the stack. The stack must have room for this 2601element. Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> 2602should be called to declare it. Do not call multiple C<TARG>-oriented 2603macros to return lists from XSUB's - see C<mPUSHu> instead. See also 2604C<XPUSHu> and C<mXPUSHu>. 2605 2606 void PUSHu(UV uv) 2607 2608=for hackers 2609Found in file pp.h 2610 2611=item PUTBACK 2612X<PUTBACK> 2613 2614Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>. 2615See C<PUSHMARK> and L<perlcall> for other uses. 2616 2617 PUTBACK; 2618 2619=for hackers 2620Found in file pp.h 2621 2622=item SP 2623X<SP> 2624 2625Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and 2626C<SPAGAIN>. 2627 2628=for hackers 2629Found in file pp.h 2630 2631=item SPAGAIN 2632X<SPAGAIN> 2633 2634Refetch the stack pointer. Used after a callback. See L<perlcall>. 2635 2636 SPAGAIN; 2637 2638=for hackers 2639Found in file pp.h 2640 2641=item XPUSHi 2642X<XPUSHi> 2643 2644Push an integer onto the stack, extending the stack if necessary. Handles 2645'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to 2646declare it. Do not call multiple C<TARG>-oriented macros to return lists 2647from XSUB's - see C<mXPUSHi> instead. See also C<PUSHi> and C<mPUSHi>. 2648 2649 void XPUSHi(IV iv) 2650 2651=for hackers 2652Found in file pp.h 2653 2654=item XPUSHmortal 2655X<XPUSHmortal> 2656 2657Push a new mortal SV onto the stack, extending the stack if necessary. Does 2658not handle 'set' magic. Does not use C<TARG>. See also C<XPUSHs>, 2659C<PUSHmortal> and C<PUSHs>. 2660 2661 void XPUSHmortal() 2662 2663=for hackers 2664Found in file pp.h 2665 2666=item XPUSHn 2667X<XPUSHn> 2668 2669Push a double onto the stack, extending the stack if necessary. Handles 2670'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to 2671declare it. Do not call multiple C<TARG>-oriented macros to return lists 2672from XSUB's - see C<mXPUSHn> instead. See also C<PUSHn> and C<mPUSHn>. 2673 2674 void XPUSHn(NV nv) 2675 2676=for hackers 2677Found in file pp.h 2678 2679=item XPUSHp 2680X<XPUSHp> 2681 2682Push a string onto the stack, extending the stack if necessary. The C<len> 2683indicates the length of the string. Handles 'set' magic. Uses C<TARG>, so 2684C<dTARGET> or C<dXSTARG> should be called to declare it. Do not call 2685multiple C<TARG>-oriented macros to return lists from XSUB's - see 2686C<mXPUSHp> instead. See also C<PUSHp> and C<mPUSHp>. 2687 2688 void XPUSHp(char* str, STRLEN len) 2689 2690=for hackers 2691Found in file pp.h 2692 2693=item XPUSHs 2694X<XPUSHs> 2695 2696Push an SV onto the stack, extending the stack if necessary. Does not 2697handle 'set' magic. Does not use C<TARG>. See also C<XPUSHmortal>, 2698C<PUSHs> and C<PUSHmortal>. 2699 2700 void XPUSHs(SV* sv) 2701 2702=for hackers 2703Found in file pp.h 2704 2705=item XPUSHu 2706X<XPUSHu> 2707 2708Push an unsigned integer onto the stack, extending the stack if necessary. 2709Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be 2710called to declare it. Do not call multiple C<TARG>-oriented macros to 2711return lists from XSUB's - see C<mXPUSHu> instead. See also C<PUSHu> and 2712C<mPUSHu>. 2713 2714 void XPUSHu(UV uv) 2715 2716=for hackers 2717Found in file pp.h 2718 2719=item XSRETURN 2720X<XSRETURN> 2721 2722Return from XSUB, indicating number of items on the stack. This is usually 2723handled by C<xsubpp>. 2724 2725 void XSRETURN(int nitems) 2726 2727=for hackers 2728Found in file XSUB.h 2729 2730=item XSRETURN_EMPTY 2731X<XSRETURN_EMPTY> 2732 2733Return an empty list from an XSUB immediately. 2734 2735 XSRETURN_EMPTY; 2736 2737=for hackers 2738Found in file XSUB.h 2739 2740=item XSRETURN_IV 2741X<XSRETURN_IV> 2742 2743Return an integer from an XSUB immediately. Uses C<XST_mIV>. 2744 2745 void XSRETURN_IV(IV iv) 2746 2747=for hackers 2748Found in file XSUB.h 2749 2750=item XSRETURN_NO 2751X<XSRETURN_NO> 2752 2753Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>. 2754 2755 XSRETURN_NO; 2756 2757=for hackers 2758Found in file XSUB.h 2759 2760=item XSRETURN_NV 2761X<XSRETURN_NV> 2762 2763Return a double from an XSUB immediately. Uses C<XST_mNV>. 2764 2765 void XSRETURN_NV(NV nv) 2766 2767=for hackers 2768Found in file XSUB.h 2769 2770=item XSRETURN_PV 2771X<XSRETURN_PV> 2772 2773Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>. 2774 2775 void XSRETURN_PV(char* str) 2776 2777=for hackers 2778Found in file XSUB.h 2779 2780=item XSRETURN_UNDEF 2781X<XSRETURN_UNDEF> 2782 2783Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>. 2784 2785 XSRETURN_UNDEF; 2786 2787=for hackers 2788Found in file XSUB.h 2789 2790=item XSRETURN_UV 2791X<XSRETURN_UV> 2792 2793Return an integer from an XSUB immediately. Uses C<XST_mUV>. 2794 2795 void XSRETURN_UV(IV uv) 2796 2797=for hackers 2798Found in file XSUB.h 2799 2800=item XSRETURN_YES 2801X<XSRETURN_YES> 2802 2803Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>. 2804 2805 XSRETURN_YES; 2806 2807=for hackers 2808Found in file XSUB.h 2809 2810=item XST_mIV 2811X<XST_mIV> 2812 2813Place an integer into the specified position C<pos> on the stack. The 2814value is stored in a new mortal SV. 2815 2816 void XST_mIV(int pos, IV iv) 2817 2818=for hackers 2819Found in file XSUB.h 2820 2821=item XST_mNO 2822X<XST_mNO> 2823 2824Place C<&PL_sv_no> into the specified position C<pos> on the 2825stack. 2826 2827 void XST_mNO(int pos) 2828 2829=for hackers 2830Found in file XSUB.h 2831 2832=item XST_mNV 2833X<XST_mNV> 2834 2835Place a double into the specified position C<pos> on the stack. The value 2836is stored in a new mortal SV. 2837 2838 void XST_mNV(int pos, NV nv) 2839 2840=for hackers 2841Found in file XSUB.h 2842 2843=item XST_mPV 2844X<XST_mPV> 2845 2846Place a copy of a string into the specified position C<pos> on the stack. 2847The value is stored in a new mortal SV. 2848 2849 void XST_mPV(int pos, char* str) 2850 2851=for hackers 2852Found in file XSUB.h 2853 2854=item XST_mUNDEF 2855X<XST_mUNDEF> 2856 2857Place C<&PL_sv_undef> into the specified position C<pos> on the 2858stack. 2859 2860 void XST_mUNDEF(int pos) 2861 2862=for hackers 2863Found in file XSUB.h 2864 2865=item XST_mYES 2866X<XST_mYES> 2867 2868Place C<&PL_sv_yes> into the specified position C<pos> on the 2869stack. 2870 2871 void XST_mYES(int pos) 2872 2873=for hackers 2874Found in file XSUB.h 2875 2876 2877=back 2878 2879=head1 SV Flags 2880 2881=over 8 2882 2883=item svtype 2884X<svtype> 2885 2886An enum of flags for Perl types. These are found in the file B<sv.h> 2887in the C<svtype> enum. Test these flags with the C<SvTYPE> macro. 2888 2889=for hackers 2890Found in file sv.h 2891 2892=item SVt_IV 2893X<SVt_IV> 2894 2895Integer type flag for scalars. See C<svtype>. 2896 2897=for hackers 2898Found in file sv.h 2899 2900=item SVt_NV 2901X<SVt_NV> 2902 2903Double type flag for scalars. See C<svtype>. 2904 2905=for hackers 2906Found in file sv.h 2907 2908=item SVt_PV 2909X<SVt_PV> 2910 2911Pointer type flag for scalars. See C<svtype>. 2912 2913=for hackers 2914Found in file sv.h 2915 2916=item SVt_PVAV 2917X<SVt_PVAV> 2918 2919Type flag for arrays. See C<svtype>. 2920 2921=for hackers 2922Found in file sv.h 2923 2924=item SVt_PVCV 2925X<SVt_PVCV> 2926 2927Type flag for code refs. See C<svtype>. 2928 2929=for hackers 2930Found in file sv.h 2931 2932=item SVt_PVHV 2933X<SVt_PVHV> 2934 2935Type flag for hashes. See C<svtype>. 2936 2937=for hackers 2938Found in file sv.h 2939 2940=item SVt_PVMG 2941X<SVt_PVMG> 2942 2943Type flag for blessed scalars. See C<svtype>. 2944 2945=for hackers 2946Found in file sv.h 2947 2948 2949=back 2950 2951=head1 SV Manipulation Functions 2952 2953=over 8 2954 2955=item get_sv 2956X<get_sv> 2957 2958Returns the SV of the specified Perl scalar. If C<create> is set and the 2959Perl variable does not exist then it will be created. If C<create> is not 2960set and the variable does not exist then NULL is returned. 2961 2962NOTE: the perl_ form of this function is deprecated. 2963 2964 SV* get_sv(const char* name, I32 create) 2965 2966=for hackers 2967Found in file perl.c 2968 2969=item looks_like_number 2970X<looks_like_number> 2971 2972Test if the content of an SV looks like a number (or is a number). 2973C<Inf> and C<Infinity> are treated as numbers (so will not issue a 2974non-numeric warning), even if your atof() doesn't grok them. 2975 2976 I32 looks_like_number(SV* sv) 2977 2978=for hackers 2979Found in file sv.c 2980 2981=item newRV_inc 2982X<newRV_inc> 2983 2984Creates an RV wrapper for an SV. The reference count for the original SV is 2985incremented. 2986 2987 SV* newRV_inc(SV* sv) 2988 2989=for hackers 2990Found in file sv.h 2991 2992=item newRV_noinc 2993X<newRV_noinc> 2994 2995Creates an RV wrapper for an SV. The reference count for the original 2996SV is B<not> incremented. 2997 2998 SV* newRV_noinc(SV *sv) 2999 3000=for hackers 3001Found in file sv.c 3002 3003=item NEWSV 3004X<NEWSV> 3005 3006Creates a new SV. A non-zero C<len> parameter indicates the number of 3007bytes of preallocated string space the SV should have. An extra byte for a 3008tailing NUL is also reserved. (SvPOK is not set for the SV even if string 3009space is allocated.) The reference count for the new SV is set to 1. 3010C<id> is an integer id between 0 and 1299 (used to identify leaks). 3011 3012 SV* NEWSV(int id, STRLEN len) 3013 3014=for hackers 3015Found in file handy.h 3016 3017=item newSV 3018X<newSV> 3019 3020Create a new null SV, or if len > 0, create a new empty SVt_PV type SV 3021with an initial PV allocation of len+1. Normally accessed via the C<NEWSV> 3022macro. 3023 3024 SV* newSV(STRLEN len) 3025 3026=for hackers 3027Found in file sv.c 3028 3029=item newSVhek 3030X<newSVhek> 3031 3032Creates a new SV from the hash key structure. It will generate scalars that 3033point to the shared string table where possible. Returns a new (undefined) 3034SV if the hek is NULL. 3035 3036 SV* newSVhek(const HEK *hek) 3037 3038=for hackers 3039Found in file sv.c 3040 3041=item newSViv 3042X<newSViv> 3043 3044Creates a new SV and copies an integer into it. The reference count for the 3045SV is set to 1. 3046 3047 SV* newSViv(IV i) 3048 3049=for hackers 3050Found in file sv.c 3051 3052=item newSVnv 3053X<newSVnv> 3054 3055Creates a new SV and copies a floating point value into it. 3056The reference count for the SV is set to 1. 3057 3058 SV* newSVnv(NV n) 3059 3060=for hackers 3061Found in file sv.c 3062 3063=item newSVpv 3064X<newSVpv> 3065 3066Creates a new SV and copies a string into it. The reference count for the 3067SV is set to 1. If C<len> is zero, Perl will compute the length using 3068strlen(). For efficiency, consider using C<newSVpvn> instead. 3069 3070 SV* newSVpv(const char* s, STRLEN len) 3071 3072=for hackers 3073Found in file sv.c 3074 3075=item newSVpvf 3076X<newSVpvf> 3077 3078Creates a new SV and initializes it with the string formatted like 3079C<sprintf>. 3080 3081 SV* newSVpvf(const char* pat, ...) 3082 3083=for hackers 3084Found in file sv.c 3085 3086=item newSVpvn 3087X<newSVpvn> 3088 3089Creates a new SV and copies a string into it. The reference count for the 3090SV is set to 1. Note that if C<len> is zero, Perl will create a zero length 3091string. You are responsible for ensuring that the source string is at least 3092C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined. 3093 3094 SV* newSVpvn(const char* s, STRLEN len) 3095 3096=for hackers 3097Found in file sv.c 3098 3099=item newSVpvn_share 3100X<newSVpvn_share> 3101 3102Creates a new SV with its SvPVX_const pointing to a shared string in the string 3103table. If the string does not already exist in the table, it is created 3104first. Turns on READONLY and FAKE. The string's hash is stored in the UV 3105slot of the SV; if the C<hash> parameter is non-zero, that value is used; 3106otherwise the hash is computed. The idea here is that as the string table 3107is used for shared hash keys these strings will have SvPVX_const == HeKEY and 3108hash lookup will avoid string compare. 3109 3110 SV* newSVpvn_share(const char* s, I32 len, U32 hash) 3111 3112=for hackers 3113Found in file sv.c 3114 3115=item newSVrv 3116X<newSVrv> 3117 3118Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then 3119it will be upgraded to one. If C<classname> is non-null then the new SV will 3120be blessed in the specified package. The new SV is returned and its 3121reference count is 1. 3122 3123 SV* newSVrv(SV* rv, const char* classname) 3124 3125=for hackers 3126Found in file sv.c 3127 3128=item newSVsv 3129X<newSVsv> 3130 3131Creates a new SV which is an exact duplicate of the original SV. 3132(Uses C<sv_setsv>). 3133 3134 SV* newSVsv(SV* old) 3135 3136=for hackers 3137Found in file sv.c 3138 3139=item newSVuv 3140X<newSVuv> 3141 3142Creates a new SV and copies an unsigned integer into it. 3143The reference count for the SV is set to 1. 3144 3145 SV* newSVuv(UV u) 3146 3147=for hackers 3148Found in file sv.c 3149 3150=item SvCUR 3151X<SvCUR> 3152 3153Returns the length of the string which is in the SV. See C<SvLEN>. 3154 3155 STRLEN SvCUR(SV* sv) 3156 3157=for hackers 3158Found in file sv.h 3159 3160=item SvCUR_set 3161X<SvCUR_set> 3162 3163Set the current length of the string which is in the SV. See C<SvCUR> 3164and C<SvIV_set>. 3165 3166 void SvCUR_set(SV* sv, STRLEN len) 3167 3168=for hackers 3169Found in file sv.h 3170 3171=item SvEND 3172X<SvEND> 3173 3174Returns a pointer to the last character in the string which is in the SV. 3175See C<SvCUR>. Access the character as *(SvEND(sv)). 3176 3177 char* SvEND(SV* sv) 3178 3179=for hackers 3180Found in file sv.h 3181 3182=item SvGROW 3183X<SvGROW> 3184 3185Expands the character buffer in the SV so that it has room for the 3186indicated number of bytes (remember to reserve space for an extra trailing 3187NUL character). Calls C<sv_grow> to perform the expansion if necessary. 3188Returns a pointer to the character buffer. 3189 3190 char * SvGROW(SV* sv, STRLEN len) 3191 3192=for hackers 3193Found in file sv.h 3194 3195=item SvIOK 3196X<SvIOK> 3197 3198Returns a boolean indicating whether the SV contains an integer. 3199 3200 bool SvIOK(SV* sv) 3201 3202=for hackers 3203Found in file sv.h 3204 3205=item SvIOKp 3206X<SvIOKp> 3207 3208Returns a boolean indicating whether the SV contains an integer. Checks 3209the B<private> setting. Use C<SvIOK>. 3210 3211 bool SvIOKp(SV* sv) 3212 3213=for hackers 3214Found in file sv.h 3215 3216=item SvIOK_notUV 3217X<SvIOK_notUV> 3218 3219Returns a boolean indicating whether the SV contains a signed integer. 3220 3221 bool SvIOK_notUV(SV* sv) 3222 3223=for hackers 3224Found in file sv.h 3225 3226=item SvIOK_off 3227X<SvIOK_off> 3228 3229Unsets the IV status of an SV. 3230 3231 void SvIOK_off(SV* sv) 3232 3233=for hackers 3234Found in file sv.h 3235 3236=item SvIOK_on 3237X<SvIOK_on> 3238 3239Tells an SV that it is an integer. 3240 3241 void SvIOK_on(SV* sv) 3242 3243=for hackers 3244Found in file sv.h 3245 3246=item SvIOK_only 3247X<SvIOK_only> 3248 3249Tells an SV that it is an integer and disables all other OK bits. 3250 3251 void SvIOK_only(SV* sv) 3252 3253=for hackers 3254Found in file sv.h 3255 3256=item SvIOK_only_UV 3257X<SvIOK_only_UV> 3258 3259Tells and SV that it is an unsigned integer and disables all other OK bits. 3260 3261 void SvIOK_only_UV(SV* sv) 3262 3263=for hackers 3264Found in file sv.h 3265 3266=item SvIOK_UV 3267X<SvIOK_UV> 3268 3269Returns a boolean indicating whether the SV contains an unsigned integer. 3270 3271 bool SvIOK_UV(SV* sv) 3272 3273=for hackers 3274Found in file sv.h 3275 3276=item SvIsCOW 3277X<SvIsCOW> 3278 3279Returns a boolean indicating whether the SV is Copy-On-Write. (either shared 3280hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for 3281COW) 3282 3283 bool SvIsCOW(SV* sv) 3284 3285=for hackers 3286Found in file sv.h 3287 3288=item SvIsCOW_shared_hash 3289X<SvIsCOW_shared_hash> 3290 3291Returns a boolean indicating whether the SV is Copy-On-Write shared hash key 3292scalar. 3293 3294 bool SvIsCOW_shared_hash(SV* sv) 3295 3296=for hackers 3297Found in file sv.h 3298 3299=item SvIV 3300X<SvIV> 3301 3302Coerces the given SV to an integer and returns it. See C<SvIVx> for a 3303version which guarantees to evaluate sv only once. 3304 3305 IV SvIV(SV* sv) 3306 3307=for hackers 3308Found in file sv.h 3309 3310=item SvIVX 3311X<SvIVX> 3312 3313Returns the raw value in the SV's IV slot, without checks or conversions. 3314Only use when you are sure SvIOK is true. See also C<SvIV()>. 3315 3316 IV SvIVX(SV* sv) 3317 3318=for hackers 3319Found in file sv.h 3320 3321=item SvIVx 3322X<SvIVx> 3323 3324Coerces the given SV to an integer and returns it. Guarantees to evaluate 3325sv only once. Use the more efficient C<SvIV> otherwise. 3326 3327 IV SvIVx(SV* sv) 3328 3329=for hackers 3330Found in file sv.h 3331 3332=item SvIV_set 3333X<SvIV_set> 3334 3335Set the value of the IV pointer in sv to val. It is possible to perform 3336the same function of this macro with an lvalue assignment to C<SvIVX>. 3337With future Perls, however, it will be more efficient to use 3338C<SvIV_set> instead of the lvalue assignment to C<SvIVX>. 3339 3340 void SvIV_set(SV* sv, IV val) 3341 3342=for hackers 3343Found in file sv.h 3344 3345=item SvLEN 3346X<SvLEN> 3347 3348Returns the size of the string buffer in the SV, not including any part 3349attributable to C<SvOOK>. See C<SvCUR>. 3350 3351 STRLEN SvLEN(SV* sv) 3352 3353=for hackers 3354Found in file sv.h 3355 3356=item SvLEN_set 3357X<SvLEN_set> 3358 3359Set the actual length of the string which is in the SV. See C<SvIV_set>. 3360 3361 void SvLEN_set(SV* sv, STRLEN len) 3362 3363=for hackers 3364Found in file sv.h 3365 3366=item SvMAGIC_set 3367X<SvMAGIC_set> 3368 3369Set the value of the MAGIC pointer in sv to val. See C<SvIV_set>. 3370 3371 void SvMAGIC_set(SV* sv, MAGIC* val) 3372 3373=for hackers 3374Found in file sv.h 3375 3376=item SvNIOK 3377X<SvNIOK> 3378 3379Returns a boolean indicating whether the SV contains a number, integer or 3380double. 3381 3382 bool SvNIOK(SV* sv) 3383 3384=for hackers 3385Found in file sv.h 3386 3387=item SvNIOKp 3388X<SvNIOKp> 3389 3390Returns a boolean indicating whether the SV contains a number, integer or 3391double. Checks the B<private> setting. Use C<SvNIOK>. 3392 3393 bool SvNIOKp(SV* sv) 3394 3395=for hackers 3396Found in file sv.h 3397 3398=item SvNIOK_off 3399X<SvNIOK_off> 3400 3401Unsets the NV/IV status of an SV. 3402 3403 void SvNIOK_off(SV* sv) 3404 3405=for hackers 3406Found in file sv.h 3407 3408=item SvNOK 3409X<SvNOK> 3410 3411Returns a boolean indicating whether the SV contains a double. 3412 3413 bool SvNOK(SV* sv) 3414 3415=for hackers 3416Found in file sv.h 3417 3418=item SvNOKp 3419X<SvNOKp> 3420 3421Returns a boolean indicating whether the SV contains a double. Checks the 3422B<private> setting. Use C<SvNOK>. 3423 3424 bool SvNOKp(SV* sv) 3425 3426=for hackers 3427Found in file sv.h 3428 3429=item SvNOK_off 3430X<SvNOK_off> 3431 3432Unsets the NV status of an SV. 3433 3434 void SvNOK_off(SV* sv) 3435 3436=for hackers 3437Found in file sv.h 3438 3439=item SvNOK_on 3440X<SvNOK_on> 3441 3442Tells an SV that it is a double. 3443 3444 void SvNOK_on(SV* sv) 3445 3446=for hackers 3447Found in file sv.h 3448 3449=item SvNOK_only 3450X<SvNOK_only> 3451 3452Tells an SV that it is a double and disables all other OK bits. 3453 3454 void SvNOK_only(SV* sv) 3455 3456=for hackers 3457Found in file sv.h 3458 3459=item SvNV 3460X<SvNV> 3461 3462Coerce the given SV to a double and return it. See C<SvNVx> for a version 3463which guarantees to evaluate sv only once. 3464 3465 NV SvNV(SV* sv) 3466 3467=for hackers 3468Found in file sv.h 3469 3470=item SvNVX 3471X<SvNVX> 3472 3473Returns the raw value in the SV's NV slot, without checks or conversions. 3474Only use when you are sure SvNOK is true. See also C<SvNV()>. 3475 3476 NV SvNVX(SV* sv) 3477 3478=for hackers 3479Found in file sv.h 3480 3481=item SvNVx 3482X<SvNVx> 3483 3484Coerces the given SV to a double and returns it. Guarantees to evaluate 3485sv only once. Use the more efficient C<SvNV> otherwise. 3486 3487 NV SvNVx(SV* sv) 3488 3489=for hackers 3490Found in file sv.h 3491 3492=item SvNV_set 3493X<SvNV_set> 3494 3495Set the value of the NV pointer in sv to val. See C<SvIV_set>. 3496 3497 void SvNV_set(SV* sv, NV val) 3498 3499=for hackers 3500Found in file sv.h 3501 3502=item SvOK 3503X<SvOK> 3504 3505Returns a boolean indicating whether the value is an SV. It also tells 3506whether the value is defined or not. 3507 3508 bool SvOK(SV* sv) 3509 3510=for hackers 3511Found in file sv.h 3512 3513=item SvOOK 3514X<SvOOK> 3515 3516Returns a boolean indicating whether the SvIVX is a valid offset value for 3517the SvPVX. This hack is used internally to speed up removal of characters 3518from the beginning of a SvPV. When SvOOK is true, then the start of the 3519allocated string buffer is really (SvPVX - SvIVX). 3520 3521 bool SvOOK(SV* sv) 3522 3523=for hackers 3524Found in file sv.h 3525 3526=item SvPOK 3527X<SvPOK> 3528 3529Returns a boolean indicating whether the SV contains a character 3530string. 3531 3532 bool SvPOK(SV* sv) 3533 3534=for hackers 3535Found in file sv.h 3536 3537=item SvPOKp 3538X<SvPOKp> 3539 3540Returns a boolean indicating whether the SV contains a character string. 3541Checks the B<private> setting. Use C<SvPOK>. 3542 3543 bool SvPOKp(SV* sv) 3544 3545=for hackers 3546Found in file sv.h 3547 3548=item SvPOK_off 3549X<SvPOK_off> 3550 3551Unsets the PV status of an SV. 3552 3553 void SvPOK_off(SV* sv) 3554 3555=for hackers 3556Found in file sv.h 3557 3558=item SvPOK_on 3559X<SvPOK_on> 3560 3561Tells an SV that it is a string. 3562 3563 void SvPOK_on(SV* sv) 3564 3565=for hackers 3566Found in file sv.h 3567 3568=item SvPOK_only 3569X<SvPOK_only> 3570 3571Tells an SV that it is a string and disables all other OK bits. 3572Will also turn off the UTF-8 status. 3573 3574 void SvPOK_only(SV* sv) 3575 3576=for hackers 3577Found in file sv.h 3578 3579=item SvPOK_only_UTF8 3580X<SvPOK_only_UTF8> 3581 3582Tells an SV that it is a string and disables all other OK bits, 3583and leaves the UTF-8 status as it was. 3584 3585 void SvPOK_only_UTF8(SV* sv) 3586 3587=for hackers 3588Found in file sv.h 3589 3590=item SvPV 3591X<SvPV> 3592 3593Returns a pointer to the string in the SV, or a stringified form of 3594the SV if the SV does not contain a string. The SV may cache the 3595stringified version becoming C<SvPOK>. Handles 'get' magic. See also 3596C<SvPVx> for a version which guarantees to evaluate sv only once. 3597 3598 char* SvPV(SV* sv, STRLEN len) 3599 3600=for hackers 3601Found in file sv.h 3602 3603=item SvPVbyte 3604X<SvPVbyte> 3605 3606Like C<SvPV>, but converts sv to byte representation first if necessary. 3607 3608 char* SvPVbyte(SV* sv, STRLEN len) 3609 3610=for hackers 3611Found in file sv.h 3612 3613=item SvPVbytex 3614X<SvPVbytex> 3615 3616Like C<SvPV>, but converts sv to byte representation first if necessary. 3617Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte> 3618otherwise. 3619 3620 char* SvPVbytex(SV* sv, STRLEN len) 3621 3622=for hackers 3623Found in file sv.h 3624 3625=item SvPVbytex_force 3626X<SvPVbytex_force> 3627 3628Like C<SvPV_force>, but converts sv to byte representation first if necessary. 3629Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force> 3630otherwise. 3631 3632 char* SvPVbytex_force(SV* sv, STRLEN len) 3633 3634=for hackers 3635Found in file sv.h 3636 3637=item SvPVbyte_force 3638X<SvPVbyte_force> 3639 3640Like C<SvPV_force>, but converts sv to byte representation first if necessary. 3641 3642 char* SvPVbyte_force(SV* sv, STRLEN len) 3643 3644=for hackers 3645Found in file sv.h 3646 3647=item SvPVbyte_nolen 3648X<SvPVbyte_nolen> 3649 3650Like C<SvPV_nolen>, but converts sv to byte representation first if necessary. 3651 3652 char* SvPVbyte_nolen(SV* sv) 3653 3654=for hackers 3655Found in file sv.h 3656 3657=item SvPVutf8 3658X<SvPVutf8> 3659 3660Like C<SvPV>, but converts sv to utf8 first if necessary. 3661 3662 char* SvPVutf8(SV* sv, STRLEN len) 3663 3664=for hackers 3665Found in file sv.h 3666 3667=item SvPVutf8x 3668X<SvPVutf8x> 3669 3670Like C<SvPV>, but converts sv to utf8 first if necessary. 3671Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8> 3672otherwise. 3673 3674 char* SvPVutf8x(SV* sv, STRLEN len) 3675 3676=for hackers 3677Found in file sv.h 3678 3679=item SvPVutf8x_force 3680X<SvPVutf8x_force> 3681 3682Like C<SvPV_force>, but converts sv to utf8 first if necessary. 3683Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force> 3684otherwise. 3685 3686 char* SvPVutf8x_force(SV* sv, STRLEN len) 3687 3688=for hackers 3689Found in file sv.h 3690 3691=item SvPVutf8_force 3692X<SvPVutf8_force> 3693 3694Like C<SvPV_force>, but converts sv to utf8 first if necessary. 3695 3696 char* SvPVutf8_force(SV* sv, STRLEN len) 3697 3698=for hackers 3699Found in file sv.h 3700 3701=item SvPVutf8_nolen 3702X<SvPVutf8_nolen> 3703 3704Like C<SvPV_nolen>, but converts sv to utf8 first if necessary. 3705 3706 char* SvPVutf8_nolen(SV* sv) 3707 3708=for hackers 3709Found in file sv.h 3710 3711=item SvPVX 3712X<SvPVX> 3713 3714Returns a pointer to the physical string in the SV. The SV must contain a 3715string. 3716 3717 char* SvPVX(SV* sv) 3718 3719=for hackers 3720Found in file sv.h 3721 3722=item SvPVx 3723X<SvPVx> 3724 3725A version of C<SvPV> which guarantees to evaluate sv only once. 3726 3727 char* SvPVx(SV* sv, STRLEN len) 3728 3729=for hackers 3730Found in file sv.h 3731 3732=item SvPV_force 3733X<SvPV_force> 3734 3735Like C<SvPV> but will force the SV into containing just a string 3736(C<SvPOK_only>). You want force if you are going to update the C<SvPVX> 3737directly. 3738 3739 char* SvPV_force(SV* sv, STRLEN len) 3740 3741=for hackers 3742Found in file sv.h 3743 3744=item SvPV_force_nomg 3745X<SvPV_force_nomg> 3746 3747Like C<SvPV> but will force the SV into containing just a string 3748(C<SvPOK_only>). You want force if you are going to update the C<SvPVX> 3749directly. Doesn't process magic. 3750 3751 char* SvPV_force_nomg(SV* sv, STRLEN len) 3752 3753=for hackers 3754Found in file sv.h 3755 3756=item SvPV_nolen 3757X<SvPV_nolen> 3758 3759Returns a pointer to the string in the SV, or a stringified form of 3760the SV if the SV does not contain a string. The SV may cache the 3761stringified form becoming C<SvPOK>. Handles 'get' magic. 3762 3763 char* SvPV_nolen(SV* sv) 3764 3765=for hackers 3766Found in file sv.h 3767 3768=item SvPV_set 3769X<SvPV_set> 3770 3771Set the value of the PV pointer in sv to val. See C<SvIV_set>. 3772 3773 void SvPV_set(SV* sv, char* val) 3774 3775=for hackers 3776Found in file sv.h 3777 3778=item SvREFCNT 3779X<SvREFCNT> 3780 3781Returns the value of the object's reference count. 3782 3783 U32 SvREFCNT(SV* sv) 3784 3785=for hackers 3786Found in file sv.h 3787 3788=item SvREFCNT_dec 3789X<SvREFCNT_dec> 3790 3791Decrements the reference count of the given SV. 3792 3793 void SvREFCNT_dec(SV* sv) 3794 3795=for hackers 3796Found in file sv.h 3797 3798=item SvREFCNT_inc 3799X<SvREFCNT_inc> 3800 3801Increments the reference count of the given SV. 3802 3803 SV* SvREFCNT_inc(SV* sv) 3804 3805=for hackers 3806Found in file sv.h 3807 3808=item SvROK 3809X<SvROK> 3810 3811Tests if the SV is an RV. 3812 3813 bool SvROK(SV* sv) 3814 3815=for hackers 3816Found in file sv.h 3817 3818=item SvROK_off 3819X<SvROK_off> 3820 3821Unsets the RV status of an SV. 3822 3823 void SvROK_off(SV* sv) 3824 3825=for hackers 3826Found in file sv.h 3827 3828=item SvROK_on 3829X<SvROK_on> 3830 3831Tells an SV that it is an RV. 3832 3833 void SvROK_on(SV* sv) 3834 3835=for hackers 3836Found in file sv.h 3837 3838=item SvRV 3839X<SvRV> 3840 3841Dereferences an RV to return the SV. 3842 3843 SV* SvRV(SV* sv) 3844 3845=for hackers 3846Found in file sv.h 3847 3848=item SvRV_set 3849X<SvRV_set> 3850 3851Set the value of the RV pointer in sv to val. See C<SvIV_set>. 3852 3853 void SvRV_set(SV* sv, SV* val) 3854 3855=for hackers 3856Found in file sv.h 3857 3858=item SvSTASH 3859X<SvSTASH> 3860 3861Returns the stash of the SV. 3862 3863 HV* SvSTASH(SV* sv) 3864 3865=for hackers 3866Found in file sv.h 3867 3868=item SvSTASH_set 3869X<SvSTASH_set> 3870 3871Set the value of the STASH pointer in sv to val. See C<SvIV_set>. 3872 3873 void SvSTASH_set(SV* sv, STASH* val) 3874 3875=for hackers 3876Found in file sv.h 3877 3878=item SvTAINT 3879X<SvTAINT> 3880 3881Taints an SV if tainting is enabled. 3882 3883 void SvTAINT(SV* sv) 3884 3885=for hackers 3886Found in file sv.h 3887 3888=item SvTAINTED 3889X<SvTAINTED> 3890 3891Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if 3892not. 3893 3894 bool SvTAINTED(SV* sv) 3895 3896=for hackers 3897Found in file sv.h 3898 3899=item SvTAINTED_off 3900X<SvTAINTED_off> 3901 3902Untaints an SV. Be I<very> careful with this routine, as it short-circuits 3903some of Perl's fundamental security features. XS module authors should not 3904use this function unless they fully understand all the implications of 3905unconditionally untainting the value. Untainting should be done in the 3906standard perl fashion, via a carefully crafted regexp, rather than directly 3907untainting variables. 3908 3909 void SvTAINTED_off(SV* sv) 3910 3911=for hackers 3912Found in file sv.h 3913 3914=item SvTAINTED_on 3915X<SvTAINTED_on> 3916 3917Marks an SV as tainted if tainting is enabled. 3918 3919 void SvTAINTED_on(SV* sv) 3920 3921=for hackers 3922Found in file sv.h 3923 3924=item SvTRUE 3925X<SvTRUE> 3926 3927Returns a boolean indicating whether Perl would evaluate the SV as true or 3928false, defined or undefined. Does not handle 'get' magic. 3929 3930 bool SvTRUE(SV* sv) 3931 3932=for hackers 3933Found in file sv.h 3934 3935=item SvTYPE 3936X<SvTYPE> 3937 3938Returns the type of the SV. See C<svtype>. 3939 3940 svtype SvTYPE(SV* sv) 3941 3942=for hackers 3943Found in file sv.h 3944 3945=item SvUOK 3946X<SvUOK> 3947 3948Returns a boolean indicating whether the SV contains an unsigned integer. 3949 3950 void SvUOK(SV* sv) 3951 3952=for hackers 3953Found in file sv.h 3954 3955=item SvUPGRADE 3956X<SvUPGRADE> 3957 3958Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to 3959perform the upgrade if necessary. See C<svtype>. 3960 3961 void SvUPGRADE(SV* sv, svtype type) 3962 3963=for hackers 3964Found in file sv.h 3965 3966=item SvUTF8 3967X<SvUTF8> 3968 3969Returns a boolean indicating whether the SV contains UTF-8 encoded data. 3970 3971 bool SvUTF8(SV* sv) 3972 3973=for hackers 3974Found in file sv.h 3975 3976=item SvUTF8_off 3977X<SvUTF8_off> 3978 3979Unsets the UTF-8 status of an SV. 3980 3981 void SvUTF8_off(SV *sv) 3982 3983=for hackers 3984Found in file sv.h 3985 3986=item SvUTF8_on 3987X<SvUTF8_on> 3988 3989Turn on the UTF-8 status of an SV (the data is not changed, just the flag). 3990Do not use frivolously. 3991 3992 void SvUTF8_on(SV *sv) 3993 3994=for hackers 3995Found in file sv.h 3996 3997=item SvUV 3998X<SvUV> 3999 4000Coerces the given SV to an unsigned integer and returns it. See C<SvUVx> 4001for a version which guarantees to evaluate sv only once. 4002 4003 UV SvUV(SV* sv) 4004 4005=for hackers 4006Found in file sv.h 4007 4008=item SvUVX 4009X<SvUVX> 4010 4011Returns the raw value in the SV's UV slot, without checks or conversions. 4012Only use when you are sure SvIOK is true. See also C<SvUV()>. 4013 4014 UV SvUVX(SV* sv) 4015 4016=for hackers 4017Found in file sv.h 4018 4019=item SvUVx 4020X<SvUVx> 4021 4022Coerces the given SV to an unsigned integer and returns it. Guarantees to 4023evaluate sv only once. Use the more efficient C<SvUV> otherwise. 4024 4025 UV SvUVx(SV* sv) 4026 4027=for hackers 4028Found in file sv.h 4029 4030=item SvUV_set 4031X<SvUV_set> 4032 4033Set the value of the UV pointer in sv to val. See C<SvIV_set>. 4034 4035 void SvUV_set(SV* sv, UV val) 4036 4037=for hackers 4038Found in file sv.h 4039 4040=item sv_2bool 4041X<sv_2bool> 4042 4043This function is only called on magical items, and is only used by 4044sv_true() or its macro equivalent. 4045 4046 bool sv_2bool(SV* sv) 4047 4048=for hackers 4049Found in file sv.c 4050 4051=item sv_2cv 4052X<sv_2cv> 4053 4054Using various gambits, try to get a CV from an SV; in addition, try if 4055possible to set C<*st> and C<*gvp> to the stash and GV associated with it. 4056 4057 CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref) 4058 4059=for hackers 4060Found in file sv.c 4061 4062=item sv_2io 4063X<sv_2io> 4064 4065Using various gambits, try to get an IO from an SV: the IO slot if its a 4066GV; or the recursive result if we're an RV; or the IO slot of the symbol 4067named after the PV if we're a string. 4068 4069 IO* sv_2io(SV* sv) 4070 4071=for hackers 4072Found in file sv.c 4073 4074=item sv_2iv 4075X<sv_2iv> 4076 4077Return the integer value of an SV, doing any necessary string conversion, 4078magic etc. Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros. 4079 4080 IV sv_2iv(SV* sv) 4081 4082=for hackers 4083Found in file sv.c 4084 4085=item sv_2mortal 4086X<sv_2mortal> 4087 4088Marks an existing SV as mortal. The SV will be destroyed "soon", either 4089by an explicit call to FREETMPS, or by an implicit call at places such as 4090statement boundaries. SvTEMP() is turned on which means that the SV's 4091string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal> 4092and C<sv_mortalcopy>. 4093 4094 SV* sv_2mortal(SV* sv) 4095 4096=for hackers 4097Found in file sv.c 4098 4099=item sv_2nv 4100X<sv_2nv> 4101 4102Return the num value of an SV, doing any necessary string or integer 4103conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)> 4104macros. 4105 4106 NV sv_2nv(SV* sv) 4107 4108=for hackers 4109Found in file sv.c 4110 4111=item sv_2pvbyte 4112X<sv_2pvbyte> 4113 4114Return a pointer to the byte-encoded representation of the SV, and set *lp 4115to its length. May cause the SV to be downgraded from UTF-8 as a 4116side-effect. 4117 4118Usually accessed via the C<SvPVbyte> macro. 4119 4120 char* sv_2pvbyte(SV* sv, STRLEN* lp) 4121 4122=for hackers 4123Found in file sv.c 4124 4125=item sv_2pvbyte_nolen 4126X<sv_2pvbyte_nolen> 4127 4128Return a pointer to the byte-encoded representation of the SV. 4129May cause the SV to be downgraded from UTF-8 as a side-effect. 4130 4131Usually accessed via the C<SvPVbyte_nolen> macro. 4132 4133 char* sv_2pvbyte_nolen(SV* sv) 4134 4135=for hackers 4136Found in file sv.c 4137 4138=item sv_2pvutf8 4139X<sv_2pvutf8> 4140 4141Return a pointer to the UTF-8-encoded representation of the SV, and set *lp 4142to its length. May cause the SV to be upgraded to UTF-8 as a side-effect. 4143 4144Usually accessed via the C<SvPVutf8> macro. 4145 4146 char* sv_2pvutf8(SV* sv, STRLEN* lp) 4147 4148=for hackers 4149Found in file sv.c 4150 4151=item sv_2pvutf8_nolen 4152X<sv_2pvutf8_nolen> 4153 4154Return a pointer to the UTF-8-encoded representation of the SV. 4155May cause the SV to be upgraded to UTF-8 as a side-effect. 4156 4157Usually accessed via the C<SvPVutf8_nolen> macro. 4158 4159 char* sv_2pvutf8_nolen(SV* sv) 4160 4161=for hackers 4162Found in file sv.c 4163 4164=item sv_2pv_flags 4165X<sv_2pv_flags> 4166 4167Returns a pointer to the string value of an SV, and sets *lp to its length. 4168If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string 4169if necessary. 4170Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg> 4171usually end up here too. 4172 4173 char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags) 4174 4175=for hackers 4176Found in file sv.c 4177 4178=item sv_2pv_nolen 4179X<sv_2pv_nolen> 4180 4181Like C<sv_2pv()>, but doesn't return the length too. You should usually 4182use the macro wrapper C<SvPV_nolen(sv)> instead. 4183 char* sv_2pv_nolen(SV* sv) 4184 4185=for hackers 4186Found in file sv.c 4187 4188=item sv_2uv 4189X<sv_2uv> 4190 4191Return the unsigned integer value of an SV, doing any necessary string 4192conversion, magic etc. Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> 4193macros. 4194 4195 UV sv_2uv(SV* sv) 4196 4197=for hackers 4198Found in file sv.c 4199 4200=item sv_backoff 4201X<sv_backoff> 4202 4203Remove any string offset. You should normally use the C<SvOOK_off> macro 4204wrapper instead. 4205 4206 int sv_backoff(SV* sv) 4207 4208=for hackers 4209Found in file sv.c 4210 4211=item sv_bless 4212X<sv_bless> 4213 4214Blesses an SV into a specified package. The SV must be an RV. The package 4215must be designated by its stash (see C<gv_stashpv()>). The reference count 4216of the SV is unaffected. 4217 4218 SV* sv_bless(SV* sv, HV* stash) 4219 4220=for hackers 4221Found in file sv.c 4222 4223=item sv_catpv 4224X<sv_catpv> 4225 4226Concatenates the string onto the end of the string which is in the SV. 4227If the SV has the UTF-8 status set, then the bytes appended should be 4228valid UTF-8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>. 4229 4230 void sv_catpv(SV* sv, const char* ptr) 4231 4232=for hackers 4233Found in file sv.c 4234 4235=item sv_catpvf 4236X<sv_catpvf> 4237 4238Processes its arguments like C<sprintf> and appends the formatted 4239output to an SV. If the appended data contains "wide" characters 4240(including, but not limited to, SVs with a UTF-8 PV formatted with %s, 4241and characters >255 formatted with %c), the original SV might get 4242upgraded to UTF-8. Handles 'get' magic, but not 'set' magic. See 4243C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be 4244valid UTF-8; if the original SV was bytes, the pattern should be too. 4245 4246 void sv_catpvf(SV* sv, const char* pat, ...) 4247 4248=for hackers 4249Found in file sv.c 4250 4251=item sv_catpvf_mg 4252X<sv_catpvf_mg> 4253 4254Like C<sv_catpvf>, but also handles 'set' magic. 4255 4256 void sv_catpvf_mg(SV *sv, const char* pat, ...) 4257 4258=for hackers 4259Found in file sv.c 4260 4261=item sv_catpvn 4262X<sv_catpvn> 4263 4264Concatenates the string onto the end of the string which is in the SV. The 4265C<len> indicates number of bytes to copy. If the SV has the UTF-8 4266status set, then the bytes appended should be valid UTF-8. 4267Handles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>. 4268 4269 void sv_catpvn(SV* sv, const char* ptr, STRLEN len) 4270 4271=for hackers 4272Found in file sv.c 4273 4274=item sv_catpvn_flags 4275X<sv_catpvn_flags> 4276 4277Concatenates the string onto the end of the string which is in the SV. The 4278C<len> indicates number of bytes to copy. If the SV has the UTF-8 4279status set, then the bytes appended should be valid UTF-8. 4280If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if 4281appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented 4282in terms of this function. 4283 4284 void sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags) 4285 4286=for hackers 4287Found in file sv.c 4288 4289=item sv_catpvn_mg 4290X<sv_catpvn_mg> 4291 4292Like C<sv_catpvn>, but also handles 'set' magic. 4293 4294 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len) 4295 4296=for hackers 4297Found in file sv.c 4298 4299=item sv_catpvn_nomg 4300X<sv_catpvn_nomg> 4301 4302Like C<sv_catpvn> but doesn't process magic. 4303 4304 void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len) 4305 4306=for hackers 4307Found in file sv.h 4308 4309=item sv_catpv_mg 4310X<sv_catpv_mg> 4311 4312Like C<sv_catpv>, but also handles 'set' magic. 4313 4314 void sv_catpv_mg(SV *sv, const char *ptr) 4315 4316=for hackers 4317Found in file sv.c 4318 4319=item sv_catsv 4320X<sv_catsv> 4321 4322Concatenates the string from SV C<ssv> onto the end of the string in 4323SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but 4324not 'set' magic. See C<sv_catsv_mg>. 4325 4326 void sv_catsv(SV* dsv, SV* ssv) 4327 4328=for hackers 4329Found in file sv.c 4330 4331=item sv_catsv_flags 4332X<sv_catsv_flags> 4333 4334Concatenates the string from SV C<ssv> onto the end of the string in 4335SV C<dsv>. Modifies C<dsv> but not C<ssv>. If C<flags> has C<SV_GMAGIC> 4336bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv> 4337and C<sv_catsv_nomg> are implemented in terms of this function. 4338 4339 void sv_catsv_flags(SV* dsv, SV* ssv, I32 flags) 4340 4341=for hackers 4342Found in file sv.c 4343 4344=item sv_catsv_mg 4345X<sv_catsv_mg> 4346 4347Like C<sv_catsv>, but also handles 'set' magic. 4348 4349 void sv_catsv_mg(SV *dstr, SV *sstr) 4350 4351=for hackers 4352Found in file sv.c 4353 4354=item sv_catsv_nomg 4355X<sv_catsv_nomg> 4356 4357Like C<sv_catsv> but doesn't process magic. 4358 4359 void sv_catsv_nomg(SV* dsv, SV* ssv) 4360 4361=for hackers 4362Found in file sv.h 4363 4364=item sv_chop 4365X<sv_chop> 4366 4367Efficient removal of characters from the beginning of the string buffer. 4368SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside 4369the string buffer. The C<ptr> becomes the first character of the adjusted 4370string. Uses the "OOK hack". 4371Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer 4372refer to the same chunk of data. 4373 4374 void sv_chop(SV* sv, char* ptr) 4375 4376=for hackers 4377Found in file sv.c 4378 4379=item sv_clear 4380X<sv_clear> 4381 4382Clear an SV: call any destructors, free up any memory used by the body, 4383and free the body itself. The SV's head is I<not> freed, although 4384its type is set to all 1's so that it won't inadvertently be assumed 4385to be live during global destruction etc. 4386This function should only be called when REFCNT is zero. Most of the time 4387you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>) 4388instead. 4389 4390 void sv_clear(SV* sv) 4391 4392=for hackers 4393Found in file sv.c 4394 4395=item sv_cmp 4396X<sv_cmp> 4397 4398Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the 4399string in C<sv1> is less than, equal to, or greater than the string in 4400C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will 4401coerce its args to strings if necessary. See also C<sv_cmp_locale>. 4402 4403 I32 sv_cmp(SV* sv1, SV* sv2) 4404 4405=for hackers 4406Found in file sv.c 4407 4408=item sv_cmp_locale 4409X<sv_cmp_locale> 4410 4411Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and 4412'use bytes' aware, handles get magic, and will coerce its args to strings 4413if necessary. See also C<sv_cmp_locale>. See also C<sv_cmp>. 4414 4415 I32 sv_cmp_locale(SV* sv1, SV* sv2) 4416 4417=for hackers 4418Found in file sv.c 4419 4420=item sv_collxfrm 4421X<sv_collxfrm> 4422 4423Add Collate Transform magic to an SV if it doesn't already have it. 4424 4425Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the 4426scalar data of the variable, but transformed to such a format that a normal 4427memory comparison can be used to compare the data according to the locale 4428settings. 4429 4430 char* sv_collxfrm(SV* sv, STRLEN* nxp) 4431 4432=for hackers 4433Found in file sv.c 4434 4435=item sv_copypv 4436X<sv_copypv> 4437 4438Copies a stringified representation of the source SV into the 4439destination SV. Automatically performs any necessary mg_get and 4440coercion of numeric values into strings. Guaranteed to preserve 4441UTF-8 flag even from overloaded objects. Similar in nature to 4442sv_2pv[_flags] but operates directly on an SV instead of just the 4443string. Mostly uses sv_2pv_flags to do its work, except when that 4444would lose the UTF-8'ness of the PV. 4445 4446 void sv_copypv(SV* dsv, SV* ssv) 4447 4448=for hackers 4449Found in file sv.c 4450 4451=item sv_dec 4452X<sv_dec> 4453 4454Auto-decrement of the value in the SV, doing string to numeric conversion 4455if necessary. Handles 'get' magic. 4456 4457 void sv_dec(SV* sv) 4458 4459=for hackers 4460Found in file sv.c 4461 4462=item sv_derived_from 4463X<sv_derived_from> 4464 4465Returns a boolean indicating whether the SV is derived from the specified 4466class. This is the function that implements C<UNIVERSAL::isa>. It works 4467for class names as well as for objects. 4468 4469 bool sv_derived_from(SV* sv, const char* name) 4470 4471=for hackers 4472Found in file universal.c 4473 4474=item sv_eq 4475X<sv_eq> 4476 4477Returns a boolean indicating whether the strings in the two SVs are 4478identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will 4479coerce its args to strings if necessary. 4480 4481 I32 sv_eq(SV* sv1, SV* sv2) 4482 4483=for hackers 4484Found in file sv.c 4485 4486=item sv_force_normal 4487X<sv_force_normal> 4488 4489Undo various types of fakery on an SV: if the PV is a shared string, make 4490a private copy; if we're a ref, stop refing; if we're a glob, downgrade to 4491an xpvmg. See also C<sv_force_normal_flags>. 4492 4493 void sv_force_normal(SV *sv) 4494 4495=for hackers 4496Found in file sv.c 4497 4498=item sv_force_normal_flags 4499X<sv_force_normal_flags> 4500 4501Undo various types of fakery on an SV: if the PV is a shared string, make 4502a private copy; if we're a ref, stop refing; if we're a glob, downgrade to 4503an xpvmg. The C<flags> parameter gets passed to C<sv_unref_flags()> 4504when unrefing. C<sv_force_normal> calls this function with flags set to 0. 4505 4506 void sv_force_normal_flags(SV *sv, U32 flags) 4507 4508=for hackers 4509Found in file sv.c 4510 4511=item sv_free 4512X<sv_free> 4513 4514Decrement an SV's reference count, and if it drops to zero, call 4515C<sv_clear> to invoke destructors and free up any memory used by 4516the body; finally, deallocate the SV's head itself. 4517Normally called via a wrapper macro C<SvREFCNT_dec>. 4518 4519 void sv_free(SV* sv) 4520 4521=for hackers 4522Found in file sv.c 4523 4524=item sv_gets 4525X<sv_gets> 4526 4527Get a line from the filehandle and store it into the SV, optionally 4528appending to the currently-stored string. 4529 4530 char* sv_gets(SV* sv, PerlIO* fp, I32 append) 4531 4532=for hackers 4533Found in file sv.c 4534 4535=item sv_grow 4536X<sv_grow> 4537 4538Expands the character buffer in the SV. If necessary, uses C<sv_unref> and 4539upgrades the SV to C<SVt_PV>. Returns a pointer to the character buffer. 4540Use the C<SvGROW> wrapper instead. 4541 4542 char* sv_grow(SV* sv, STRLEN newlen) 4543 4544=for hackers 4545Found in file sv.c 4546 4547=item sv_inc 4548X<sv_inc> 4549 4550Auto-increment of the value in the SV, doing string to numeric conversion 4551if necessary. Handles 'get' magic. 4552 4553 void sv_inc(SV* sv) 4554 4555=for hackers 4556Found in file sv.c 4557 4558=item sv_insert 4559X<sv_insert> 4560 4561Inserts a string at the specified offset/length within the SV. Similar to 4562the Perl substr() function. 4563 4564 void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen) 4565 4566=for hackers 4567Found in file sv.c 4568 4569=item sv_isa 4570X<sv_isa> 4571 4572Returns a boolean indicating whether the SV is blessed into the specified 4573class. This does not check for subtypes; use C<sv_derived_from> to verify 4574an inheritance relationship. 4575 4576 int sv_isa(SV* sv, const char* name) 4577 4578=for hackers 4579Found in file sv.c 4580 4581=item sv_isobject 4582X<sv_isobject> 4583 4584Returns a boolean indicating whether the SV is an RV pointing to a blessed 4585object. If the SV is not an RV, or if the object is not blessed, then this 4586will return false. 4587 4588 int sv_isobject(SV* sv) 4589 4590=for hackers 4591Found in file sv.c 4592 4593=item sv_iv 4594X<sv_iv> 4595 4596A private implementation of the C<SvIVx> macro for compilers which can't 4597cope with complex macro expressions. Always use the macro instead. 4598 4599 IV sv_iv(SV* sv) 4600 4601=for hackers 4602Found in file sv.c 4603 4604=item sv_len 4605X<sv_len> 4606 4607Returns the length of the string in the SV. Handles magic and type 4608coercion. See also C<SvCUR>, which gives raw access to the xpv_cur slot. 4609 4610 STRLEN sv_len(SV* sv) 4611 4612=for hackers 4613Found in file sv.c 4614 4615=item sv_len_utf8 4616X<sv_len_utf8> 4617 4618Returns the number of characters in the string in an SV, counting wide 4619UTF-8 bytes as a single character. Handles magic and type coercion. 4620 4621 STRLEN sv_len_utf8(SV* sv) 4622 4623=for hackers 4624Found in file sv.c 4625 4626=item sv_magic 4627X<sv_magic> 4628 4629Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary, 4630then adds a new magic item of type C<how> to the head of the magic list. 4631 4632See C<sv_magicext> (which C<sv_magic> now calls) for a description of the 4633handling of the C<name> and C<namlen> arguments. 4634 4635You need to use C<sv_magicext> to add magic to SvREADONLY SVs and also 4636to add more than one instance of the same 'how'. 4637 4638 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) 4639 4640=for hackers 4641Found in file sv.c 4642 4643=item sv_magicext 4644X<sv_magicext> 4645 4646Adds magic to an SV, upgrading it if necessary. Applies the 4647supplied vtable and returns a pointer to the magic added. 4648 4649Note that C<sv_magicext> will allow things that C<sv_magic> will not. 4650In particular, you can add magic to SvREADONLY SVs, and add more than 4651one instance of the same 'how'. 4652 4653If C<namlen> is greater than zero then a C<savepvn> I<copy> of C<name> is 4654stored, if C<namlen> is zero then C<name> is stored as-is and - as another 4655special case - if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed 4656to contain an C<SV*> and is stored as-is with its REFCNT incremented. 4657 4658(This is now used as a subroutine by C<sv_magic>.) 4659 4660 MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen) 4661 4662=for hackers 4663Found in file sv.c 4664 4665=item sv_mortalcopy 4666X<sv_mortalcopy> 4667 4668Creates a new SV which is a copy of the original SV (using C<sv_setsv>). 4669The new SV is marked as mortal. It will be destroyed "soon", either by an 4670explicit call to FREETMPS, or by an implicit call at places such as 4671statement boundaries. See also C<sv_newmortal> and C<sv_2mortal>. 4672 4673 SV* sv_mortalcopy(SV* oldsv) 4674 4675=for hackers 4676Found in file sv.c 4677 4678=item sv_newmortal 4679X<sv_newmortal> 4680 4681Creates a new null SV which is mortal. The reference count of the SV is 4682set to 1. It will be destroyed "soon", either by an explicit call to 4683FREETMPS, or by an implicit call at places such as statement boundaries. 4684See also C<sv_mortalcopy> and C<sv_2mortal>. 4685 4686 SV* sv_newmortal() 4687 4688=for hackers 4689Found in file sv.c 4690 4691=item sv_newref 4692X<sv_newref> 4693 4694Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper 4695instead. 4696 4697 SV* sv_newref(SV* sv) 4698 4699=for hackers 4700Found in file sv.c 4701 4702=item sv_nv 4703X<sv_nv> 4704 4705A private implementation of the C<SvNVx> macro for compilers which can't 4706cope with complex macro expressions. Always use the macro instead. 4707 4708 NV sv_nv(SV* sv) 4709 4710=for hackers 4711Found in file sv.c 4712 4713=item sv_pos_b2u 4714X<sv_pos_b2u> 4715 4716Converts the value pointed to by offsetp from a count of bytes from the 4717start of the string, to a count of the equivalent number of UTF-8 chars. 4718Handles magic and type coercion. 4719 4720 void sv_pos_b2u(SV* sv, I32* offsetp) 4721 4722=for hackers 4723Found in file sv.c 4724 4725=item sv_pos_u2b 4726X<sv_pos_u2b> 4727 4728Converts the value pointed to by offsetp from a count of UTF-8 chars from 4729the start of the string, to a count of the equivalent number of bytes; if 4730lenp is non-zero, it does the same to lenp, but this time starting from 4731the offset, rather than from the start of the string. Handles magic and 4732type coercion. 4733 4734 void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp) 4735 4736=for hackers 4737Found in file sv.c 4738 4739=item sv_pv 4740X<sv_pv> 4741 4742Use the C<SvPV_nolen> macro instead 4743 4744 char* sv_pv(SV *sv) 4745 4746=for hackers 4747Found in file sv.c 4748 4749=item sv_pvbyte 4750X<sv_pvbyte> 4751 4752Use C<SvPVbyte_nolen> instead. 4753 4754 char* sv_pvbyte(SV *sv) 4755 4756=for hackers 4757Found in file sv.c 4758 4759=item sv_pvbyten 4760X<sv_pvbyten> 4761 4762A private implementation of the C<SvPVbyte> macro for compilers 4763which can't cope with complex macro expressions. Always use the macro 4764instead. 4765 4766 char* sv_pvbyten(SV *sv, STRLEN *len) 4767 4768=for hackers 4769Found in file sv.c 4770 4771=item sv_pvbyten_force 4772X<sv_pvbyten_force> 4773 4774A private implementation of the C<SvPVbytex_force> macro for compilers 4775which can't cope with complex macro expressions. Always use the macro 4776instead. 4777 4778 char* sv_pvbyten_force(SV* sv, STRLEN* lp) 4779 4780=for hackers 4781Found in file sv.c 4782 4783=item sv_pvn 4784X<sv_pvn> 4785 4786A private implementation of the C<SvPV> macro for compilers which can't 4787cope with complex macro expressions. Always use the macro instead. 4788 4789 char* sv_pvn(SV *sv, STRLEN *len) 4790 4791=for hackers 4792Found in file sv.c 4793 4794=item sv_pvn_force 4795X<sv_pvn_force> 4796 4797Get a sensible string out of the SV somehow. 4798A private implementation of the C<SvPV_force> macro for compilers which 4799can't cope with complex macro expressions. Always use the macro instead. 4800 4801 char* sv_pvn_force(SV* sv, STRLEN* lp) 4802 4803=for hackers 4804Found in file sv.c 4805 4806=item sv_pvn_force_flags 4807X<sv_pvn_force_flags> 4808 4809Get a sensible string out of the SV somehow. 4810If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if 4811appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are 4812implemented in terms of this function. 4813You normally want to use the various wrapper macros instead: see 4814C<SvPV_force> and C<SvPV_force_nomg> 4815 4816 char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags) 4817 4818=for hackers 4819Found in file sv.c 4820 4821=item sv_pvutf8 4822X<sv_pvutf8> 4823 4824Use the C<SvPVutf8_nolen> macro instead 4825 4826 char* sv_pvutf8(SV *sv) 4827 4828=for hackers 4829Found in file sv.c 4830 4831=item sv_pvutf8n 4832X<sv_pvutf8n> 4833 4834A private implementation of the C<SvPVutf8> macro for compilers 4835which can't cope with complex macro expressions. Always use the macro 4836instead. 4837 4838 char* sv_pvutf8n(SV *sv, STRLEN *len) 4839 4840=for hackers 4841Found in file sv.c 4842 4843=item sv_pvutf8n_force 4844X<sv_pvutf8n_force> 4845 4846A private implementation of the C<SvPVutf8_force> macro for compilers 4847which can't cope with complex macro expressions. Always use the macro 4848instead. 4849 4850 char* sv_pvutf8n_force(SV* sv, STRLEN* lp) 4851 4852=for hackers 4853Found in file sv.c 4854 4855=item sv_reftype 4856X<sv_reftype> 4857 4858Returns a string describing what the SV is a reference to. 4859 4860 char* sv_reftype(SV* sv, int ob) 4861 4862=for hackers 4863Found in file sv.c 4864 4865=item sv_replace 4866X<sv_replace> 4867 4868Make the first argument a copy of the second, then delete the original. 4869The target SV physically takes over ownership of the body of the source SV 4870and inherits its flags; however, the target keeps any magic it owns, 4871and any magic in the source is discarded. 4872Note that this is a rather specialist SV copying operation; most of the 4873time you'll want to use C<sv_setsv> or one of its many macro front-ends. 4874 4875 void sv_replace(SV* sv, SV* nsv) 4876 4877=for hackers 4878Found in file sv.c 4879 4880=item sv_report_used 4881X<sv_report_used> 4882 4883Dump the contents of all SVs not yet freed. (Debugging aid). 4884 4885 void sv_report_used() 4886 4887=for hackers 4888Found in file sv.c 4889 4890=item sv_reset 4891X<sv_reset> 4892 4893Underlying implementation for the C<reset> Perl function. 4894Note that the perl-level function is vaguely deprecated. 4895 4896 void sv_reset(char* s, HV* stash) 4897 4898=for hackers 4899Found in file sv.c 4900 4901=item sv_rvweaken 4902X<sv_rvweaken> 4903 4904Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the 4905referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and 4906push a back-reference to this RV onto the array of backreferences 4907associated with that magic. 4908 4909 SV* sv_rvweaken(SV *sv) 4910 4911=for hackers 4912Found in file sv.c 4913 4914=item sv_setiv 4915X<sv_setiv> 4916 4917Copies an integer into the given SV, upgrading first if necessary. 4918Does not handle 'set' magic. See also C<sv_setiv_mg>. 4919 4920 void sv_setiv(SV* sv, IV num) 4921 4922=for hackers 4923Found in file sv.c 4924 4925=item sv_setiv_mg 4926X<sv_setiv_mg> 4927 4928Like C<sv_setiv>, but also handles 'set' magic. 4929 4930 void sv_setiv_mg(SV *sv, IV i) 4931 4932=for hackers 4933Found in file sv.c 4934 4935=item sv_setnv 4936X<sv_setnv> 4937 4938Copies a double into the given SV, upgrading first if necessary. 4939Does not handle 'set' magic. See also C<sv_setnv_mg>. 4940 4941 void sv_setnv(SV* sv, NV num) 4942 4943=for hackers 4944Found in file sv.c 4945 4946=item sv_setnv_mg 4947X<sv_setnv_mg> 4948 4949Like C<sv_setnv>, but also handles 'set' magic. 4950 4951 void sv_setnv_mg(SV *sv, NV num) 4952 4953=for hackers 4954Found in file sv.c 4955 4956=item sv_setpv 4957X<sv_setpv> 4958 4959Copies a string into an SV. The string must be null-terminated. Does not 4960handle 'set' magic. See C<sv_setpv_mg>. 4961 4962 void sv_setpv(SV* sv, const char* ptr) 4963 4964=for hackers 4965Found in file sv.c 4966 4967=item sv_setpvf 4968X<sv_setpvf> 4969 4970Works like C<sv_catpvf> but copies the text into the SV instead of 4971appending it. Does not handle 'set' magic. See C<sv_setpvf_mg>. 4972 4973 void sv_setpvf(SV* sv, const char* pat, ...) 4974 4975=for hackers 4976Found in file sv.c 4977 4978=item sv_setpvf_mg 4979X<sv_setpvf_mg> 4980 4981Like C<sv_setpvf>, but also handles 'set' magic. 4982 4983 void sv_setpvf_mg(SV *sv, const char* pat, ...) 4984 4985=for hackers 4986Found in file sv.c 4987 4988=item sv_setpviv 4989X<sv_setpviv> 4990 4991Copies an integer into the given SV, also updating its string value. 4992Does not handle 'set' magic. See C<sv_setpviv_mg>. 4993 4994 void sv_setpviv(SV* sv, IV num) 4995 4996=for hackers 4997Found in file sv.c 4998 4999=item sv_setpviv_mg 5000X<sv_setpviv_mg> 5001 5002Like C<sv_setpviv>, but also handles 'set' magic. 5003 5004 void sv_setpviv_mg(SV *sv, IV iv) 5005 5006=for hackers 5007Found in file sv.c 5008 5009=item sv_setpvn 5010X<sv_setpvn> 5011 5012Copies a string into an SV. The C<len> parameter indicates the number of 5013bytes to be copied. If the C<ptr> argument is NULL the SV will become 5014undefined. Does not handle 'set' magic. See C<sv_setpvn_mg>. 5015 5016 void sv_setpvn(SV* sv, const char* ptr, STRLEN len) 5017 5018=for hackers 5019Found in file sv.c 5020 5021=item sv_setpvn_mg 5022X<sv_setpvn_mg> 5023 5024Like C<sv_setpvn>, but also handles 'set' magic. 5025 5026 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len) 5027 5028=for hackers 5029Found in file sv.c 5030 5031=item sv_setpv_mg 5032X<sv_setpv_mg> 5033 5034Like C<sv_setpv>, but also handles 'set' magic. 5035 5036 void sv_setpv_mg(SV *sv, const char *ptr) 5037 5038=for hackers 5039Found in file sv.c 5040 5041=item sv_setref_iv 5042X<sv_setref_iv> 5043 5044Copies an integer into a new SV, optionally blessing the SV. The C<rv> 5045argument will be upgraded to an RV. That RV will be modified to point to 5046the new SV. The C<classname> argument indicates the package for the 5047blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV 5048will have a reference count of 1, and the RV will be returned. 5049 5050 SV* sv_setref_iv(SV* rv, const char* classname, IV iv) 5051 5052=for hackers 5053Found in file sv.c 5054 5055=item sv_setref_nv 5056X<sv_setref_nv> 5057 5058Copies a double into a new SV, optionally blessing the SV. The C<rv> 5059argument will be upgraded to an RV. That RV will be modified to point to 5060the new SV. The C<classname> argument indicates the package for the 5061blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV 5062will have a reference count of 1, and the RV will be returned. 5063 5064 SV* sv_setref_nv(SV* rv, const char* classname, NV nv) 5065 5066=for hackers 5067Found in file sv.c 5068 5069=item sv_setref_pv 5070X<sv_setref_pv> 5071 5072Copies a pointer into a new SV, optionally blessing the SV. The C<rv> 5073argument will be upgraded to an RV. That RV will be modified to point to 5074the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed 5075into the SV. The C<classname> argument indicates the package for the 5076blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV 5077will have a reference count of 1, and the RV will be returned. 5078 5079Do not use with other Perl types such as HV, AV, SV, CV, because those 5080objects will become corrupted by the pointer copy process. 5081 5082Note that C<sv_setref_pvn> copies the string while this copies the pointer. 5083 5084 SV* sv_setref_pv(SV* rv, const char* classname, void* pv) 5085 5086=for hackers 5087Found in file sv.c 5088 5089=item sv_setref_pvn 5090X<sv_setref_pvn> 5091 5092Copies a string into a new SV, optionally blessing the SV. The length of the 5093string must be specified with C<n>. The C<rv> argument will be upgraded to 5094an RV. That RV will be modified to point to the new SV. The C<classname> 5095argument indicates the package for the blessing. Set C<classname> to 5096C<Nullch> to avoid the blessing. The new SV will have a reference count 5097of 1, and the RV will be returned. 5098 5099Note that C<sv_setref_pv> copies the pointer while this copies the string. 5100 5101 SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n) 5102 5103=for hackers 5104Found in file sv.c 5105 5106=item sv_setref_uv 5107X<sv_setref_uv> 5108 5109Copies an unsigned integer into a new SV, optionally blessing the SV. The C<rv> 5110argument will be upgraded to an RV. That RV will be modified to point to 5111the new SV. The C<classname> argument indicates the package for the 5112blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV 5113will have a reference count of 1, and the RV will be returned. 5114 5115 SV* sv_setref_uv(SV* rv, const char* classname, UV uv) 5116 5117=for hackers 5118Found in file sv.c 5119 5120=item sv_setsv 5121X<sv_setsv> 5122 5123Copies the contents of the source SV C<ssv> into the destination SV 5124C<dsv>. The source SV may be destroyed if it is mortal, so don't use this 5125function if the source SV needs to be reused. Does not handle 'set' magic. 5126Loosely speaking, it performs a copy-by-value, obliterating any previous 5127content of the destination. 5128 5129You probably want to use one of the assortment of wrappers, such as 5130C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and 5131C<SvSetMagicSV_nosteal>. 5132 5133 void sv_setsv(SV* dsv, SV* ssv) 5134 5135=for hackers 5136Found in file sv.c 5137 5138=item sv_setsv_flags 5139X<sv_setsv_flags> 5140 5141Copies the contents of the source SV C<ssv> into the destination SV 5142C<dsv>. The source SV may be destroyed if it is mortal, so don't use this 5143function if the source SV needs to be reused. Does not handle 'set' magic. 5144Loosely speaking, it performs a copy-by-value, obliterating any previous 5145content of the destination. 5146If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on 5147C<ssv> if appropriate, else not. If the C<flags> parameter has the 5148C<NOSTEAL> bit set then the buffers of temps will not be stolen. <sv_setsv> 5149and C<sv_setsv_nomg> are implemented in terms of this function. 5150 5151You probably want to use one of the assortment of wrappers, such as 5152C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and 5153C<SvSetMagicSV_nosteal>. 5154 5155This is the primary function for copying scalars, and most other 5156copy-ish functions and macros use this underneath. 5157 5158 void sv_setsv_flags(SV* dsv, SV* ssv, I32 flags) 5159 5160=for hackers 5161Found in file sv.c 5162 5163=item sv_setsv_mg 5164X<sv_setsv_mg> 5165 5166Like C<sv_setsv>, but also handles 'set' magic. 5167 5168 void sv_setsv_mg(SV *dstr, SV *sstr) 5169 5170=for hackers 5171Found in file sv.c 5172 5173=item sv_setsv_nomg 5174X<sv_setsv_nomg> 5175 5176Like C<sv_setsv> but doesn't process magic. 5177 5178 void sv_setsv_nomg(SV* dsv, SV* ssv) 5179 5180=for hackers 5181Found in file sv.h 5182 5183=item sv_setuv 5184X<sv_setuv> 5185 5186Copies an unsigned integer into the given SV, upgrading first if necessary. 5187Does not handle 'set' magic. See also C<sv_setuv_mg>. 5188 5189 void sv_setuv(SV* sv, UV num) 5190 5191=for hackers 5192Found in file sv.c 5193 5194=item sv_setuv_mg 5195X<sv_setuv_mg> 5196 5197Like C<sv_setuv>, but also handles 'set' magic. 5198 5199 void sv_setuv_mg(SV *sv, UV u) 5200 5201=for hackers 5202Found in file sv.c 5203 5204=item sv_taint 5205X<sv_taint> 5206 5207Taint an SV. Use C<SvTAINTED_on> instead. 5208 void sv_taint(SV* sv) 5209 5210=for hackers 5211Found in file sv.c 5212 5213=item sv_tainted 5214X<sv_tainted> 5215 5216Test an SV for taintedness. Use C<SvTAINTED> instead. 5217 bool sv_tainted(SV* sv) 5218 5219=for hackers 5220Found in file sv.c 5221 5222=item sv_true 5223X<sv_true> 5224 5225Returns true if the SV has a true value by Perl's rules. 5226Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may 5227instead use an in-line version. 5228 5229 I32 sv_true(SV *sv) 5230 5231=for hackers 5232Found in file sv.c 5233 5234=item sv_unmagic 5235X<sv_unmagic> 5236 5237Removes all magic of type C<type> from an SV. 5238 5239 int sv_unmagic(SV* sv, int type) 5240 5241=for hackers 5242Found in file sv.c 5243 5244=item sv_unref 5245X<sv_unref> 5246 5247Unsets the RV status of the SV, and decrements the reference count of 5248whatever was being referenced by the RV. This can almost be thought of 5249as a reversal of C<newSVrv>. This is C<sv_unref_flags> with the C<flag> 5250being zero. See C<SvROK_off>. 5251 5252 void sv_unref(SV* sv) 5253 5254=for hackers 5255Found in file sv.c 5256 5257=item sv_unref_flags 5258X<sv_unref_flags> 5259 5260Unsets the RV status of the SV, and decrements the reference count of 5261whatever was being referenced by the RV. This can almost be thought of 5262as a reversal of C<newSVrv>. The C<cflags> argument can contain 5263C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented 5264(otherwise the decrementing is conditional on the reference count being 5265different from one or the reference being a readonly SV). 5266See C<SvROK_off>. 5267 5268 void sv_unref_flags(SV* sv, U32 flags) 5269 5270=for hackers 5271Found in file sv.c 5272 5273=item sv_untaint 5274X<sv_untaint> 5275 5276Untaint an SV. Use C<SvTAINTED_off> instead. 5277 void sv_untaint(SV* sv) 5278 5279=for hackers 5280Found in file sv.c 5281 5282=item sv_upgrade 5283X<sv_upgrade> 5284 5285Upgrade an SV to a more complex form. Generally adds a new body type to the 5286SV, then copies across as much information as possible from the old body. 5287You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>. 5288 5289 bool sv_upgrade(SV* sv, U32 mt) 5290 5291=for hackers 5292Found in file sv.c 5293 5294=item sv_usepvn 5295X<sv_usepvn> 5296 5297Tells an SV to use C<ptr> to find its string value. Normally the string is 5298stored inside the SV but sv_usepvn allows the SV to use an outside string. 5299The C<ptr> should point to memory that was allocated by C<malloc>. The 5300string length, C<len>, must be supplied. This function will realloc the 5301memory pointed to by C<ptr>, so that pointer should not be freed or used by 5302the programmer after giving it to sv_usepvn. Does not handle 'set' magic. 5303See C<sv_usepvn_mg>. 5304 5305 void sv_usepvn(SV* sv, char* ptr, STRLEN len) 5306 5307=for hackers 5308Found in file sv.c 5309 5310=item sv_usepvn_mg 5311X<sv_usepvn_mg> 5312 5313Like C<sv_usepvn>, but also handles 'set' magic. 5314 5315 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) 5316 5317=for hackers 5318Found in file sv.c 5319 5320=item sv_utf8_decode 5321X<sv_utf8_decode> 5322 5323If the PV of the SV is an octet sequence in UTF-8 5324and contains a multiple-byte character, the C<SvUTF8> flag is turned on 5325so that it looks like a character. If the PV contains only single-byte 5326characters, the C<SvUTF8> flag stays being off. 5327Scans PV for validity and returns false if the PV is invalid UTF-8. 5328 5329NOTE: this function is experimental and may change or be 5330removed without notice. 5331 5332 bool sv_utf8_decode(SV *sv) 5333 5334=for hackers 5335Found in file sv.c 5336 5337=item sv_utf8_downgrade 5338X<sv_utf8_downgrade> 5339 5340Attempts to convert the PV of an SV from characters to bytes. 5341If the PV contains a character beyond byte, this conversion will fail; 5342in this case, either returns false or, if C<fail_ok> is not 5343true, croaks. 5344 5345This is not as a general purpose Unicode to byte encoding interface: 5346use the Encode extension for that. 5347 5348NOTE: this function is experimental and may change or be 5349removed without notice. 5350 5351 bool sv_utf8_downgrade(SV *sv, bool fail_ok) 5352 5353=for hackers 5354Found in file sv.c 5355 5356=item sv_utf8_encode 5357X<sv_utf8_encode> 5358 5359Converts the PV of an SV to UTF-8, but then turns the C<SvUTF8> 5360flag off so that it looks like octets again. 5361 5362 void sv_utf8_encode(SV *sv) 5363 5364=for hackers 5365Found in file sv.c 5366 5367=item sv_utf8_upgrade 5368X<sv_utf8_upgrade> 5369 5370Converts the PV of an SV to its UTF-8-encoded form. 5371Forces the SV to string form if it is not already. 5372Always sets the SvUTF8 flag to avoid future validity checks even 5373if all the bytes have hibit clear. 5374 5375This is not as a general purpose byte encoding to Unicode interface: 5376use the Encode extension for that. 5377 5378 STRLEN sv_utf8_upgrade(SV *sv) 5379 5380=for hackers 5381Found in file sv.c 5382 5383=item sv_utf8_upgrade_flags 5384X<sv_utf8_upgrade_flags> 5385 5386Converts the PV of an SV to its UTF-8-encoded form. 5387Forces the SV to string form if it is not already. 5388Always sets the SvUTF8 flag to avoid future validity checks even 5389if all the bytes have hibit clear. If C<flags> has C<SV_GMAGIC> bit set, 5390will C<mg_get> on C<sv> if appropriate, else not. C<sv_utf8_upgrade> and 5391C<sv_utf8_upgrade_nomg> are implemented in terms of this function. 5392 5393This is not as a general purpose byte encoding to Unicode interface: 5394use the Encode extension for that. 5395 5396 STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags) 5397 5398=for hackers 5399Found in file sv.c 5400 5401=item sv_uv 5402X<sv_uv> 5403 5404A private implementation of the C<SvUVx> macro for compilers which can't 5405cope with complex macro expressions. Always use the macro instead. 5406 5407 UV sv_uv(SV* sv) 5408 5409=for hackers 5410Found in file sv.c 5411 5412=item sv_vcatpvf 5413X<sv_vcatpvf> 5414 5415Processes its arguments like C<vsprintf> and appends the formatted output 5416to an SV. Does not handle 'set' magic. See C<sv_vcatpvf_mg>. 5417 5418Usually used via its frontend C<sv_catpvf>. 5419 5420 void sv_vcatpvf(SV* sv, const char* pat, va_list* args) 5421 5422=for hackers 5423Found in file sv.c 5424 5425=item sv_vcatpvfn 5426X<sv_vcatpvfn> 5427 5428Processes its arguments like C<vsprintf> and appends the formatted output 5429to an SV. Uses an array of SVs if the C style variable argument list is 5430missing (NULL). When running with taint checks enabled, indicates via 5431C<maybe_tainted> if results are untrustworthy (often due to the use of 5432locales). 5433 5434XXX Except that it maybe_tainted is never assigned to. 5435 5436Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_mg>. 5437 5438 void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) 5439 5440=for hackers 5441Found in file sv.c 5442 5443=item sv_vcatpvf_mg 5444X<sv_vcatpvf_mg> 5445 5446Like C<sv_vcatpvf>, but also handles 'set' magic. 5447 5448Usually used via its frontend C<sv_catpvf_mg>. 5449 5450 void sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args) 5451 5452=for hackers 5453Found in file sv.c 5454 5455=item sv_vsetpvf 5456X<sv_vsetpvf> 5457 5458Works like C<sv_vcatpvf> but copies the text into the SV instead of 5459appending it. Does not handle 'set' magic. See C<sv_vsetpvf_mg>. 5460 5461Usually used via its frontend C<sv_setpvf>. 5462 5463 void sv_vsetpvf(SV* sv, const char* pat, va_list* args) 5464 5465=for hackers 5466Found in file sv.c 5467 5468=item sv_vsetpvfn 5469X<sv_vsetpvfn> 5470 5471Works like C<sv_vcatpvfn> but copies the text into the SV instead of 5472appending it. 5473 5474Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_mg>. 5475 5476 void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) 5477 5478=for hackers 5479Found in file sv.c 5480 5481=item sv_vsetpvf_mg 5482X<sv_vsetpvf_mg> 5483 5484Like C<sv_vsetpvf>, but also handles 'set' magic. 5485 5486Usually used via its frontend C<sv_setpvf_mg>. 5487 5488 void sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args) 5489 5490=for hackers 5491Found in file sv.c 5492 5493 5494=back 5495 5496=head1 Unicode Support 5497 5498=over 8 5499 5500=item bytes_from_utf8 5501X<bytes_from_utf8> 5502 5503Converts a string C<s> of length C<len> from UTF-8 into byte encoding. 5504Unlike C<utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to 5505the newly-created string, and updates C<len> to contain the new 5506length. Returns the original string if no conversion occurs, C<len> 5507is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to 55080 if C<s> is converted or contains all 7bit characters. 5509 5510NOTE: this function is experimental and may change or be 5511removed without notice. 5512 5513 U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8) 5514 5515=for hackers 5516Found in file utf8.c 5517 5518=item bytes_to_utf8 5519X<bytes_to_utf8> 5520 5521Converts a string C<s> of length C<len> from ASCII into UTF-8 encoding. 5522Returns a pointer to the newly-created string, and sets C<len> to 5523reflect the new length. 5524 5525If you want to convert to UTF-8 from other encodings than ASCII, 5526see sv_recode_to_utf8(). 5527 5528NOTE: this function is experimental and may change or be 5529removed without notice. 5530 5531 U8* bytes_to_utf8(U8 *s, STRLEN *len) 5532 5533=for hackers 5534Found in file utf8.c 5535 5536=item ibcmp_utf8 5537X<ibcmp_utf8> 5538 5539Return true if the strings s1 and s2 differ case-insensitively, false 5540if not (if they are equal case-insensitively). If u1 is true, the 5541string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true, 5542the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2 5543are false, the respective string is assumed to be in native 8-bit 5544encoding. 5545 5546If the pe1 and pe2 are non-NULL, the scanning pointers will be copied 5547in there (they will point at the beginning of the I<next> character). 5548If the pointers behind pe1 or pe2 are non-NULL, they are the end 5549pointers beyond which scanning will not continue under any 5550circumstances. If the byte lengths l1 and l2 are non-zero, s1+l1 and 5551s2+l2 will be used as goal end pointers that will also stop the scan, 5552and which qualify towards defining a successful match: all the scans 5553that define an explicit length must reach their goal pointers for 5554a match to succeed). 5555 5556For case-insensitiveness, the "casefolding" of Unicode is used 5557instead of upper/lowercasing both the characters, see 5558http://www.unicode.org/unicode/reports/tr21/ (Case Mappings). 5559 5560 I32 ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2) 5561 5562=for hackers 5563Found in file utf8.c 5564 5565=item is_utf8_char 5566X<is_utf8_char> 5567 5568Tests if some arbitrary number of bytes begins in a valid UTF-8 5569character. Note that an INVARIANT (i.e. ASCII) character is a valid 5570UTF-8 character. The actual number of bytes in the UTF-8 character 5571will be returned if it is valid, otherwise 0. 5572 5573 STRLEN is_utf8_char(U8 *p) 5574 5575=for hackers 5576Found in file utf8.c 5577 5578=item is_utf8_string 5579X<is_utf8_string> 5580 5581Returns true if first C<len> bytes of the given string form a valid 5582UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does 5583not mean 'a string that contains code points above 0x7F encoded in UTF-8' 5584because a valid ASCII string is a valid UTF-8 string. 5585 5586See also is_utf8_string_loclen() and is_utf8_string_loc(). 5587 5588 bool is_utf8_string(U8 *s, STRLEN len) 5589 5590=for hackers 5591Found in file utf8.c 5592 5593=item is_utf8_string_loc 5594X<is_utf8_string_loc> 5595 5596Like is_utf8_string() but stores the location of the failure (in the 5597case of "utf8ness failure") or the location s+len (in the case of 5598"utf8ness success") in the C<ep>. 5599 5600See also is_utf8_string_loclen() and is_utf8_string(). 5601 5602 bool is_utf8_string_loc(U8 *s, STRLEN len, U8 **p) 5603 5604=for hackers 5605Found in file utf8.c 5606 5607=item is_utf8_string_loclen 5608X<is_utf8_string_loclen> 5609 5610Like is_utf8_string() but stores the location of the failure (in the 5611case of "utf8ness failure") or the location s+len (in the case of 5612"utf8ness success") in the C<ep>, and the number of UTF-8 5613encoded characters in the C<el>. 5614 5615See also is_utf8_string_loc() and is_utf8_string(). 5616 5617 bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el) 5618 5619=for hackers 5620Found in file utf8.c 5621 5622=item pv_uni_display 5623X<pv_uni_display> 5624 5625Build to the scalar dsv a displayable version of the string spv, 5626length len, the displayable version being at most pvlim bytes long 5627(if longer, the rest is truncated and "..." will be appended). 5628 5629The flags argument can have UNI_DISPLAY_ISPRINT set to display 5630isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH 5631to display the \\[nrfta\\] as the backslashed versions (like '\n') 5632(UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\). 5633UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both 5634UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on. 5635 5636The pointer to the PV of the dsv is returned. 5637 5638 char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags) 5639 5640=for hackers 5641Found in file utf8.c 5642 5643=item sv_cat_decode 5644X<sv_cat_decode> 5645 5646The encoding is assumed to be an Encode object, the PV of the ssv is 5647assumed to be octets in that encoding and decoding the input starts 5648from the position which (PV + *offset) pointed to. The dsv will be 5649concatenated the decoded UTF-8 string from ssv. Decoding will terminate 5650when the string tstr appears in decoding output or the input ends on 5651the PV of the ssv. The value which the offset points will be modified 5652to the last input position on the ssv. 5653 5654Returns TRUE if the terminator was found, else returns FALSE. 5655 5656 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen) 5657 5658=for hackers 5659Found in file sv.c 5660 5661=item sv_recode_to_utf8 5662X<sv_recode_to_utf8> 5663 5664The encoding is assumed to be an Encode object, on entry the PV 5665of the sv is assumed to be octets in that encoding, and the sv 5666will be converted into Unicode (and UTF-8). 5667 5668If the sv already is UTF-8 (or if it is not POK), or if the encoding 5669is not a reference, nothing is done to the sv. If the encoding is not 5670an C<Encode::XS> Encoding object, bad things will happen. 5671(See F<lib/encoding.pm> and L<Encode>). 5672 5673The PV of the sv is returned. 5674 5675 char* sv_recode_to_utf8(SV* sv, SV *encoding) 5676 5677=for hackers 5678Found in file sv.c 5679 5680=item sv_uni_display 5681X<sv_uni_display> 5682 5683Build to the scalar dsv a displayable version of the scalar sv, 5684the displayable version being at most pvlim bytes long 5685(if longer, the rest is truncated and "..." will be appended). 5686 5687The flags argument is as in pv_uni_display(). 5688 5689The pointer to the PV of the dsv is returned. 5690 5691 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags) 5692 5693=for hackers 5694Found in file utf8.c 5695 5696=item to_utf8_case 5697X<to_utf8_case> 5698 5699The "p" contains the pointer to the UTF-8 string encoding 5700the character that is being converted. 5701 5702The "ustrp" is a pointer to the character buffer to put the 5703conversion result to. The "lenp" is a pointer to the length 5704of the result. 5705 5706The "swashp" is a pointer to the swash to use. 5707 5708Both the special and normal mappings are stored lib/unicore/To/Foo.pl, 5709and loaded by SWASHGET, using lib/utf8_heavy.pl. The special (usually, 5710but not always, a multicharacter mapping), is tried first. 5711 5712The "special" is a string like "utf8::ToSpecLower", which means the 5713hash %utf8::ToSpecLower. The access to the hash is through 5714Perl_to_utf8_case(). 5715 5716The "normal" is a string like "ToLower" which means the swash 5717%utf8::ToLower. 5718 5719 UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, char *normal, char *special) 5720 5721=for hackers 5722Found in file utf8.c 5723 5724=item to_utf8_fold 5725X<to_utf8_fold> 5726 5727Convert the UTF-8 encoded character at p to its foldcase version and 5728store that in UTF-8 in ustrp and its length in bytes in lenp. Note 5729that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the 5730foldcase version may be longer than the original character (up to 5731three characters). 5732 5733The first character of the foldcased version is returned 5734(but note, as explained above, that there may be more.) 5735 5736 UV to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp) 5737 5738=for hackers 5739Found in file utf8.c 5740 5741=item to_utf8_lower 5742X<to_utf8_lower> 5743 5744Convert the UTF-8 encoded character at p to its lowercase version and 5745store that in UTF-8 in ustrp and its length in bytes in lenp. Note 5746that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the 5747lowercase version may be longer than the original character. 5748 5749The first character of the lowercased version is returned 5750(but note, as explained above, that there may be more.) 5751 5752 UV to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp) 5753 5754=for hackers 5755Found in file utf8.c 5756 5757=item to_utf8_title 5758X<to_utf8_title> 5759 5760Convert the UTF-8 encoded character at p to its titlecase version and 5761store that in UTF-8 in ustrp and its length in bytes in lenp. Note 5762that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the 5763titlecase version may be longer than the original character. 5764 5765The first character of the titlecased version is returned 5766(but note, as explained above, that there may be more.) 5767 5768 UV to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp) 5769 5770=for hackers 5771Found in file utf8.c 5772 5773=item to_utf8_upper 5774X<to_utf8_upper> 5775 5776Convert the UTF-8 encoded character at p to its uppercase version and 5777store that in UTF-8 in ustrp and its length in bytes in lenp. Note 5778that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since 5779the uppercase version may be longer than the original character. 5780 5781The first character of the uppercased version is returned 5782(but note, as explained above, that there may be more.) 5783 5784 UV to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp) 5785 5786=for hackers 5787Found in file utf8.c 5788 5789=item utf8n_to_uvchr 5790X<utf8n_to_uvchr> 5791 5792Returns the native character value of the first character in the string C<s> 5793which is assumed to be in UTF-8 encoding; C<retlen> will be set to the 5794length, in bytes, of that character. 5795 5796Allows length and flags to be passed to low level routine. 5797 5798 UV utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags) 5799 5800=for hackers 5801Found in file utf8.c 5802 5803=item utf8n_to_uvuni 5804X<utf8n_to_uvuni> 5805 5806Bottom level UTF-8 decode routine. 5807Returns the unicode code point value of the first character in the string C<s> 5808which is assumed to be in UTF-8 encoding and no longer than C<curlen>; 5809C<retlen> will be set to the length, in bytes, of that character. 5810 5811If C<s> does not point to a well-formed UTF-8 character, the behaviour 5812is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY, 5813it is assumed that the caller will raise a warning, and this function 5814will silently just set C<retlen> to C<-1> and return zero. If the 5815C<flags> does not contain UTF8_CHECK_ONLY, warnings about 5816malformations will be given, C<retlen> will be set to the expected 5817length of the UTF-8 character in bytes, and zero will be returned. 5818 5819The C<flags> can also contain various flags to allow deviations from 5820the strict UTF-8 encoding (see F<utf8.h>). 5821 5822Most code should use utf8_to_uvchr() rather than call this directly. 5823 5824 UV utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags) 5825 5826=for hackers 5827Found in file utf8.c 5828 5829=item utf8_distance 5830X<utf8_distance> 5831 5832Returns the number of UTF-8 characters between the UTF-8 pointers C<a> 5833and C<b>. 5834 5835WARNING: use only if you *know* that the pointers point inside the 5836same UTF-8 buffer. 5837 5838 IV utf8_distance(U8 *a, U8 *b) 5839 5840=for hackers 5841Found in file utf8.c 5842 5843=item utf8_hop 5844X<utf8_hop> 5845 5846Return the UTF-8 pointer C<s> displaced by C<off> characters, either 5847forward or backward. 5848 5849WARNING: do not use the following unless you *know* C<off> is within 5850the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned 5851on the first byte of character or just after the last byte of a character. 5852 5853 U8* utf8_hop(U8 *s, I32 off) 5854 5855=for hackers 5856Found in file utf8.c 5857 5858=item utf8_length 5859X<utf8_length> 5860 5861Return the length of the UTF-8 char encoded string C<s> in characters. 5862Stops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end 5863up past C<e>, croaks. 5864 5865 STRLEN utf8_length(U8* s, U8 *e) 5866 5867=for hackers 5868Found in file utf8.c 5869 5870=item utf8_to_bytes 5871X<utf8_to_bytes> 5872 5873Converts a string C<s> of length C<len> from UTF-8 into byte encoding. 5874Unlike C<bytes_to_utf8>, this over-writes the original string, and 5875updates len to contain the new length. 5876Returns zero on failure, setting C<len> to -1. 5877 5878NOTE: this function is experimental and may change or be 5879removed without notice. 5880 5881 U8* utf8_to_bytes(U8 *s, STRLEN *len) 5882 5883=for hackers 5884Found in file utf8.c 5885 5886=item utf8_to_uvchr 5887X<utf8_to_uvchr> 5888 5889Returns the native character value of the first character in the string C<s> 5890which is assumed to be in UTF-8 encoding; C<retlen> will be set to the 5891length, in bytes, of that character. 5892 5893If C<s> does not point to a well-formed UTF-8 character, zero is 5894returned and retlen is set, if possible, to -1. 5895 5896 UV utf8_to_uvchr(U8 *s, STRLEN *retlen) 5897 5898=for hackers 5899Found in file utf8.c 5900 5901=item utf8_to_uvuni 5902X<utf8_to_uvuni> 5903 5904Returns the Unicode code point of the first character in the string C<s> 5905which is assumed to be in UTF-8 encoding; C<retlen> will be set to the 5906length, in bytes, of that character. 5907 5908This function should only be used when returned UV is considered 5909an index into the Unicode semantic tables (e.g. swashes). 5910 5911If C<s> does not point to a well-formed UTF-8 character, zero is 5912returned and retlen is set, if possible, to -1. 5913 5914 UV utf8_to_uvuni(U8 *s, STRLEN *retlen) 5915 5916=for hackers 5917Found in file utf8.c 5918 5919=item uvchr_to_utf8 5920X<uvchr_to_utf8> 5921 5922Adds the UTF-8 representation of the Native codepoint C<uv> to the end 5923of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free 5924bytes available. The return value is the pointer to the byte after the 5925end of the new character. In other words, 5926 5927 d = uvchr_to_utf8(d, uv); 5928 5929is the recommended wide native character-aware way of saying 5930 5931 *(d++) = uv; 5932 5933 U8* uvchr_to_utf8(U8 *d, UV uv) 5934 5935=for hackers 5936Found in file utf8.c 5937 5938=item uvuni_to_utf8_flags 5939X<uvuni_to_utf8_flags> 5940 5941Adds the UTF-8 representation of the Unicode codepoint C<uv> to the end 5942of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free 5943bytes available. The return value is the pointer to the byte after the 5944end of the new character. In other words, 5945 5946 d = uvuni_to_utf8_flags(d, uv, flags); 5947 5948or, in most cases, 5949 5950 d = uvuni_to_utf8(d, uv); 5951 5952(which is equivalent to) 5953 5954 d = uvuni_to_utf8_flags(d, uv, 0); 5955 5956is the recommended Unicode-aware way of saying 5957 5958 *(d++) = uv; 5959 5960 U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags) 5961 5962=for hackers 5963Found in file utf8.c 5964 5965 5966=back 5967 5968=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions 5969 5970=over 8 5971 5972=item ax 5973X<ax> 5974 5975Variable which is setup by C<xsubpp> to indicate the stack base offset, 5976used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro 5977must be called prior to setup the C<MARK> variable. 5978 5979 I32 ax 5980 5981=for hackers 5982Found in file XSUB.h 5983 5984=item CLASS 5985X<CLASS> 5986 5987Variable which is setup by C<xsubpp> to indicate the 5988class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>. 5989 5990 char* CLASS 5991 5992=for hackers 5993Found in file XSUB.h 5994 5995=item dAX 5996X<dAX> 5997 5998Sets up the C<ax> variable. 5999This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>. 6000 6001 dAX; 6002 6003=for hackers 6004Found in file XSUB.h 6005 6006=item dAXMARK 6007X<dAXMARK> 6008 6009Sets up the C<ax> variable and stack marker variable C<mark>. 6010This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>. 6011 6012 dAXMARK; 6013 6014=for hackers 6015Found in file XSUB.h 6016 6017=item dITEMS 6018X<dITEMS> 6019 6020Sets up the C<items> variable. 6021This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>. 6022 6023 dITEMS; 6024 6025=for hackers 6026Found in file XSUB.h 6027 6028=item dXSARGS 6029X<dXSARGS> 6030 6031Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. 6032Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>. 6033This is usually handled automatically by C<xsubpp>. 6034 6035 dXSARGS; 6036 6037=for hackers 6038Found in file XSUB.h 6039 6040=item dXSI32 6041X<dXSI32> 6042 6043Sets up the C<ix> variable for an XSUB which has aliases. This is usually 6044handled automatically by C<xsubpp>. 6045 6046 dXSI32; 6047 6048=for hackers 6049Found in file XSUB.h 6050 6051=item items 6052X<items> 6053 6054Variable which is setup by C<xsubpp> to indicate the number of 6055items on the stack. See L<perlxs/"Variable-length Parameter Lists">. 6056 6057 I32 items 6058 6059=for hackers 6060Found in file XSUB.h 6061 6062=item ix 6063X<ix> 6064 6065Variable which is setup by C<xsubpp> to indicate which of an 6066XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">. 6067 6068 I32 ix 6069 6070=for hackers 6071Found in file XSUB.h 6072 6073=item newXSproto 6074X<newXSproto> 6075 6076Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to 6077the subs. 6078 6079=for hackers 6080Found in file XSUB.h 6081 6082=item RETVAL 6083X<RETVAL> 6084 6085Variable which is setup by C<xsubpp> to hold the return value for an 6086XSUB. This is always the proper type for the XSUB. See 6087L<perlxs/"The RETVAL Variable">. 6088 6089 (whatever) RETVAL 6090 6091=for hackers 6092Found in file XSUB.h 6093 6094=item ST 6095X<ST> 6096 6097Used to access elements on the XSUB's stack. 6098 6099 SV* ST(int ix) 6100 6101=for hackers 6102Found in file XSUB.h 6103 6104=item THIS 6105X<THIS> 6106 6107Variable which is setup by C<xsubpp> to designate the object in a C++ 6108XSUB. This is always the proper type for the C++ object. See C<CLASS> and 6109L<perlxs/"Using XS With C++">. 6110 6111 (whatever) THIS 6112 6113=for hackers 6114Found in file XSUB.h 6115 6116=item XS 6117X<XS> 6118 6119Macro to declare an XSUB and its C parameter list. This is handled by 6120C<xsubpp>. 6121 6122=for hackers 6123Found in file XSUB.h 6124 6125=item XS_VERSION 6126X<XS_VERSION> 6127 6128The version identifier for an XS module. This is usually 6129handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>. 6130 6131=for hackers 6132Found in file XSUB.h 6133 6134=item XS_VERSION_BOOTCHECK 6135X<XS_VERSION_BOOTCHECK> 6136 6137Macro to verify that a PM module's $VERSION variable matches the XS 6138module's C<XS_VERSION> variable. This is usually handled automatically by 6139C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">. 6140 6141 XS_VERSION_BOOTCHECK; 6142 6143=for hackers 6144Found in file XSUB.h 6145 6146 6147=back 6148 6149=head1 Warning and Dieing 6150 6151=over 8 6152 6153=item croak 6154X<croak> 6155 6156This is the XSUB-writer's interface to Perl's C<die> function. 6157Normally call this function the same way you call the C C<printf> 6158function. Calling C<croak> returns control directly to Perl, 6159sidestepping the normal C order of execution. See C<warn>. 6160 6161If you want to throw an exception object, assign the object to 6162C<$@> and then pass C<Nullch> to croak(): 6163 6164 errsv = get_sv("@", TRUE); 6165 sv_setsv(errsv, exception_object); 6166 croak(Nullch); 6167 6168 void croak(const char* pat, ...) 6169 6170=for hackers 6171Found in file util.c 6172 6173=item warn 6174X<warn> 6175 6176This is the XSUB-writer's interface to Perl's C<warn> function. Call this 6177function the same way you call the C C<printf> function. See C<croak>. 6178 6179 void warn(const char* pat, ...) 6180 6181=for hackers 6182Found in file util.c 6183 6184 6185=back 6186 6187=head1 AUTHORS 6188 6189Until May 1997, this document was maintained by Jeff Okamoto 6190<okamoto@corp.hp.com>. It is now maintained as part of Perl itself. 6191 6192With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, 6193Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil 6194Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, 6195Stephen McCamant, and Gurusamy Sarathy. 6196 6197API Listing originally by Dean Roehrich <roehrich@cray.com>. 6198 6199Updated to be autogenerated from comments in the source by Benjamin Stuhl. 6200 6201=head1 SEE ALSO 6202 6203perlguts(1), perlxs(1), perlxstut(1), perlintern(1) 6204 6205