{ "content": [ { "type": "text", "text": "# PERLAPI (man)\n\n## NAME\n\nperlapi - autogenerated documentation for the perl public API\n\n## DESCRIPTION\n\nThis file contains most of the documentation of the perl public API, as generated by\nembed.pl. Specifically, it is a listing of functions, macros, flags, and variables that may\nbe used by extension writers. Besides perlintern and config.h, some items are listed here as\nbeing actually documented in another pod.\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **Callback Functions**\n- **Casting**\n- **Character case changing**\n- **Character classification**\n- **Compiler and Preprocessor information**\n- **Compiler directives**\n- **Compile-time scope hooks**\n- **Concurrency**\n- **Custom Operators**\n- **Debugging**\n- **Display functions**\n- **Embedding, Threads, and Interpreter Cloning**\n- **Errno**\n- **Exception Handling (simple) Macros**\n- **Filesystem configuration values**\n- **Floating point**\n- **General Configuration** (2 subsections)\n- **Global Variables**\n- **Hook manipulation**\n- **Input/Output**\n- **Integer**\n- **Lexer interface**\n- **Locales**\n- **Magic**\n- **Memory Management**\n- **MRO**\n- **Multicall Functions**\n- **Numeric Functions**\n- **Optrees**\n- **Pad Data Structures**\n- **Password and Group access**\n- **Paths to system commands**\n- **Prototype information**\n- **Reports and Formats**\n- **Signals**\n- **Site configuration**\n- **Sockets configuration values**\n- **Source Filters**\n- **Stack Manipulation Macros**\n- **String Handling**\n- **Tainting**\n- **Time**\n- **Typedef names**\n- **Unicode Support**\n- **Utility Functions**\n- **Versioning**\n- **Warning and Dieing**\n- **Undocumented elements**\n- **AUTHORS**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "PERLAPI", "section": "", "mode": "man", "summary": "perlapi - autogenerated documentation for the perl public API", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 445, "subsections": [] }, { "name": "Callback Functions", "lines": 366, "subsections": [] }, { "name": "Casting", "lines": 66, "subsections": [] }, { "name": "Character case changing", "lines": 229, "subsections": [] }, { "name": "Character classification", "lines": 520, "subsections": [] }, { "name": "Compiler and Preprocessor information", "lines": 103, "subsections": [] }, { "name": "Compiler directives", "lines": 151, "subsections": [] }, { "name": "Compile-time scope hooks", "lines": 37, "subsections": [] }, { "name": "Concurrency", "lines": 507, "subsections": [] }, { "name": "Custom Operators", "lines": 133, "subsections": [] }, { "name": "Debugging", "lines": 161, "subsections": [] }, { "name": "Display functions", "lines": 154, "subsections": [] }, { "name": "Embedding, Threads, and Interpreter Cloning", "lines": 576, "subsections": [] }, { "name": "Errno", "lines": 23, "subsections": [] }, { "name": "Exception Handling (simple) Macros", "lines": 33, "subsections": [] }, { "name": "Filesystem configuration values", "lines": 302, "subsections": [] }, { "name": "Floating point", "lines": 402, "subsections": [] }, { "name": "General Configuration", "lines": 221, "subsections": [ { "name": "List of capability \"HAS__foo_\" symbols", "lines": 74 }, { "name": "List of \"#include\" needed symbols", "lines": 22 } ] }, { "name": "Global Variables", "lines": 669, "subsections": [] }, { "name": "Hook manipulation", "lines": 568, "subsections": [] }, { "name": "Input/Output", "lines": 234, "subsections": [] }, { "name": "Integer", "lines": 370, "subsections": [] }, { "name": "Lexer interface", "lines": 599, "subsections": [] }, { "name": "Locales", "lines": 345, "subsections": [] }, { "name": "Magic", "lines": 131, "subsections": [] }, { "name": "Memory Management", "lines": 108, "subsections": [] }, { "name": "MRO", "lines": 85, "subsections": [] }, { "name": "Multicall Functions", "lines": 20, "subsections": [] }, { "name": "Numeric Functions", "lines": 374, "subsections": [] }, { "name": "Optrees", "lines": 1004, "subsections": [] }, { "name": "Pad Data Structures", "lines": 277, "subsections": [] }, { "name": "Password and Group access", "lines": 85, "subsections": [] }, { "name": "Paths to system commands", "lines": 12, "subsections": [] }, { "name": "Prototype information", "lines": 462, "subsections": [] }, { "name": "Reports and Formats", "lines": 52, "subsections": [] }, { "name": "Signals", "lines": 108, "subsections": [] }, { "name": "Site configuration", "lines": 247, "subsections": [] }, { "name": "Sockets configuration values", "lines": 39, "subsections": [] }, { "name": "Source Filters", "lines": 53, "subsections": [] }, { "name": "Stack Manipulation Macros", "lines": 451, "subsections": [] }, { "name": "String Handling", "lines": 3050, "subsections": [] }, { "name": "Tainting", "lines": 28, "subsections": [] }, { "name": "Time", "lines": 260, "subsections": [] }, { "name": "Typedef names", "lines": 133, "subsections": [] }, { "name": "Unicode Support", "lines": 1288, "subsections": [] }, { "name": "Utility Functions", "lines": 121, "subsections": [] }, { "name": "Versioning", "lines": 176, "subsections": [] }, { "name": "Warning and Dieing", "lines": 399, "subsections": [] }, { "name": "Undocumented elements", "lines": 32, "subsections": [] }, { "name": "AUTHORS", "lines": 11, "subsections": [] }, { "name": "SEE ALSO", "lines": 4, "subsections": [] } ], "sections": { "NAME": { "content": "perlapi - autogenerated documentation for the perl public API\n", "subsections": [] }, "DESCRIPTION": { "content": "This file contains most of the documentation of the perl public API, as generated by\nembed.pl. Specifically, it is a listing of functions, macros, flags, and variables that may\nbe used by extension writers. Besides perlintern and config.h, some items are listed here as\nbeing actually documented in another pod.\n\nAt the end is a list of functions which have yet to be documented. Patches welcome! The\ninterfaces of these are subject to change without notice.\n\nSome of the functions documented here are consolidated so that a single entry serves for\nmultiple functions which all do basically the same thing, but have some slight differences.\nFor example, one form might process magic, while another doesn't. The name of each variation\nis listed at the top of the single entry. But if all have the same signature (arguments and\nreturn type) except for their names, only the usage for the base form is shown. If any one\nof the forms has a different signature (such as returning \"const\" or not) every function's\nsignature is explicitly displayed.\n\nAnything not listed here or in the other mentioned pods is not part of the public API, and\nshould not be used by extension writers at all. For these reasons, blindly using functions\nlisted in proto.h is to be avoided when writing extensions.\n\nIn Perl, unlike C, a string of characters may generally contain embedded \"NUL\" characters.\nSometimes in the documentation a Perl string is referred to as a \"buffer\" to distinguish it\nfrom a C string, but sometimes they are both just referred to as strings.\n\nNote that all Perl API global variables must be referenced with the \"PL\" prefix. Again,\nthose not listed here are not to be used by extension writers, and may be changed or removed\nwithout notice; same with macros. Some macros are provided for compatibility with the older,\nunadorned names, but this support may be disabled in a future release.\n\nPerl was originally written to handle US-ASCII only (that is characters whose ordinal numbers\nare in the range 0 - 127). And documentation and comments may still use the term ASCII, when\nsometimes in fact the entire range from 0 - 255 is meant.\n\nThe non-ASCII characters below 256 can have various meanings, depending on various things.\n(See, most notably, perllocale.) But usually the whole range can be referred to as\nISO-8859-1. Often, the term \"Latin-1\" (or \"Latin1\") is used as an equivalent for ISO-8859-1.\nBut some people treat \"Latin1\" as referring just to the characters in the range 128 through\n255, or sometimes from 160 through 255. This documentation uses \"Latin1\" and \"Latin-1\" to\nrefer to all 256 characters.\n\nNote that Perl can be compiled and run under either ASCII or EBCDIC (See perlebcdic). Most\nof the documentation (and even comments in the code) ignore the EBCDIC possibility. For\nalmost all purposes the differences are transparent. As an example, under EBCDIC, instead of\nUTF-8, UTF-EBCDIC is used to encode Unicode strings, and so whenever this documentation\nrefers to \"utf8\" (and variants of that name, including in function names), it also\n(essentially transparently) means \"UTF-EBCDIC\". But the ordinals of characters differ\nbetween ASCII, EBCDIC, and the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy\na different number of bytes than in UTF-8.\n\nThe organization of this document is tentative and subject to change. Suggestions and\npatches welcome perl5-porters@perl.org .\n\nThe sections in this document currently are\n\n\"AV Handling\"\n\"Callback Functions\"\n\"Casting\"\n\"Character case changing\"\n\"Character classification\"\n\"Compiler and Preprocessor information\"\n\"Compiler directives\"\n\"Compile-time scope hooks\"\n\"Concurrency\"\n\"COPs and Hint Hashes\"\n\"Custom Operators\"\n\"CV Handling\"\n\"Debugging\"\n\"Display functions\"\n\"Embedding, Threads, and Interpreter Cloning\"\n\"Errno\"\n\"Exception Handling (simple) Macros\"\n\"Filesystem configuration values\"\n\"Floating point\"\n\"General Configuration\"\n\"Global Variables\"\n\"GV Handling and Stashes\"\n\"Hook manipulation\"\n\"HV Handling\"\n\"Input/Output\"\n\"Integer\"\n\"I/O Formats\"\n\"Lexer interface\"\n\"Locales\"\n\"Magic\"\n\"Memory Management\"\n\"MRO\"\n\"Multicall Functions\"\n\"Numeric Functions\"\n\"Optrees\"\n\"Pack and Unpack\"\n\"Pad Data Structures\"\n\"Password and Group access\"\n\"Paths to system commands\"\n\"Prototype information\"\n\"REGEXP Functions\"\n\"Reports and Formats\"\n\"Signals\"\n\"Site configuration\"\n\"Sockets configuration values\"\n\"Source Filters\"\n\"Stack Manipulation Macros\"\n\"String Handling\"\n\"SV Flags\"\n\"SV Handling\"\n\"Tainting\"\n\"Time\"\n\"Typedef names\"\n\"Unicode Support\"\n\"Utility Functions\"\n\"Versioning\"\n\"Warning and Dieing\"\n\"XS\"\n\"Undocumented elements\"\n\nThe listing below is alphabetical, case insensitive.\n\nAV Handling\n\"AV\"\nDescribed in perlguts.\n\n\"AvALLOC\"\nDescribed in perlguts.\n\nAvALLOC(AV* av)\n\n\"AvARRAY\"\nReturns a pointer to the AV's internal SV* array.\n\nThis is useful for doing pointer arithmetic on the array. If all you need is to look up\nan array element, then prefer \"avfetch\".\n\nSV AvARRAY(AV* av)\n\n\"avclear\"\nFrees all the elements of an array, leaving it empty. The XS equivalent of \"@array =\n()\". See also \"avundef\".\n\nNote that it is possible that the actions of a destructor called directly or indirectly\nby freeing an element of the array could cause the reference count of the array itself to\nbe reduced (e.g. by deleting an entry in the symbol table). So it is a possibility that\nthe AV could have been freed (or even reallocated) on return from the call unless you\nhold a reference to it.\n\nvoid avclear(AV *av)\n\n\"avcount\"\nReturns the number of elements in the array \"av\". This is the true length of the array,\nincluding any undefined elements. It is always the same as \"avtopindex(av) + 1\".\n\nSizet avcount(AV *av)\n\n\"avcreateandpush\"\nPush an SV onto the end of the array, creating the array if necessary. A small internal\nhelper function to remove a commonly duplicated idiom.\n\nNOTE: \"avcreateandpush\" must be explicitly called as \"Perlavcreateandpush\" with an\n\"aTHX\" parameter.\n\nvoid Perlavcreateandpush(pTHX AV const avp,\nSV * const val)\n\n\"avcreateandunshiftone\"\nUnshifts an SV onto the beginning of the array, creating the array if necessary. A small\ninternal helper function to remove a commonly duplicated idiom.\n\nNOTE: \"avcreateandunshiftone\" must be explicitly called as\n\"Perlavcreateandunshiftone\" with an \"aTHX\" parameter.\n\nSV Perlavcreateandunshiftone(pTHX AV const avp,\nSV * const val)\n\n\"avdelete\"\nDeletes the element indexed by \"key\" from the array, makes the element mortal, and\nreturns it. If \"flags\" equals \"GDISCARD\", the element is freed and NULL is returned.\nNULL is also returned if \"key\" is out of range.\n\nPerl equivalent: \"splice(@myarray, $key, 1, undef)\" (with the \"splice\" in void context if\n\"GDISCARD\" is present).\n\nSV * avdelete(AV *av, SSizet key, I32 flags)\n\n\"avexists\"\nReturns true if the element indexed by \"key\" has been initialized.\n\nThis relies on the fact that uninitialized array elements are set to \"NULL\".\n\nPerl equivalent: exists($myarray[$key]).\n\nbool avexists(AV *av, SSizet key)\n\n\"avextend\"\nPre-extend an array so that it is capable of storing values at indexes \"0..key\". Thus\n\"avextend(av,99)\" guarantees that the array can store 100 elements, i.e. that\n\"avstore(av, 0, sv)\" through \"avstore(av, 99, sv)\" on a plain array will work without\nany further memory allocation.\n\nIf the av argument is a tied array then will call the \"EXTEND\" tied array method with an\nargument of \"(key+1)\".\n\nvoid avextend(AV *av, SSizet key)\n\n\"avfetch\"\nReturns the SV at the specified index in the array. The \"key\" is the index. If \"lval\"\nis true, you are guaranteed to get a real SV back (in case it wasn't real before), which\nyou can then modify. Check that the return value is non-NULL before dereferencing it to\na \"SV*\".\n\nSee \"Understanding the Magic of Tied Hashes and Arrays\" in perlguts for more information\non how to use this function on tied arrays.\n\nThe rough perl equivalent is $myarray[$key].\n\nSV avfetch(AV *av, SSizet key, I32 lval)\n\n\"AvFILL\"\nSame as \"avtopindex\" or \"avtindex\".\n\nSSizet AvFILL(AV* av)\n\n\"avfill\"\nSet the highest index in the array to the given number, equivalent to Perl's\n\"$#array = $fill;\".\n\nThe number of elements in the array will be \"fill + 1\" after avfill() returns. If the\narray was previously shorter, then the additional elements appended are set to NULL. If\nthe array was longer, then the excess elements are freed. \"avfill(av, -1)\" is the same\nas avclear(av).\n\nvoid avfill(AV *av, SSizet fill)\n\n\"avlen\"\nSame as \"avtopindex\". Note that, unlike what the name implies, it returns the maximum\nindex in the array. This is unlike \"svlen\", which returns what you would expect.\n\nTo get the true number of elements in the array, instead use \"avcount\".\n\nSSizet avlen(AV *av)\n\n\"avmake\"\nCreates a new AV and populates it with a list (strp, length \"size\") of SVs. A copy is\nmade of each SV, so their refcounts are not changed. The new AV will have a reference\ncount of 1.\n\nPerl equivalent: \"my @newarray = ($scalar1, $scalar2, $scalar3...);\"\n\nAV * avmake(SSizet size, SV strp)\n\n\"avpop\"\nRemoves one SV from the end of the array, reducing its size by one and returning the SV\n(transferring control of one reference count) to the caller. Returns &PLsvundef if the\narray is empty.\n\nPerl equivalent: \"pop(@myarray);\"\n\nSV * avpop(AV *av)\n\n\"avpush\"\nPushes an SV (transferring control of one reference count) onto the end of the array.\nThe array will grow automatically to accommodate the addition.\n\nPerl equivalent: \"push @myarray, $val;\".\n\nvoid avpush(AV *av, SV *val)\n\n\"avpushsimple\"\nThis is a cut-down version of avpush that assumes that the array is very straightforward\n- no magic, not readonly, and AvREAL - and that \"key\" is not less than -1. This function\nMUST NOT be used in situations where any of those assumptions may not hold.\n\nPushes an SV (transferring control of one reference count) onto the end of the array.\nThe array will grow automatically to accommodate the addition.\n\nPerl equivalent: \"push @myarray, $val;\".\n\nvoid avpushsimple(AV *av, SV *val)\n\n\"avshift\"\nRemoves one SV from the start of the array, reducing its size by one and returning the SV\n(transferring control of one reference count) to the caller. Returns &PLsvundef if the\narray is empty.\n\nPerl equivalent: \"shift(@myarray);\"\n\nSV * avshift(AV *av)\n\n\"avstore\"\nStores an SV in an array. The array index is specified as \"key\". The return value will\nbe \"NULL\" if the operation failed or if the value did not need to be actually stored\nwithin the array (as in the case of tied arrays). Otherwise, it can be dereferenced to\nget the \"SV*\" that was stored there (= \"val\")).\n\nNote that the caller is responsible for suitably incrementing the reference count of\n\"val\" before the call, and decrementing it if the function returned \"NULL\".\n\nApproximate Perl equivalent: \"splice(@myarray, $key, 1, $val)\".\n\nSee \"Understanding the Magic of Tied Hashes and Arrays\" in perlguts for more information\non how to use this function on tied arrays.\n\nSV avstore(AV *av, SSizet key, SV *val)\n\n\"avtindex\"\n\"avtopindex\"\nThese behave identically. If the array \"av\" is empty, these return -1; otherwise they\nreturn the maximum value of the indices of all the array elements which are currently\ndefined in \"av\".\n\nThey process 'get' magic.\n\nThe Perl equivalent for these is $#av.\n\nUse \"avcount\" to get the number of elements in an array.\n\nSSizet avtindex(AV *av)\n\n\"avundef\"\nUndefines the array. The XS equivalent of undef(@array).\n\nAs well as freeing all the elements of the array (like avclear()), this also frees the\nmemory used by the av to store its list of scalars.\n\nSee \"avclear\" for a note about the array possibly being invalid on return.\n\nvoid avundef(AV *av)\n\n\"avunshift\"\nUnshift the given number of \"undef\" values onto the beginning of the array. The array\nwill grow automatically to accommodate the addition.\n\nPerl equivalent: \"unshift @myarray, ((undef) x $num);\"\n\nvoid avunshift(AV *av, SSizet num)\n\n\"getav\"\nReturns the AV of the specified Perl global or package array with the given name (so it\nwon't work on lexical variables). \"flags\" are passed to \"gvfetchpv\". If \"GVADD\" is\nset and the Perl variable does not exist then it will be created. If \"flags\" is zero\n(ignoring \"SVfUTF8\") and the variable does not exist then \"NULL\" is returned.\n\nPerl equivalent: \"@{\"$name\"}\".\n\nNOTE: the perlgetav() form is deprecated.\n\nAV * getav(const char *name, I32 flags)\n\n\"newAV\"\n\"newAVallocx\"\n\"newAVallocxz\"\nThese all create a new AV, setting the reference count to 1. If you also know the\ninitial elements of the array with, see \"\"avmake\"\".\n\nAs background, an array consists of three things:\n\n1. A data structure containing information about the array as a whole, such as its size\nand reference count.\n\n2. A C language array of pointers to the individual elements. These are treated as\npointers to SVs, so all must be castable to SV*.\n\n3. The individual elements themselves. These could be, for instance, SVs and/or AVs\nand/or HVs, etc.\n\nAn empty array need only have the first data structure, and all these functions create\nthat. They differ in what else they do, as follows:\n\n\"newAV\" form\nThis does nothing beyond creating the whole-array data structure. The Perl\nequivalent is approximately \"my @array;\"\n\nThis is useful when the minimum size of the array could be zero (perhaps there are\nlikely code paths that will entirely skip using it).\n\nIf the array does get used, the pointers data structure will need to be allocated at\nthat time. This will end up being done by \"avextend\">, either explicitly:\n\navextend(av, len);\n\nor implicitly when the first element is stored:\n\n(void)avstore(av, 0, sv);\n\nUnused array elements are typically initialized by \"avextend\".\n\n\"newAVallocx\" form\nThis effectively does a \"newAV\" followed by also allocating (uninitialized) space for\nthe pointers array. This is used when you know ahead of time the likely minimum size\nof the array. It is more efficient to do this than doing a plain \"newAV\" followed by\nan \"avextend\".\n\nOf course the array can be extended later should it become necessary.\n\n\"size\" must be at least 1.\n\n\"newAVallocxz\" form\nThis is \"newAVallocx\", but initializes each pointer in it to NULL. This gives\nadded safety to guard against them being read before being set.\n\n\"size\" must be at least 1.\n\nThe following examples all result in an array that can fit four elements (indexes 0 ..\n3):\n\nAV *av = newAV();\navextend(av, 3);\n\nAV *av = newAVallocx(4);\n\nAV *av = newAVallocxz(4);\n\nIn contrast, the following examples allocate an array that is only guaranteed to fit one\nelement without extending:\n\nAV *av = newAVallocx(1);\nAV *av = newAVallocxz(1);\n\nAV * newAV ()\nAV * newAVallocx (SSizet size)\nAV * newAVallocxz(SSizet size)\n\n\"newAVav\"\nCreates a new AV and populates it with values copied from an existing AV. The new AV\nwill have a reference count of 1, and will contain newly created SVs copied from the\noriginal SV. The original source will remain unchanged.\n\nPerl equivalent: \"my @newarray = @existingarray;\"\n\nAV * newAVav(AV *oav)\n\n\"newAVhv\"\nCreates a new AV and populates it with keys and values copied from an existing HV. The\nnew AV will have a reference count of 1, and will contain newly created SVs copied from\nthe original HV. The original source will remain unchanged.\n\nPerl equivalent: \"my @newarray = %existinghash;\"\n\nAV * newAVhv(HV *ohv)\n\n\"Nullav\"\n\"DEPRECATED!\" It is planned to remove \"Nullav\" from a future release of Perl. Do not\nuse it for new code; remove it from existing code.\n\nNull AV pointer.\n\n(deprecated - use \"(AV *)NULL\" instead)\n", "subsections": [] }, "Callback Functions": { "content": "\"callargv\"\nPerforms a callback to the specified named and package-scoped Perl subroutine with \"argv\"\n(a \"NULL\"-terminated array of strings) as arguments. See perlcall.\n\nApproximate Perl equivalent: \"&{\"$subname\"}(@$argv)\".\n\nNOTE: the perlcallargv() form is deprecated.\n\nI32 callargv(const char *subname, I32 flags, char argv)\n\n\"callmethod\"\nPerforms a callback to the specified Perl method. The blessed object must be on the\nstack. See perlcall.\n\nNOTE: the perlcallmethod() form is deprecated.\n\nI32 callmethod(const char *methname, I32 flags)\n\n\"callpv\"\nPerforms a callback to the specified Perl sub. See perlcall.\n\nNOTE: the perlcallpv() form is deprecated.\n\nI32 callpv(const char *subname, I32 flags)\n\n\"callsv\"\nPerforms a callback to the Perl sub specified by the SV.\n\nIf neither the \"GMETHOD\" nor \"GMETHODNAMED\" flag is supplied, the SV may be any of a\nCV, a GV, a reference to a CV, a reference to a GV or SvPV(sv) will be used as the name\nof the sub to call.\n\nIf the \"GMETHOD\" flag is supplied, the SV may be a reference to a CV or SvPV(sv) will be\nused as the name of the method to call.\n\nIf the \"GMETHODNAMED\" flag is supplied, SvPV(sv) will be used as the name of the method\nto call.\n\nSome other values are treated specially for internal use and should not be depended on.\n\nSee perlcall.\n\nNOTE: the perlcallsv() form is deprecated.\n\nI32 callsv(SV *sv, volatile I32 flags)\n\n\"DESTRUCTORFUNCNOCONTEXTt\"\nDescribed in perlguts.\n\n\"DESTRUCTORFUNCt\"\nDescribed in perlguts.\n\n\"ENTER\"\nOpening bracket on a callback. See \"LEAVE\" and perlcall.\n\nENTER;\n\n\"ENTERwithname\"\nSame as \"ENTER\", but when debugging is enabled it also associates the given literal\nstring with the new scope.\n\nENTERwithname(\"name\");\n\n\"evalpv\"\nTells Perl to \"eval\" the given string in scalar context and return an SV* result.\n\nNOTE: the perlevalpv() form is deprecated.\n\nSV * evalpv(const char *p, I32 croakonerror)\n\n\"evalsv\"\nTells Perl to \"eval\" the string in the SV. It supports the same flags as \"callsv\", with\nthe obvious exception of \"GEVAL\". See perlcall.\n\nThe \"GRETHROW\" flag can be used if you only need evalsv() to execute code specified by\na string, but not catch any errors.\n\nNOTE: the perlevalsv() form is deprecated.\n\nI32 evalsv(SV *sv, I32 flags)\n\n\"FREETMPS\"\nClosing bracket for temporaries on a callback. See \"SAVETMPS\" and perlcall.\n\nFREETMPS;\n\n\"GDISCARD\"\nDescribed in perlcall.\n\n\"GEVAL\"\nDescribed in perlcall.\n\n\"GIMME\"\n\"DEPRECATED!\" It is planned to remove \"GIMME\" from a future release of Perl. Do not use\nit for new code; remove it from existing code.\n\nA backward-compatible version of \"GIMMEV\" which can only return \"GSCALAR\" or \"GLIST\";\nin a void context, it returns \"GSCALAR\". Deprecated. Use \"GIMMEV\" instead.\n\nU32 GIMME\n\n\"GIMMEV\"\nThe XSUB-writer's equivalent to Perl's \"wantarray\". Returns \"GVOID\", \"GSCALAR\" or\n\"GLIST\" for void, scalar or list context, respectively. See perlcall for a usage\nexample.\n\nU32 GIMMEV\n\n\"GKEEPERR\"\nDescribed in perlcall.\n\n\"GLIST\"\nDescribed in perlcall.\n\n\"GNOARGS\"\nDescribed in perlcall.\n\n\"GSCALAR\"\nDescribed in perlcall.\n\n\"GVOID\"\nDescribed in perlcall.\n\n\"islvaluesub\"\nReturns non-zero if the sub calling this function is being called in an lvalue context.\nReturns 0 otherwise.\n\nI32 islvaluesub()\n\n\"LEAVE\"\nClosing bracket on a callback. See \"ENTER\" and perlcall.\n\nLEAVE;\n\n\"LEAVEwithname\"\nSame as \"LEAVE\", but when debugging is enabled it first checks that the scope has the\ngiven name. \"name\" must be a literal string.\n\nLEAVEwithname(\"name\");\n\n\"MORTALDESTRUCTORSV\"\nDescribed in perlguts.\n\nMORTALDESTRUCTORSV(SV *coderef, SV *args)\n\n\"mortaldestructorsv\"\nThis function arranges for either a Perl code reference, or a C function reference to be\ncalled at the end of the current statement.\n\nThe \"coderef\" argument determines the type of function that will be called. If it is\nSvROK() it is assumed to be a reference to a CV and will arrange for the coderef to be\ncalled. If it is not SvROK() then it is assumed to be a SvIV() which is SvIOK() whose\nvalue is a pointer to a C function of type \"DESTRUCTORFUNCt\" created using PTR2INT().\nEither way the \"args\" parameter will be provided to the callback as a parameter, although\nthe rules for doing so differ between the Perl and C mode. Normally this function is only\nused directly for the Perl case and the wrapper mortaldestructorx() is used for the C\nfunction case.\n\nWhen operating in Perl callback mode the \"args\" parameter may be NULL in which case the\ncode reference is called with no arguments, otherwise if it is an AV (SvTYPE(args) ==\nSVtPVAV) then the contents of the AV will be used as the arguments to the code\nreference, and if it is any other type then the \"args\" SV will be provided as a single\nargument to the code reference.\n\nWhen operating in a C callback mode the \"args\" parameter will be passed directly to the C\nfunction as a \"void *\" pointer. No additional processing of the argument will be\npeformed, and it is the callers responsibility to free the \"args\" parameter if necessary.\n\nBe aware that there is a signficant difference in timing between the end of the current\nstatement and the end of the current pseudo block. If you are looking for a mechanism to\ntrigger a function at the end of the current pseudo block you should look at\nSAVEDESTRUCTORX() instead of this function.\n\nvoid mortaldestructorsv(SV *coderef, SV *args)\n\n\"MORTALDESTRUCTORX\"\nDescribed in perlguts.\n\nMORTALDESTRUCTORX(DESTRUCTORFUNCt f, SV *sv)\n\n\"PLerrgv\"\nDescribed in perlcall.\n\n\"saveaelem\"\n\"saveaelemflags\"\nThese each arrange for the value of the array element \"av[idx]\" to be restored at the end\nof the enclosing pseudo-block.\n\nIn \"saveaelem\", the SV at Csptr> will be replaced by a new \"undef\" scalar. That\nscalar will inherit any magic from the original sptr, and any 'set' magic will be\nprocessed.\n\nIn \"saveaelemflags\", \"SAVEfKEEPOLDELEM\" being set in \"flags\" causes the function to\nforgo all that: the scalar at sptr is untouched. If \"SAVEfKEEPOLDELEM\" is not set,\nthe SV at Csptr> will be replaced by a new \"undef\" scalar. That scalar will inherit\nany magic from the original sptr. Any 'set' magic will be processed if and only if\n\"SAVEfSETMAGIC\" is set in in \"flags\".\n\nvoid saveaelem (AV *av, SSizet idx, SV sptr)\nvoid saveaelemflags(AV *av, SSizet idx, SV sptr,\nconst U32 flags)\n\n\"saveaptr\"\nDescribed in perlguts.\n\nvoid saveaptr(AV aptr)\n\n\"saveary\"\nDescribed in perlguts.\n\nAV * saveary(GV *gv)\n\n\"SAVEBOOL\"\nDescribed in perlguts.\n\nSAVEBOOL(bool i)\n\n\"SAVEDELETE\"\nDescribed in perlguts.\n\nSAVEDELETE(HV * hv, char * key, I32 length)\n\n\"SAVEDESTRUCTOR\"\nDescribed in perlguts.\n\nSAVEDESTRUCTOR(DESTRUCTORFUNCNOCONTEXTt f, void *p)\n\n\"SAVEDESTRUCTORX\"\nDescribed in perlguts.\n\nSAVEDESTRUCTORX(DESTRUCTORFUNCt f, void *p)\n\n\"SAVEFREEOP\"\nDescribed in perlguts.\n\nSAVEFREEOP(OP *op)\n\n\"SAVEFREEPV\"\nDescribed in perlguts.\n\nSAVEFREEPV(char *pv)\n\n\"SAVEFREERCPV\"\nDescribed in perlguts.\n\nSAVEFREERCPV(char *pv)\n\n\"SAVEFREESV\"\nDescribed in perlguts.\n\nSAVEFREESV(SV* sv)\n\n\"SAVEGENERICSV\"\nDescribed in perlguts.\n\nSAVEGENERICSV(char psv)\n\n\"savehash\"\nDescribed in perlguts.\n\nHV * savehash(GV *gv)\n\n\"savehelem\"\n\"savehelemflags\"\nThese each arrange for the value of the hash element (in Perlish terms) \"$hv{key}]\" to be\nrestored at the end of the enclosing pseudo-block.\n\nIn \"savehelem\", the SV at Csptr> will be replaced by a new \"undef\" scalar. That\nscalar will inherit any magic from the original sptr, and any 'set' magic will be\nprocessed.\n\nIn \"savehelemflags\", \"SAVEfKEEPOLDELEM\" being set in \"flags\" causes the function to\nforgo all that: the scalar at sptr is untouched. If \"SAVEfKEEPOLDELEM\" is not set,\nthe SV at Csptr> will be replaced by a new \"undef\" scalar. That scalar will inherit\nany magic from the original sptr. Any 'set' magic will be processed if and only if\n\"SAVEfSETMAGIC\" is set in in \"flags\".\n\nvoid savehelem (HV *hv, SV *key, SV sptr)\nvoid savehelemflags(HV *hv, SV *key, SV sptr,\nconst U32 flags)\n\n\"savehptr\"\nDescribed in perlguts.\n\nvoid savehptr(HV hptr)\n\n\"SAVEINT\"\nDescribed in perlguts.\n\nSAVEINT(int i)\n\n\"saveitem\"\nDescribed in perlguts.\n\nvoid saveitem(SV *item)\n\n\"SAVEIV\"\nDescribed in perlguts.\n\nSAVEIV(IV i)\n\n\"SAVEI8\"\nDescribed in perlguts.\n\nSAVEI8(I8 i)\n\n\"SAVEI16\"\nDescribed in perlguts.\n\nSAVEI16(I16 i)\n\n\"SAVEI32\"\nDescribed in perlguts.\n\nSAVEI32(I32 i)\n\n\"SAVELONG\"\nDescribed in perlguts.\n\nSAVELONG(long i)\n\n\"SAVEMORTALIZESV\"\nDescribed in perlguts.\n\nSAVEMORTALIZESV(SV* sv)\n\n\"SAVEPPTR\"\nDescribed in perlguts.\n\nSAVEPPTR(char * p)\n\n\"SAVERCPV\"\nDescribed in perlguts.\n\nSAVERCPV(char *pv)\n\n\"savescalar\"\nDescribed in perlguts.\n\nSV * savescalar(GV *gv)\n\n\"SAVESPTR\"\nDescribed in perlguts.\n\nSAVESPTR(SV * s)\n\n\"SAVESTACKPOS\"\nDescribed in perlguts.\n\nSAVESTACKPOS()\n\n\"SAVESTRLEN\"\nDescribed in perlguts.\n\nSAVESTRLEN(STRLEN i)\n\n\"savesvref\"\nDescribed in perlguts.\n\nSV * savesvref(SV sptr)\n\n\"SAVETMPS\"\nOpening bracket for temporaries on a callback. See \"FREETMPS\" and perlcall.\n\nSAVETMPS;\n", "subsections": [] }, "Casting": { "content": "\"Atof\"\nThis is a synonym for \"\"myatof\"\".\n\nNV Atof(NN const char * const s)\n\n\"cBOOL\"\nCast-to-bool. When Perl was able to be compiled on pre-C99 compilers, a \"(bool)\" cast\ndidn't necessarily do the right thing, so this macro was created (and made somewhat\ncomplicated to work around bugs in old compilers). Now, many years later, and C99 is\nused, this is no longer required, but is kept for backwards compatibility.\n\nbool cBOOL(bool expr)\n\n\"INT2PTR\"\nDescribed in perlguts.\n\ntype INT2PTR(type, int value)\n\n\"IV\"\nCast an NV to IV while avoiding undefined C behavior\n\nIV IV(NV what)\n\n\"I32\"\nCast an NV to I32 while avoiding undefined C behavior\n\nI32 I32(NV what)\n\n\"PTR2IV\"\nDescribed in perlguts.\n\nIV PTR2IV(void * ptr)\n\n\"PTR2nat\"\nDescribed in perlguts.\n\nIV PTR2nat(void *)\n\n\"PTR2NV\"\nDescribed in perlguts.\n\nNV PTR2NV(void * ptr)\n\n\"PTR2ul\"\nDescribed in perlguts.\n\nunsigned long PTR2ul(void *)\n\n\"PTR2UV\"\nDescribed in perlguts.\n\nUV PTR2UV(void * ptr)\n\n\"PTRV\"\nDescribed in perlguts.\n\n\"UV\"\nCast an NV to UV while avoiding undefined C behavior\n\nUV UV(NV what)\n\n\"U32\"\nCast an NV to U32 while avoiding undefined C behavior\n\nU32 U32(NV what)\n", "subsections": [] }, "Character case changing": { "content": "Perl uses \"full\" Unicode case mappings. This means that converting a single character to\nanother case may result in a sequence of more than one character. For example, the uppercase\nof \"ß\" (LATIN SMALL LETTER SHARP S) is the two character sequence \"SS\". This presents some\ncomplications The lowercase of all characters in the range 0..255 is a single character,\nand thus \"toLOWERL1\" is furnished. But, \"toUPPERL1\" can't exist, as it couldn't return a\nvalid result for all legal inputs. Instead \"toUPPERuvchr\" has an API that does allow every\npossible legal result to be returned.) Likewise no other function that is crippled by not\nbeing able to give the correct results for the full range of possible inputs has been\nimplemented here.\n\n\"toFOLD\"\n\"toFOLDA\"\n\"toFOLDutf8\"\n\"toFOLDutf8safe\"\n\"toFOLDuvchr\"\nThese all return the foldcase of a character. \"foldcase\" is an internal case for \"/i\"\npattern matching. If the foldcase of character A and the foldcase of character B are the\nsame, they match caselessly; otherwise they don't.\n\nThe differences in the forms are what domain they operate on, and whether the input is\nspecified as a code point (those forms with a \"cp\" parameter) or as a UTF-8 string (the\nothers). In the latter case, the code point to use is the first one in the buffer of\nUTF-8 encoded code points, delineated by the arguments \"p .. e - 1\".\n\n\"toFOLD\" and \"toFOLDA\" are synonyms of each other. They return the foldcase of any\nASCII-range code point. In this range, the foldcase is identical to the lowercase. All\nother inputs are returned unchanged. Since these are macros, the input type may be any\nintegral one, and the output will occupy the same number of bits as the input.\n\nThere is no \"toFOLDL1\" nor \"toFOLDLATIN1\" as the foldcase of some code points in the\n0..255 range is above that range or consists of multiple characters. Instead use\n\"toFOLDuvchr\".\n\n\"toFOLDuvchr\" returns the foldcase of any Unicode code point. The return value is\nidentical to that of \"toFOLDA\" for input code points in the ASCII range. The foldcase\nof the vast majority of Unicode code points is the same as the code point itself. For\nthese, and for code points above the legal Unicode maximum, this returns the input code\npoint unchanged. It additionally stores the UTF-8 of the result into the buffer\nbeginning at \"s\", and its length in bytes into *lenp. The caller must have made \"s\"\nlarge enough to contain at least \"UTF8MAXBYTESCASE+1\" bytes to avoid possible overflow.\n\nNOTE: the foldcase of a code point may be more than one code point. The return value of\nthis function is only the first of these. The entire foldcase is returned in \"s\". To\ndetermine if the result is more than a single code point, you can do something like this:\n\nuc = toFOLDuvchr(cp, s, &len);\nif (len > UTF8SKIP(s)) { is multiple code points }\nelse { is a single code point }\n\n\"toFOLDutf8\" and \"toFOLDutf8safe\" are synonyms of each other. The only difference\nbetween these and \"toFOLDuvchr\" is that the source for these is encoded in UTF-8,\ninstead of being a code point. It is passed as a buffer starting at \"p\", with \"e\"\npointing to one byte beyond its end. The \"p\" buffer may certainly contain more than one\ncode point; but only the first one (up through \"e - 1\") is examined. If the UTF-8 for\nthe input character is malformed in some way, the program may croak, or the function may\nreturn the REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to\nchange in future releases.\n\nUV toFOLD (UV cp)\nUV toFOLDA (UV cp)\nUV toFOLDutf8 (U8* p, U8* e, U8* s, STRLEN* lenp)\nUV toFOLDutf8safe(U8* p, U8* e, U8* s, STRLEN* lenp)\nUV toFOLDuvchr (UV cp, U8* s, STRLEN* lenp)\n\n\"toLOWER\"\n\"toLOWERA\"\n\"toLOWERLATIN1\"\n\"toLOWERLC\"\n\"toLOWERL1\"\n\"toLOWERutf8\"\n\"toLOWERutf8safe\"\n\"toLOWERuvchr\"\nThese all return the lowercase of a character. The differences are what domain they\noperate on, and whether the input is specified as a code point (those forms with a \"cp\"\nparameter) or as a UTF-8 string (the others). In the latter case, the code point to use\nis the first one in the buffer of UTF-8 encoded code points, delineated by the arguments\n\"p .. e - 1\".\n\n\"toLOWER\" and \"toLOWERA\" are synonyms of each other. They return the lowercase of any\nuppercase ASCII-range code point. All other inputs are returned unchanged. Since these\nare macros, the input type may be any integral one, and the output will occupy the same\nnumber of bits as the input.\n\n\"toLOWERL1\" and \"toLOWERLATIN1\" are synonyms of each other. They behave identically as\n\"toLOWER\" for ASCII-range input. But additionally will return the lowercase of any\nuppercase code point in the entire 0..255 range, assuming a Latin-1 encoding (or the\nEBCDIC equivalent on such platforms).\n\n\"toLOWERLC\" returns the lowercase of the input code point according to the rules of the\ncurrent POSIX locale. Input code points outside the range 0..255 are returned unchanged.\n\n\"toLOWERuvchr\" returns the lowercase of any Unicode code point. The return value is\nidentical to that of \"toLOWERL1\" for input code points in the 0..255 range. The\nlowercase of the vast majority of Unicode code points is the same as the code point\nitself. For these, and for code points above the legal Unicode maximum, this returns the\ninput code point unchanged. It additionally stores the UTF-8 of the result into the\nbuffer beginning at \"s\", and its length in bytes into *lenp. The caller must have made\n\"s\" large enough to contain at least \"UTF8MAXBYTESCASE+1\" bytes to avoid possible\noverflow.\n\nNOTE: the lowercase of a code point may be more than one code point. The return value of\nthis function is only the first of these. The entire lowercase is returned in \"s\". To\ndetermine if the result is more than a single code point, you can do something like this:\n\nuc = toLOWERuvchr(cp, s, &len);\nif (len > UTF8SKIP(s)) { is multiple code points }\nelse { is a single code point }\n\n\"toLOWERutf8\" and \"toLOWERutf8safe\" are synonyms of each other. The only difference\nbetween these and \"toLOWERuvchr\" is that the source for these is encoded in UTF-8,\ninstead of being a code point. It is passed as a buffer starting at \"p\", with \"e\"\npointing to one byte beyond its end. The \"p\" buffer may certainly contain more than one\ncode point; but only the first one (up through \"e - 1\") is examined. If the UTF-8 for\nthe input character is malformed in some way, the program may croak, or the function may\nreturn the REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to\nchange in future releases.\n\nUV toLOWER (UV cp)\nUV toLOWERA (UV cp)\nUV toLOWERLATIN1 (UV cp)\nUV toLOWERLC (UV cp)\nUV toLOWERL1 (UV cp)\nUV toLOWERutf8 (U8* p, U8* e, U8* s, STRLEN* lenp)\nUV toLOWERutf8safe(U8* p, U8* e, U8* s, STRLEN* lenp)\nUV toLOWERuvchr (UV cp, U8* s, STRLEN* lenp)\n\n\"toTITLE\"\n\"toTITLEA\"\n\"toTITLEutf8\"\n\"toTITLEutf8safe\"\n\"toTITLEuvchr\"\nThese all return the titlecase of a character. The differences are what domain they\noperate on, and whether the input is specified as a code point (those forms with a \"cp\"\nparameter) or as a UTF-8 string (the others). In the latter case, the code point to use\nis the first one in the buffer of UTF-8 encoded code points, delineated by the arguments\n\"p .. e - 1\".\n\n\"toTITLE\" and \"toTITLEA\" are synonyms of each other. They return the titlecase of any\nlowercase ASCII-range code point. In this range, the titlecase is identical to the\nuppercase. All other inputs are returned unchanged. Since these are macros, the input\ntype may be any integral one, and the output will occupy the same number of bits as the\ninput.\n\nThere is no \"toTITLEL1\" nor \"toTITLELATIN1\" as the titlecase of some code points in the\n0..255 range is above that range or consists of multiple characters. Instead use\n\"toTITLEuvchr\".\n\n\"toTITLEuvchr\" returns the titlecase of any Unicode code point. The return value is\nidentical to that of \"toTITLEA\" for input code points in the ASCII range. The titlecase\nof the vast majority of Unicode code points is the same as the code point itself. For\nthese, and for code points above the legal Unicode maximum, this returns the input code\npoint unchanged. It additionally stores the UTF-8 of the result into the buffer\nbeginning at \"s\", and its length in bytes into *lenp. The caller must have made \"s\"\nlarge enough to contain at least \"UTF8MAXBYTESCASE+1\" bytes to avoid possible overflow.\n\nNOTE: the titlecase of a code point may be more than one code point. The return value of\nthis function is only the first of these. The entire titlecase is returned in \"s\". To\ndetermine if the result is more than a single code point, you can do something like this:\n\nuc = toTITLEuvchr(cp, s, &len);\nif (len > UTF8SKIP(s)) { is multiple code points }\nelse { is a single code point }\n\n\"toTITLEutf8\" and \"toTITLEutf8safe\" are synonyms of each other. The only difference\nbetween these and \"toTITLEuvchr\" is that the source for these is encoded in UTF-8,\ninstead of being a code point. It is passed as a buffer starting at \"p\", with \"e\"\npointing to one byte beyond its end. The \"p\" buffer may certainly contain more than one\ncode point; but only the first one (up through \"e - 1\") is examined. If the UTF-8 for\nthe input character is malformed in some way, the program may croak, or the function may\nreturn the REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to\nchange in future releases.\n\nUV toTITLE (UV cp)\nUV toTITLEA (UV cp)\nUV toTITLEutf8 (U8* p, U8* e, U8* s, STRLEN* lenp)\nUV toTITLEutf8safe(U8* p, U8* e, U8* s, STRLEN* lenp)\nUV toTITLEuvchr (UV cp, U8* s, STRLEN* lenp)\n\n\"toUPPER\"\n\"toUPPERA\"\n\"toUPPERutf8\"\n\"toUPPERutf8safe\"\n\"toUPPERuvchr\"\nThese all return the uppercase of a character. The differences are what domain they\noperate on, and whether the input is specified as a code point (those forms with a \"cp\"\nparameter) or as a UTF-8 string (the others). In the latter case, the code point to use\nis the first one in the buffer of UTF-8 encoded code points, delineated by the arguments\n\"p .. e - 1\".\n\n\"toUPPER\" and \"toUPPERA\" are synonyms of each other. They return the uppercase of any\nlowercase ASCII-range code point. All other inputs are returned unchanged. Since these\nare macros, the input type may be any integral one, and the output will occupy the same\nnumber of bits as the input.\n\nThere is no \"toUPPERL1\" nor \"toUPPERLATIN1\" as the uppercase of some code points in the\n0..255 range is above that range or consists of multiple characters. Instead use\n\"toUPPERuvchr\".\n\n\"toUPPERuvchr\" returns the uppercase of any Unicode code point. The return value is\nidentical to that of \"toUPPERA\" for input code points in the ASCII range. The uppercase\nof the vast majority of Unicode code points is the same as the code point itself. For\nthese, and for code points above the legal Unicode maximum, this returns the input code\npoint unchanged. It additionally stores the UTF-8 of the result into the buffer\nbeginning at \"s\", and its length in bytes into *lenp. The caller must have made \"s\"\nlarge enough to contain at least \"UTF8MAXBYTESCASE+1\" bytes to avoid possible overflow.\n\nNOTE: the uppercase of a code point may be more than one code point. The return value of\nthis function is only the first of these. The entire uppercase is returned in \"s\". To\ndetermine if the result is more than a single code point, you can do something like this:\n\nuc = toUPPERuvchr(cp, s, &len);\nif (len > UTF8SKIP(s)) { is multiple code points }\nelse { is a single code point }\n\n\"toUPPERutf8\" and \"toUPPERutf8safe\" are synonyms of each other. The only difference\nbetween these and \"toUPPERuvchr\" is that the source for these is encoded in UTF-8,\ninstead of being a code point. It is passed as a buffer starting at \"p\", with \"e\"\npointing to one byte beyond its end. The \"p\" buffer may certainly contain more than one\ncode point; but only the first one (up through \"e - 1\") is examined. If the UTF-8 for\nthe input character is malformed in some way, the program may croak, or the function may\nreturn the REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to\nchange in future releases.\n\nUV toUPPER (UV cp)\nUV toUPPERA (UV cp)\nUV toUPPERutf8 (U8* p, U8* e, U8* s, STRLEN* lenp)\nUV toUPPERutf8safe(U8* p, U8* e, U8* s, STRLEN* lenp)\nUV toUPPERuvchr (UV cp, U8* s, STRLEN* lenp)\n", "subsections": [] }, "Character classification": { "content": "This section is about functions (really macros) that classify characters into types, such as\npunctuation versus alphabetic, etc. Most of these are analogous to regular expression\ncharacter classes. (See \"POSIX Character Classes\" in perlrecharclass.) There are several\nvariants for each class. (Not all macros have all variants; each item below lists the ones\nvalid for it.) None are affected by \"use bytes\", and only the ones with \"LC\" in the name are\naffected by the current locale.\n\nThe base function, e.g., isALPHA(), takes any signed or unsigned value, treating it as a code\npoint, and returns a boolean as to whether or not the character represented by it is (or on\nnon-ASCII platforms, corresponds to) an ASCII character in the named class based on platform,\nUnicode, and Perl rules. If the input is a number that doesn't fit in an octet, FALSE is\nreturned.\n\nVariant \"isFOOA\" (e.g., isALPHAA()) is identical to the base function with no suffix \"A\".\nThis variant is used to emphasize by its name that only ASCII-range characters can return\nTRUE.\n\nVariant \"isFOOL1\" imposes the Latin-1 (or EBCDIC equivalent) character set onto the\nplatform. That is, the code points that are ASCII are unaffected, since ASCII is a subset of\nLatin-1. But the non-ASCII code points are treated as if they are Latin-1 characters. For\nexample, isWORDCHARL1() will return true when called with the code point 0xDF, which is a\nword character in both ASCII and EBCDIC (though it represents different characters in each).\nIf the input is a number that doesn't fit in an octet, FALSE is returned. (Perl's\ndocumentation uses a colloquial definition of Latin-1, to include all code points below 256.)\n\nVariant \"isFOOuvchr\" is exactly like the \"isFOOL1\" variant, for inputs below 256, but if\nthe code point is larger than 255, Unicode rules are used to determine if it is in the\ncharacter class. For example, isWORDCHARuvchr(0x100) returns TRUE, since 0x100 is LATIN\nCAPITAL LETTER A WITH MACRON in Unicode, and is a word character.\n\nVariants \"isFOOutf8\" and \"isFOOutf8safe\" are like \"isFOOuvchr\", but are used for UTF-8\nencoded strings. The two forms are different names for the same thing. Each call to one of\nthese classifies the first character of the string starting at \"p\". The second parameter,\n\"e\", points to anywhere in the string beyond the first character, up to one byte past the end\nof the entire string. Although both variants are identical, the suffix \"safe\" in one name\nemphasizes that it will not attempt to read beyond \"e - 1\", provided that the constraint\n\"s < e\" is true (this is asserted for in \"-DDEBUGGING\" builds). If the UTF-8 for the input\ncharacter is malformed in some way, the program may croak, or the function may return FALSE,\nat the discretion of the implementation, and subject to change in future releases.\n\nVariant \"isFOOLC\" is like the \"isFOOA\" and \"isFOOL1\" variants, but the result is based on\nthe current locale, which is what \"LC\" in the name stands for. If Perl can determine that\nthe current locale is a UTF-8 locale, it uses the published Unicode rules; otherwise, it uses\nthe C library function that gives the named classification. For example, isDIGITLC() when\nnot in a UTF-8 locale returns the result of calling isdigit(). FALSE is always returned if\nthe input won't fit into an octet. On some platforms where the C library function is known\nto be defective, Perl changes its result to follow the POSIX standard's rules.\n\nVariant \"isFOOLCuvchr\" acts exactly like \"isFOOLC\" for inputs less than 256, but for\nlarger ones it returns the Unicode classification of the code point.\n\nVariants \"isFOOLCutf8\" and \"isFOOLCutf8safe\" are like \"isFOOLCuvchr\", but are used for\nUTF-8 encoded strings. The two forms are different names for the same thing. Each call to\none of these classifies the first character of the string starting at \"p\". The second\nparameter, \"e\", points to anywhere in the string beyond the first character, up to one byte\npast the end of the entire string. Although both variants are identical, the suffix \"safe\"\nin one name emphasizes that it will not attempt to read beyond \"e - 1\", provided that the\nconstraint \"s < e\" is true (this is asserted for in \"-DDEBUGGING\" builds). If the UTF-8 for\nthe input character is malformed in some way, the program may croak, or the function may\nreturn FALSE, at the discretion of the implementation, and subject to change in future\nreleases.\n\n\"isALNUM\"\n\"isALNUMA\"\n\"isALNUMLC\"\n\"isALNUMLCuvchr\"\nThese are each a synonym for their respectively named \"\"isWORDCHAR\"\" variant.\n\nThey are provided for backward compatibility, even though a word character includes more\nthan the standard C language meaning of alphanumeric. To get the C language definition,\nuse the corresponding \"\"isALPHANUMERIC\"\" variant.\n\nbool isALNUM(UV ch)\n\n\"isALNUMC\"\n\"isALNUMCA\"\n\"isALNUMCLC\"\n\"isALNUMCLCuvchr\"\n\"isALNUMCL1\"\nThese are discouraged, backward compatibility macros for \"\"isALPHANUMERIC\"\". That is,\neach returns a boolean indicating whether the specified character is one of\n\"[A-Za-z0-9]\", analogous to \"m/[[:alnum:]]/\".\n\nThe \"C\" suffix in the names was meant to indicate that they correspond to the C language\nisalnum(3).\n\nbool isALNUMC(UV ch)\n\n\"isALPHA\"\n\"isALPHAA\"\n\"isALPHALC\"\n\"isALPHALCutf8safe\"\n\"isALPHALCuvchr\"\n\"isALPHAL1\"\n\"isALPHAutf8\"\n\"isALPHAutf8safe\"\n\"isALPHAuvchr\"\nReturns a boolean indicating whether the specified input is one of \"[A-Za-z]\", analogous\nto \"m/[[:alpha:]]/\". See the top of this section for an explanation of the variants.\n\nbool isALPHA (UV ch)\nbool isALPHAA (UV ch)\nbool isALPHALC (UV ch)\nbool isALPHALCutf8safe(U8 * s, U8 *end)\nbool isALPHALCuvchr (UV ch)\nbool isALPHAL1 (UV ch)\nbool isALPHAutf8 (U8 * s, U8 * end)\nbool isALPHAutf8safe (U8 * s, U8 * end)\nbool isALPHAuvchr (UV ch)\n\n\"isALPHANUMERIC\"\n\"isALPHANUMERICA\"\n\"isALPHANUMERICLC\"\n\"isALPHANUMERICLCutf8safe\"\n\"isALPHANUMERICLCuvchr\"\n\"isALPHANUMERICL1\"\n\"isALPHANUMERICutf8\"\n\"isALPHANUMERICutf8safe\"\n\"isALPHANUMERICuvchr\"\nReturns a boolean indicating whether the specified character is one of \"[A-Za-z0-9]\",\nanalogous to \"m/[[:alnum:]]/\". See the top of this section for an explanation of the\nvariants.\n\nbool isALPHANUMERIC (UV ch)\nbool isALPHANUMERICA (UV ch)\nbool isALPHANUMERICLC (UV ch)\nbool isALPHANUMERICLCutf8safe(U8 * s, U8 *end)\nbool isALPHANUMERICLCuvchr (UV ch)\nbool isALPHANUMERICL1 (UV ch)\nbool isALPHANUMERICutf8 (U8 * s, U8 * end)\nbool isALPHANUMERICutf8safe (U8 * s, U8 * end)\nbool isALPHANUMERICuvchr (UV ch)\n\n\"isASCII\"\n\"isASCIIA\"\n\"isASCIILC\"\n\"isASCIILCutf8safe\"\n\"isASCIILCuvchr\"\n\"isASCIIL1\"\n\"isASCIIutf8\"\n\"isASCIIutf8safe\"\n\"isASCIIuvchr\"\nReturns a boolean indicating whether the specified character is one of the 128 characters\nin the ASCII character set, analogous to \"m/[[:ascii:]]/\". On non-ASCII platforms, it\nreturns TRUE iff this character corresponds to an ASCII character. Variants isASCIIA()\nand isASCIIL1() are identical to isASCII(). See the top of this section for an\nexplanation of the variants. Note, however, that some platforms do not have the C\nlibrary routine isascii(). In these cases, the variants whose names contain \"LC\" are the\nsame as the corresponding ones without.\n\nAlso note, that because all ASCII characters are UTF-8 invariant (meaning they have the\nexact same representation (always a single byte) whether encoded in UTF-8 or not),\n\"isASCII\" will give the correct results when called with any byte in any string encoded\nor not in UTF-8. And similarly \"isASCIIutf8\" and \"isASCIIutf8safe\" will work properly\non any string encoded or not in UTF-8.\n\nbool isASCII (UV ch)\nbool isASCIIA (UV ch)\nbool isASCIILC (UV ch)\nbool isASCIILCutf8safe(U8 * s, U8 *end)\nbool isASCIILCuvchr (UV ch)\nbool isASCIIL1 (UV ch)\nbool isASCIIutf8 (U8 * s, U8 * end)\nbool isASCIIutf8safe (U8 * s, U8 * end)\nbool isASCIIuvchr (UV ch)\n\n\"isBLANK\"\n\"isBLANKA\"\n\"isBLANKLC\"\n\"isBLANKLCutf8safe\"\n\"isBLANKLCuvchr\"\n\"isBLANKL1\"\n\"isBLANKutf8\"\n\"isBLANKutf8safe\"\n\"isBLANKuvchr\"\nReturns a boolean indicating whether the specified character is a character considered to\nbe a blank, analogous to \"m/[[:blank:]]/\". See the top of this section for an\nexplanation of the variants. Note, however, that some platforms do not have the C\nlibrary routine isblank(). In these cases, the variants whose names contain \"LC\" are the\nsame as the corresponding ones without.\n\nbool isBLANK (UV ch)\nbool isBLANKA (UV ch)\nbool isBLANKLC (UV ch)\nbool isBLANKLCutf8safe(U8 * s, U8 *end)\nbool isBLANKLCuvchr (UV ch)\nbool isBLANKL1 (UV ch)\nbool isBLANKutf8 (U8 * s, U8 * end)\nbool isBLANKutf8safe (U8 * s, U8 * end)\nbool isBLANKuvchr (UV ch)\n\n\"isCNTRL\"\n\"isCNTRLA\"\n\"isCNTRLLC\"\n\"isCNTRLLCutf8safe\"\n\"isCNTRLLCuvchr\"\n\"isCNTRLL1\"\n\"isCNTRLutf8\"\n\"isCNTRLutf8safe\"\n\"isCNTRLuvchr\"\nReturns a boolean indicating whether the specified character is a control character,\nanalogous to \"m/[[:cntrl:]]/\". See the top of this section for an explanation of the\nvariants. On EBCDIC platforms, you almost always want to use the \"isCNTRLL1\" variant.\n\nbool isCNTRL (UV ch)\nbool isCNTRLA (UV ch)\nbool isCNTRLLC (UV ch)\nbool isCNTRLLCutf8safe(U8 * s, U8 *end)\nbool isCNTRLLCuvchr (UV ch)\nbool isCNTRLL1 (UV ch)\nbool isCNTRLutf8 (U8 * s, U8 * end)\nbool isCNTRLutf8safe (U8 * s, U8 * end)\nbool isCNTRLuvchr (UV ch)\n\n\"isDIGIT\"\n\"isDIGITA\"\n\"isDIGITLC\"\n\"isDIGITLCutf8safe\"\n\"isDIGITLCuvchr\"\n\"isDIGITL1\"\n\"isDIGITutf8\"\n\"isDIGITutf8safe\"\n\"isDIGITuvchr\"\nReturns a boolean indicating whether the specified character is a digit, analogous to\n\"m/[[:digit:]]/\". Variants \"isDIGITA\" and \"isDIGITL1\" are identical to \"isDIGIT\". See\nthe top of this section for an explanation of the variants.\n\nbool isDIGIT (UV ch)\nbool isDIGITA (UV ch)\nbool isDIGITLC (UV ch)\nbool isDIGITLCutf8safe(U8 * s, U8 *end)\nbool isDIGITLCuvchr (UV ch)\nbool isDIGITL1 (UV ch)\nbool isDIGITutf8 (U8 * s, U8 * end)\nbool isDIGITutf8safe (U8 * s, U8 * end)\nbool isDIGITuvchr (UV ch)\n\n\"isGRAPH\"\n\"isGRAPHA\"\n\"isGRAPHLC\"\n\"isGRAPHLCutf8safe\"\n\"isGRAPHLCuvchr\"\n\"isGRAPHL1\"\n\"isGRAPHutf8\"\n\"isGRAPHutf8safe\"\n\"isGRAPHuvchr\"\nReturns a boolean indicating whether the specified character is a graphic character,\nanalogous to \"m/[[:graph:]]/\". See the top of this section for an explanation of the\nvariants.\n\nbool isGRAPH (UV ch)\nbool isGRAPHA (UV ch)\nbool isGRAPHLC (UV ch)\nbool isGRAPHLCutf8safe(U8 * s, U8 *end)\nbool isGRAPHLCuvchr (UV ch)\nbool isGRAPHL1 (UV ch)\nbool isGRAPHutf8 (U8 * s, U8 * end)\nbool isGRAPHutf8safe (U8 * s, U8 * end)\nbool isGRAPHuvchr (UV ch)\n\n\"isIDCONT\"\n\"isIDCONTA\"\n\"isIDCONTLC\"\n\"isIDCONTLCutf8safe\"\n\"isIDCONTLCuvchr\"\n\"isIDCONTL1\"\n\"isIDCONTutf8\"\n\"isIDCONTutf8safe\"\n\"isIDCONTuvchr\"\nReturns a boolean indicating whether the specified character can be the second or\nsucceeding character of an identifier. This is very close to, but not quite the same as\nthe official Unicode property \"XIDContinue\". The difference is that this returns true\nonly if the input character also matches \"isWORDCHAR\". See the top of this section for\nan explanation of the variants.\n\nbool isIDCONT (UV ch)\nbool isIDCONTA (UV ch)\nbool isIDCONTLC (UV ch)\nbool isIDCONTLCutf8safe(U8 * s, U8 *end)\nbool isIDCONTLCuvchr (UV ch)\nbool isIDCONTL1 (UV ch)\nbool isIDCONTutf8 (U8 * s, U8 * end)\nbool isIDCONTutf8safe (U8 * s, U8 * end)\nbool isIDCONTuvchr (UV ch)\n\n\"isIDFIRST\"\n\"isIDFIRSTA\"\n\"isIDFIRSTLC\"\n\"isIDFIRSTLCutf8safe\"\n\"isIDFIRSTLCuvchr\"\n\"isIDFIRSTL1\"\n\"isIDFIRSTutf8\"\n\"isIDFIRSTutf8safe\"\n\"isIDFIRSTuvchr\"\nReturns a boolean indicating whether the specified character can be the first character\nof an identifier. This is very close to, but not quite the same as the official Unicode\nproperty \"XIDStart\". The difference is that this returns true only if the input\ncharacter also matches \"isWORDCHAR\". See the top of this section for an explanation of\nthe variants.\n\nbool isIDFIRST (UV ch)\nbool isIDFIRSTA (UV ch)\nbool isIDFIRSTLC (UV ch)\nbool isIDFIRSTLCutf8safe(U8 * s, U8 *end)\nbool isIDFIRSTLCuvchr (UV ch)\nbool isIDFIRSTL1 (UV ch)\nbool isIDFIRSTutf8 (U8 * s, U8 * end)\nbool isIDFIRSTutf8safe (U8 * s, U8 * end)\nbool isIDFIRSTuvchr (UV ch)\n\n\"isLOWER\"\n\"isLOWERA\"\n\"isLOWERLC\"\n\"isLOWERLCutf8safe\"\n\"isLOWERLCuvchr\"\n\"isLOWERL1\"\n\"isLOWERutf8\"\n\"isLOWERutf8safe\"\n\"isLOWERuvchr\"\nReturns a boolean indicating whether the specified character is a lowercase character,\nanalogous to \"m/[[:lower:]]/\". See the top of this section for an explanation of the\nvariants\n\nbool isLOWER (UV ch)\nbool isLOWERA (UV ch)\nbool isLOWERLC (UV ch)\nbool isLOWERLCutf8safe(U8 * s, U8 *end)\nbool isLOWERLCuvchr (UV ch)\nbool isLOWERL1 (UV ch)\nbool isLOWERutf8 (U8 * s, U8 * end)\nbool isLOWERutf8safe (U8 * s, U8 * end)\nbool isLOWERuvchr (UV ch)\n\n\"isOCTAL\"\n\"isOCTALA\"\n\"isOCTALL1\"\nReturns a boolean indicating whether the specified character is an octal digit, [0-7].\nThe only two variants are \"isOCTALA\" and \"isOCTALL1\"; each is identical to \"isOCTAL\".\n\nbool isOCTAL(UV ch)\n\n\"isPRINT\"\n\"isPRINTA\"\n\"isPRINTLC\"\n\"isPRINTLCutf8safe\"\n\"isPRINTLCuvchr\"\n\"isPRINTL1\"\n\"isPRINTutf8\"\n\"isPRINTutf8safe\"\n\"isPRINTuvchr\"\nReturns a boolean indicating whether the specified character is a printable character,\nanalogous to \"m/[[:print:]]/\". See the top of this section for an explanation of the\nvariants.\n\nbool isPRINT (UV ch)\nbool isPRINTA (UV ch)\nbool isPRINTLC (UV ch)\nbool isPRINTLCutf8safe(U8 * s, U8 *end)\nbool isPRINTLCuvchr (UV ch)\nbool isPRINTL1 (UV ch)\nbool isPRINTutf8 (U8 * s, U8 * end)\nbool isPRINTutf8safe (U8 * s, U8 * end)\nbool isPRINTuvchr (UV ch)\n\n\"isPSXSPC\"\n\"isPSXSPCA\"\n\"isPSXSPCLC\"\n\"isPSXSPCLCutf8safe\"\n\"isPSXSPCLCuvchr\"\n\"isPSXSPCL1\"\n\"isPSXSPCutf8\"\n\"isPSXSPCutf8safe\"\n\"isPSXSPCuvchr\"\n(short for Posix Space) Starting in 5.18, this is identical in all its forms to the\ncorresponding isSPACE() macros. The locale forms of this macro are identical to their\ncorresponding isSPACE() forms in all Perl releases. In releases prior to 5.18, the non-\nlocale forms differ from their isSPACE() forms only in that the isSPACE() forms don't\nmatch a Vertical Tab, and the isPSXSPC() forms do. Otherwise they are identical. Thus\nthis macro is analogous to what \"m/[[:space:]]/\" matches in a regular expression. See\nthe top of this section for an explanation of the variants.\n\nbool isPSXSPC (UV ch)\nbool isPSXSPCA (UV ch)\nbool isPSXSPCLC (UV ch)\nbool isPSXSPCLCutf8safe(U8 * s, U8 *end)\nbool isPSXSPCLCuvchr (UV ch)\nbool isPSXSPCL1 (UV ch)\nbool isPSXSPCutf8 (U8 * s, U8 * end)\nbool isPSXSPCutf8safe (U8 * s, U8 * end)\nbool isPSXSPCuvchr (UV ch)\n\n\"isPUNCT\"\n\"isPUNCTA\"\n\"isPUNCTLC\"\n\"isPUNCTLCutf8safe\"\n\"isPUNCTLCuvchr\"\n\"isPUNCTL1\"\n\"isPUNCTutf8\"\n\"isPUNCTutf8safe\"\n\"isPUNCTuvchr\"\nReturns a boolean indicating whether the specified character is a punctuation character,\nanalogous to \"m/[[:punct:]]/\". Note that the definition of what is punctuation isn't as\nstraightforward as one might desire. See \"POSIX Character Classes\" in perlrecharclass\nfor details. See the top of this section for an explanation of the variants.\n\nbool isPUNCT (UV ch)\nbool isPUNCTA (UV ch)\nbool isPUNCTLC (UV ch)\nbool isPUNCTLCutf8safe(U8 * s, U8 *end)\nbool isPUNCTLCuvchr (UV ch)\nbool isPUNCTL1 (UV ch)\nbool isPUNCTutf8 (U8 * s, U8 * end)\nbool isPUNCTutf8safe (U8 * s, U8 * end)\nbool isPUNCTuvchr (UV ch)\n\n\"isSPACE\"\n\"isSPACEA\"\n\"isSPACELC\"\n\"isSPACELCutf8safe\"\n\"isSPACELCuvchr\"\n\"isSPACEL1\"\n\"isSPACEutf8\"\n\"isSPACEutf8safe\"\n\"isSPACEuvchr\"\nReturns a boolean indicating whether the specified character is a whitespace character.\nThis is analogous to what \"m/\\s/\" matches in a regular expression. Starting in Perl 5.18\nthis also matches what \"m/[[:space:]]/\" does. Prior to 5.18, only the locale forms of\nthis macro (the ones with \"LC\" in their names) matched precisely what \"m/[[:space:]]/\"\ndoes. In those releases, the only difference, in the non-locale variants, was that\nisSPACE() did not match a vertical tab. (See \"isPSXSPC\" for a macro that matches a\nvertical tab in all releases.) See the top of this section for an explanation of the\nvariants.\n\nbool isSPACE (UV ch)\nbool isSPACEA (UV ch)\nbool isSPACELC (UV ch)\nbool isSPACELCutf8safe(U8 * s, U8 *end)\nbool isSPACELCuvchr (UV ch)\nbool isSPACEL1 (UV ch)\nbool isSPACEutf8 (U8 * s, U8 * end)\nbool isSPACEutf8safe (U8 * s, U8 * end)\nbool isSPACEuvchr (UV ch)\n\n\"isUPPER\"\n\"isUPPERA\"\n\"isUPPERLC\"\n\"isUPPERLCutf8safe\"\n\"isUPPERLCuvchr\"\n\"isUPPERL1\"\n\"isUPPERutf8\"\n\"isUPPERutf8safe\"\n\"isUPPERuvchr\"\nReturns a boolean indicating whether the specified character is an uppercase character,\nanalogous to \"m/[[:upper:]]/\". See the top of this section for an explanation of the\nvariants.\n\nbool isUPPER (UV ch)\nbool isUPPERA (UV ch)\nbool isUPPERLC (UV ch)\nbool isUPPERLCutf8safe(U8 * s, U8 *end)\nbool isUPPERLCuvchr (UV ch)\nbool isUPPERL1 (UV ch)\nbool isUPPERutf8 (U8 * s, U8 * end)\nbool isUPPERutf8safe (U8 * s, U8 * end)\nbool isUPPERuvchr (UV ch)\n\n\"isWORDCHAR\"\n\"isWORDCHARA\"\n\"isWORDCHARLC\"\n\"isWORDCHARLCutf8safe\"\n\"isWORDCHARLCuvchr\"\n\"isWORDCHARL1\"\n\"isWORDCHARutf8\"\n\"isWORDCHARutf8safe\"\n\"isWORDCHARuvchr\"\nReturns a boolean indicating whether the specified character is a character that is a\nword character, analogous to what \"m/\\w/\" and \"m/[[:word:]]/\" match in a regular\nexpression. A word character is an alphabetic character, a decimal digit, a connecting\npunctuation character (such as an underscore), or a \"mark\" character that attaches to one\nof those (like some sort of accent).\n\nSee the top of this section for an explanation of the variants.\n\n\"isWORDCHARA\", \"isWORDCHARL1\", \"isWORDCHARuvchr\", \"isWORDCHARLC\",\n\"isWORDCHARLCuvchr\", \"isWORDCHARLCutf8\", and \"isWORDCHARLCutf8safe\" are also as\ndescribed there, but additionally include the platform's native underscore.\n\nbool isWORDCHAR (UV ch)\nbool isWORDCHARA (UV ch)\nbool isWORDCHARLC (UV ch)\nbool isWORDCHARLCutf8safe(U8 * s, U8 *end)\nbool isWORDCHARLCuvchr (UV ch)\nbool isWORDCHARL1 (UV ch)\nbool isWORDCHARutf8 (U8 * s, U8 * end)\nbool isWORDCHARutf8safe (U8 * s, U8 * end)\nbool isWORDCHARuvchr (UV ch)\n\n\"isXDIGIT\"\n\"isXDIGITA\"\n\"isXDIGITLC\"\n\"isXDIGITLCutf8safe\"\n\"isXDIGITLCuvchr\"\n\"isXDIGITL1\"\n\"isXDIGITutf8\"\n\"isXDIGITutf8safe\"\n\"isXDIGITuvchr\"\nReturns a boolean indicating whether the specified character is a hexadecimal digit. In\nthe ASCII range these are \"[0-9A-Fa-f]\". Variants isXDIGITA() and isXDIGITL1() are\nidentical to isXDIGIT(). See the top of this section for an explanation of the variants.\n\nbool isXDIGIT (UV ch)\nbool isXDIGITA (UV ch)\nbool isXDIGITLC (UV ch)\nbool isXDIGITLCutf8safe(U8 * s, U8 *end)\nbool isXDIGITLCuvchr (UV ch)\nbool isXDIGITL1 (UV ch)\nbool isXDIGITutf8 (U8 * s, U8 * end)\nbool isXDIGITutf8safe (U8 * s, U8 * end)\nbool isXDIGITuvchr (UV ch)\n", "subsections": [] }, "Compiler and Preprocessor information": { "content": "\"CPPLAST\"\nThis symbol is intended to be used along with \"CPPRUN\" in the same manner symbol\n\"CPPMINUS\" is used with \"CPPSTDIN\". It contains either \"-\" or \"\".\n\n\"CPPMINUS\"\nThis symbol contains the second part of the string which will invoke the C preprocessor\non the standard input and produce to standard output. This symbol will have the value\n\"-\" if \"CPPSTDIN\" needs a minus to specify standard input, otherwise the value is \"\".\n\n\"CPPRUN\"\nThis symbol contains the string which will invoke a C preprocessor on the standard input\nand produce to standard output. It needs to end with \"CPPLAST\", after all other\npreprocessor flags have been specified. The main difference with \"CPPSTDIN\" is that this\nprogram will never be a pointer to a shell wrapper, i.e. it will be empty if no\npreprocessor is available directly to the user. Note that it may well be different from\nthe preprocessor used to compile the C program.\n\n\"CPPSTDIN\"\nThis symbol contains the first part of the string which will invoke the C preprocessor on\nthe standard input and produce to standard output. Typical value of \"cc -E\" or\n\"/lib/cpp\", but it can also call a wrapper. See \"CPPRUN\".\n\n\"HASATTRIBUTEALWAYSINLINE\"\nCan we handle \"GCC\" attribute for functions that should always be inlined.\n\n\"HASATTRIBUTEDEPRECATED\"\nCan we handle \"GCC\" attribute for marking deprecated \"APIs\"\n\n\"HASATTRIBUTEFORMAT\"\nCan we handle \"GCC\" attribute for checking printf-style formats\n\n\"HASATTRIBUTENONNULL\"\nCan we handle \"GCC\" attribute for nonnull function parms.\n\n\"HASATTRIBUTENORETURN\"\nCan we handle \"GCC\" attribute for functions that do not return\n\n\"HASATTRIBUTEPURE\"\nCan we handle \"GCC\" attribute for pure functions\n\n\"HASATTRIBUTEUNUSED\"\nCan we handle \"GCC\" attribute for unused variables and arguments\n\n\"HASATTRIBUTEVISIBILITY\"\nCan we handle \"GCC\" attribute for functions that should have a different visibility.\n\n\"HASATTRIBUTEWARNUNUSEDRESULT\"\nCan we handle \"GCC\" attribute for warning on unused results\n\n\"HASBUILTINADDOVERFLOW\"\nThis symbol, if defined, indicates that the compiler supports \"builtinaddoverflow\"\nfor adding integers with overflow checks.\n\n\"HASBUILTINCHOOSEEXPR\"\nCan we handle \"GCC\" builtin for compile-time ternary-like expressions\n\n\"HASBUILTINEXPECT\"\nCan we handle \"GCC\" builtin for telling that certain values are more likely\n\n\"HASBUILTINMULOVERFLOW\"\nThis symbol, if defined, indicates that the compiler supports \"builtinmuloverflow\"\nfor multiplying integers with overflow checks.\n\n\"HASBUILTINSUBOVERFLOW\"\nThis symbol, if defined, indicates that the compiler supports \"builtinsuboverflow\"\nfor subtracting integers with overflow checks.\n\n\"HASC99VARIADICMACROS\"\nIf defined, the compiler supports C99 variadic macros.\n\n\"HASSTATICINLINE\"\nThis symbol, if defined, indicates that the C compiler supports C99-style static inline.\nThat is, the function can't be called from another translation unit.\n\n\"MEMALIGNBYTES\"\nThis symbol contains the number of bytes required to align a double, or a long double\nwhen applicable. Usual values are 2, 4 and 8. The default is eight, for safety. For\ncross-compiling or multiarch support, Configure will set a minimum of 8.\n\n\"PERLSTATICINLINE\"\nThis symbol gives the best-guess incantation to use for static inline functions. If\n\"HASSTATICINLINE\" is defined, this will give C99-style inline. If \"HASSTATICINLINE\"\nis not defined, this will give a plain 'static'. It will always be defined to something\nthat gives static linkage. Possibilities include\n\nstatic inline (c99)\nstatic inline (gcc -ansi)\nstatic inline (MSVC)\nstatic inline (older MSVC)\nstatic (c89 compilers)\n\n\"PERLTHREADLOCAL\"\nThis symbol, if defined, gives a linkage specification for thread-local storage. For\nexample, for a C11 compiler this will be \"Threadlocal\". Beware, some compilers are\nsensitive to the C language standard they are told to parse. For example, suncc defaults\nto C11, so our probe will report that \"Threadlocal\" can be used. However, if the\n-std=c99 is later added to the compiler flags, then \"Threadlocal\" will become a syntax\nerror. Hence it is important for these flags to be consistent between probing and use.\n\n\"U32ALIGNMENTREQUIRED\"\nThis symbol, if defined, indicates that you must access character data through\nU32-aligned pointers.\n", "subsections": [] }, "Compiler directives": { "content": "\"ASSERT\"\nThis is a helper macro to avoid preprocessor issues, replaced by nothing unless under\nDEBUGGING, where it expands to an assert of its argument, followed by a comma (hence the\ncomma operator). If we just used a straight assert(), we would get a comma with nothing\nbefore it when not DEBUGGING.\n\nASSERT(bool expr)\n\n\"ASSUME\"\n\"ASSUME\" is like assert(), but it has a benefit in a release build. It is a hint to a\ncompiler about a statement of fact in a function call free expression, which allows the\ncompiler to generate better machine code. In a debug build, ASSUME(x) is a synonym for\nassert(x). ASSUME(0) means the control path is unreachable. In a for loop, \"ASSUME\" can\nbe used to hint that a loop will run at least X times. \"ASSUME\" is based off MSVC's\n\"assume\" intrinsic function, see its documents for more details.\n\nASSUME(bool expr)\n\n\"dNOOP\"\nDeclare nothing; typically used as a placeholder to replace something that used to\ndeclare something. Works on compilers that require declarations before any code.\n\ndNOOP;\n\n\"ENDEXTERNC\"\nWhen not compiling using C++, expands to nothing. Otherwise ends a section of code\nalready begun by a \"STARTEXTERNC\".\n\nENDEXTERNC\n\n\"EXTERNC\"\nWhen not compiling using C++, expands to nothing. Otherwise is used in a declaration of\na function to indicate the function should have external C linkage. This is required for\nthings to work for just about all functions with external linkage compiled into perl.\nOften, you can use \"STARTEXTERNC\" ... \"ENDEXTERNC\" blocks surrounding all your code\nthat you need to have this linkage.\n\nExample usage:\n\nEXTERNC int flock(int fd, int op);\n\n\"LIKELY\"\nReturns the input unchanged, but at the same time it gives a branch prediction hint to\nthe compiler that this condition is likely to be true.\n\nLIKELY(bool expr)\n\n\"NOOP\"\nDo nothing; typically used as a placeholder to replace something that used to do\nsomething.\n\nNOOP;\n\n\"PERLUNUSEDARG\"\nThis is used to suppress compiler warnings that a parameter to a function is not used.\nThis situation can arise, for example, when a parameter is needed under some\nconfiguration conditions, but not others, so that C preprocessor conditional compilation\ncauses it be used just sometimes.\n\nPERLUNUSEDARG(void x);\n\n\"PERLUNUSEDCONTEXT\"\nThis is used to suppress compiler warnings that the thread context parameter to a\nfunction is not used. This situation can arise, for example, when a C preprocessor\nconditional compilation causes it be used just some times.\n\nPERLUNUSEDCONTEXT;\n\n\"PERLUNUSEDDECL\"\nTells the compiler that the parameter in the function prototype just before it is not\nnecessarily expected to be used in the function. Not that many compilers understand\nthis, so this should only be used in cases where \"PERLUNUSEDARG\" can't conveniently be\nused.\n\nExample usage:\n\nSignalt\nPerlperlysighandler(int sig, Siginfot *sip PERLUNUSEDDECL,\nvoid *uap PERLUNUSEDDECL, bool safe)\n\n\"PERLUNUSEDRESULT\"\nThis macro indicates to discard the return value of the function call inside it, e.g.,\n\nPERLUNUSEDRESULT(foo(a, b))\n\nThe main reason for this is that the combination of \"gcc -Wunused-result\" (part of\n\"-Wall\") and the \"attribute((warnunusedresult))\" cannot be silenced with casting to\n\"void\". This causes trouble when the system header files use the attribute.\n\nUse \"PERLUNUSEDRESULT\" sparingly, though, since usually the warning is there for a good\nreason: you might lose success/failure information, or leak resources, or changes in\nresources.\n\nBut sometimes you just want to ignore the return value, e.g., on codepaths soon ending up\nin abort, or in \"best effort\" attempts, or in situations where there is no good way to\nhandle failures.\n\nSometimes \"PERLUNUSEDRESULT\" might not be the most natural way: another possibility is\nthat you can capture the return value and use \"PERLUNUSEDVAR\" on that.\n\nPERLUNUSEDRESULT(void x)\n\n\"PERLUNUSEDVAR\"\nThis is used to suppress compiler warnings that the variable x is not used. This\nsituation can arise, for example, when a C preprocessor conditional compilation causes it\nbe used just some times.\n\nPERLUNUSEDVAR(void x);\n\n\"STARTEXTERNC\"\nWhen not compiling using C++, expands to nothing. Otherwise begins a section of code in\nwhich every function will effectively have \"EXTERNC\" applied to it, that is to have\nexternal C linkage. The section is ended by a \"ENDEXTERNC\".\n\nSTARTEXTERNC\n\n\"STATIC\"\nDescribed in perlguts.\n\n\"STMTEND\"\n\"STMTSTART\"\nThese allow a series of statements in a macro to be used as a single statement, as in\n\nif (x) STMTSTART { ... } STMTEND else ...\n\nNote that you can't return a value out of this construct and cannot use it as an operand\nto the comma operator. These limit its utility.\n\nBut, a value could be returned by constructing the API so that a pointer is passed and\nthe macro dereferences this to set the return. If the value can be any of various types,\ndepending on context, you can handle that situation in some situations by adding the type\nof the return as an extra accompanying parameter:\n\n#define foo(param, type) STMTSTART {\ntype * param; *param = docalc; ...\n} STMTEND\n\nThis could be awkward, so consider instead using a C language \"static inline\" function.\n\nIf you do use this construct, it is easy to forget that it is a macro and not a function,\nand hence fall into traps that might not show up until someone someday writes code which\ncontains names that clash with the ones you chose here, or calls it with a parameter\nwhich is an expression with side effects, the consequences of which you didn't think\nabout. See \"Writing safer macros\" in perlhacktips for how to avoid these.\n\n\"UNLIKELY\"\nReturns the input unchanged, but at the same time it gives a branch prediction hint to\nthe compiler that this condition is likely to be false.\n\nUNLIKELY(bool expr)\n", "subsections": [] }, "Compile-time scope hooks": { "content": "\"BhkDISABLE\"\nNOTE: \"BhkDISABLE\" is experimental and may change or be removed without notice.\n\nTemporarily disable an entry in this BHK structure, by clearing the appropriate flag.\n\"which\" is a preprocessor token indicating which entry to disable.\n\nvoid BhkDISABLE(BHK *hk, token which)\n\n\"BhkENABLE\"\nNOTE: \"BhkENABLE\" is experimental and may change or be removed without notice.\n\nRe-enable an entry in this BHK structure, by setting the appropriate flag. \"which\" is a\npreprocessor token indicating which entry to enable. This will assert (under\n-DDEBUGGING) if the entry doesn't contain a valid pointer.\n\nvoid BhkENABLE(BHK *hk, token which)\n\n\"BhkENTRYset\"\nNOTE: \"BhkENTRYset\" is experimental and may change or be removed without notice.\n\nSet an entry in the BHK structure, and set the flags to indicate it is valid. \"which\" is\na preprocessing token indicating which entry to set. The type of \"ptr\" depends on the\nentry.\n\nvoid BhkENTRYset(BHK *hk, token which, void *ptr)\n\n\"blockhookregister\"\nNOTE: \"blockhookregister\" is experimental and may change or be removed without notice.\n\nRegister a set of hooks to be called when the Perl lexical scope changes at compile time.\nSee \"Compile-time scope hooks\" in perlguts.\n\nNOTE: \"blockhookregister\" must be explicitly called as \"Perlblockhookregister\" with an\n\"aTHX\" parameter.\n\nvoid Perlblockhookregister(pTHX BHK *hk)\n", "subsections": [] }, "Concurrency": { "content": "\"aTHX\"\nDescribed in perlguts.\n\n\"aTHX\"\nDescribed in perlguts.\n\n\"CPERLscope\"\n\"DEPRECATED!\" It is planned to remove \"CPERLscope\" from a future release of Perl. Do\nnot use it for new code; remove it from existing code.\n\nNow a no-op.\n\nvoid CPERLscope(void x)\n\n\"dTHR\"\nDescribed in perlguts.\n\n\"dTHX\"\nDescribed in perlguts.\n\n\"dTHXa\"\nOn threaded perls, set \"pTHX\" to \"a\"; on unthreaded perls, do nothing\n\n\"dTHXoa\"\nNow a synonym for \"dTHXa\".\n\n\"dVAR\"\nThis is now a synonym for dNOOP: declare nothing\n\n\"GETENVPRESERVESOTHERTHREAD\"\nThis symbol, if defined, indicates that the getenv system call doesn't zap the static\nbuffer of getenv() in a different thread. The typical getenv() implementation will\nreturn a pointer to the proper position in environ. But some may instead copy them to\na static buffer in getenv(). If there is a per-thread instance of that buffer, or the\nreturn points to environ, then a many-reader/1-writer mutex will work; otherwise an\nexclusive locking mutex is required to prevent races.\n\n\"HASPTHREADATFORK\"\nThis symbol, if defined, indicates that the \"pthreadatfork\" routine is available to\nsetup fork handlers.\n\n\"HASPTHREADATTRSETSCOPE\"\nThis symbol, if defined, indicates that the \"pthreadattrsetscope\" system call is\navailable to set the contention scope attribute of a thread attribute object.\n\n\"HASPTHREADYIELD\"\nThis symbol, if defined, indicates that the \"pthreadyield\" routine is available to yield\nthe execution of the current thread. \"schedyield\" is preferable to \"pthreadyield\".\n\n\"HASSCHEDYIELD\"\nThis symbol, if defined, indicates that the \"schedyield\" routine is available to yield\nthe execution of the current thread. \"schedyield\" is preferable to \"pthreadyield\".\n\n\"IMACHCTHREADS\"\nThis symbol, if defined, indicates to the C program that it should include\nmach/cthreads.h.\n\n#ifdef IMACHCTHREADS\n#include \n#endif\n\n\"IPTHREAD\"\nThis symbol, if defined, indicates to the C program that it should include pthread.h.\n\n#ifdef IPTHREAD\n#include \n#endif\n\n\"MULTIPLICITY\"\nThis symbol, if defined, indicates that Perl should be built to use multiplicity.\n\n\"OLDPTHREADCREATEJOINABLE\"\nThis symbol, if defined, indicates how to create pthread in joinable (aka undetached)\nstate. \"NOTE\": not defined if pthread.h already has defined \"PTHREADCREATEJOINABLE\"\n(the new version of the constant). If defined, known values are\n\"PTHREADCREATEUNDETACHED\" and \"UNDETACHED\".\n\n\"OLDPTHREADSAPI\"\nThis symbol, if defined, indicates that Perl should be built to use the old draft \"POSIX\"\nthreads \"API\".\n\n\"PERLIMPLICITCONTEXT\"\nDescribed in perlguts.\n\n\"PERLNOGETCONTEXT\"\nDescribed in perlguts.\n\n\"pTHX\"\nDescribed in perlguts.\n\n\"pTHX\"\nDescribed in perlguts.\n\n\"SCHEDYIELD\"\nThis symbol defines the way to yield the execution of the current thread. Known ways are\n\"schedyield\", \"pthreadyield\", and \"pthreadyield\" with \"NULL\".\n\nCOPs and Hint Hashes\n\"copfetchlabel\"\nNOTE: \"copfetchlabel\" is experimental and may change or be removed without notice.\n\nReturns the label attached to a cop, and stores its length in bytes into *len. Upon\nreturn, *flags will be set to either \"SVfUTF8\" or 0.\n\nAlternatively, use the macro \"CopLABELlenflags\"; or if you don't need to know if the\nlabel is UTF-8 or not, the macro \"CopLABELlen\"; or if you additionally don't need to\nknow the length, \"CopLABEL\".\n\nconst char * copfetchlabel(COP * const cop, STRLEN *len,\nU32 *flags)\n\n\"CopFILE\"\nReturns the name of the file associated with the \"COP\" \"c\"\n\nconst char * CopFILE(const COP * c)\n\n\"CopFILEAV\"\nReturns the AV associated with the \"COP\" \"c\", creating it if necessary.\n\nAV * CopFILEAV(const COP * c)\n\n\"CopFILEAVn\"\nReturns the AV associated with the \"COP\" \"c\", returning NULL if it doesn't already exist.\n\nAV * CopFILEAVn(const COP * c)\n\n\"CopFILEcopy\"\nEfficiently copies the cop file name from one COP to another. Wraps the required logic to\ndo a refcounted copy under threads or not.\n\nvoid CopFILEcopy(COP * dst, COP * src)\n\n\"CopFILEfree\"\nFrees the file data in a cop. Under the hood this is a refcounting operation.\n\nvoid CopFILEfree(COP * c)\n\n\"CopFILEGV\"\nReturns the GV associated with the \"COP\" \"c\"\n\nGV * CopFILEGV(const COP * c)\n\n\"CopFILEGVset\"\nAvailable only on unthreaded perls. Makes \"pv\" the name of the file associated with the\n\"COP\" \"c\"\n\nvoid CopFILEGVset(COP *c, GV *gv)\n\n\"CopFILELEN\"\nReturns the length of the file associated with the \"COP\" \"c\"\n\nconst char * CopFILELEN(const COP * c)\n\n\"CopFILEset\"\nMakes \"pv\" the name of the file associated with the \"COP\" \"c\"\n\nvoid CopFILEset(COP * c, const char * pv)\n\n\"CopFILEsetn\"\nMakes \"pv\" the name of the file associated with the \"COP\" \"c\"\n\nvoid CopFILEsetn(COP * c, const char * pv, STRLEN len)\n\n\"CopFILESV\"\nReturns the SV associated with the \"COP\" \"c\"\n\nSV * CopFILESV(const COP * c)\n\n\"cophhcopy\"\nNOTE: \"cophhcopy\" is experimental and may change or be removed without notice.\n\nMake and return a complete copy of the cop hints hash \"cophh\".\n\nCOPHH * cophhcopy(COPHH *cophh)\n\n\"cophhdeletepv\"\n\"cophhdeletepvn\"\n\"cophhdeletepvs\"\n\"cophhdeletesv\"\nNOTE: all these forms are experimental and may change or be removed without notice.\n\nThese delete a key and its associated value from the cop hints hash \"cophh\", and return\nthe modified hash. The returned hash pointer is in general not the same as the hash\npointer that was passed in. The input hash is consumed by the function, and the pointer\nto it must not be subsequently used. Use \"cophhcopy\" if you need both hashes.\n\nThe forms differ in how the key is specified. In all forms, the key is pointed to by\n\"key\". In the plain \"pv\" form, the key is a C language NUL-terminated string. In the\n\"pvs\" form, the key is a C language string literal. In the \"pvn\" form, an additional\nparameter, \"keylen\", specifies the length of the string, which hence, may contain\nembedded-NUL characters. In the \"sv\" form, *key is an SV, and the key is the PV\nextracted from that. using \"SvPVconst\".\n\n\"hash\" is a precomputed hash of the key string, or zero if it has not been precomputed.\nThis parameter is omitted from the \"pvs\" form, as it is computed automatically at compile\ntime.\n\nThe only flag currently used from the \"flags\" parameter is \"COPHHKEYUTF8\". It is\nillegal to set this in the \"sv\" form. In the \"pv*\" forms, it specifies whether the key\noctets are interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The \"sv\" form uses\nthe underlying SV to determine the UTF-8ness of the octets.\n\nCOPHH * cophhdeletepv (COPHH *cophh, const char *key, U32 hash,\nU32 flags)\nCOPHH * cophhdeletepvn(COPHH *cophh, const char *key,\nSTRLEN keylen, U32 hash, U32 flags)\nCOPHH * cophhdeletepvs(COPHH *cophh, \"key\", U32 flags)\nCOPHH * cophhdeletesv (COPHH *cophh, SV *key, U32 hash,\nU32 flags)\n\n\"cophhexistspvn\"\nNOTE: \"cophhexistspvn\" is experimental and may change or be removed without notice.\n\nThese look up the hint entry in the cop \"cop\" with the key specified by \"key\" (and\n\"keylen\" in the \"pvn\" form), returning true if a value exists, and false otherwise.\n\nThe forms differ in how the key is specified. In the plain \"pv\" form, the key is a C\nlanguage NUL-terminated string. In the \"pvs\" form, the key is a C language string\nliteral. In the \"pvn\" form, an additional parameter, \"keylen\", specifies the length of\nthe string, which hence, may contain embedded-NUL characters. In the \"sv\" form, *key is\nan SV, and the key is the PV extracted from that. using \"SvPVconst\".\n\n\"hash\" is a precomputed hash of the key string, or zero if it has not been precomputed.\nThis parameter is omitted from the \"pvs\" form, as it is computed automatically at compile\ntime.\n\nThe only flag currently used from the \"flags\" parameter is \"COPHHKEYUTF8\". It is\nillegal to set this in the \"sv\" form. In the \"pv*\" forms, it specifies whether the key\noctets are interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The \"sv\" form uses\nthe underlying SV to determine the UTF-8ness of the octets.\n\nbool cophhexistspvn(const COPHH *cophh, const char *key,\nSTRLEN keylen, U32 hash, U32 flags)\n\n\"cophhfetchpv\"\n\"cophhfetchpvn\"\n\"cophhfetchpvs\"\n\"cophhfetchsv\"\nNOTE: all these forms are experimental and may change or be removed without notice.\n\nThese look up the entry in the cop hints hash \"cophh\" with the key specified by \"key\"\n(and \"keylen\" in the \"pvn\" form), returning that value as a mortal scalar copy, or\n&PLsvplaceholder if there is no value associated with the key.\n\nThe forms differ in how the key is specified. In the plain \"pv\" form, the key is a C\nlanguage NUL-terminated string. In the \"pvs\" form, the key is a C language string\nliteral. In the \"pvn\" form, an additional parameter, \"keylen\", specifies the length of\nthe string, which hence, may contain embedded-NUL characters. In the \"sv\" form, *key is\nan SV, and the key is the PV extracted from that. using \"SvPVconst\".\n\n\"hash\" is a precomputed hash of the key string, or zero if it has not been precomputed.\nThis parameter is omitted from the \"pvs\" form, as it is computed automatically at compile\ntime.\n\nThe only flag currently used from the \"flags\" parameter is \"COPHHKEYUTF8\". It is\nillegal to set this in the \"sv\" form. In the \"pv*\" forms, it specifies whether the key\noctets are interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The \"sv\" form uses\nthe underlying SV to determine the UTF-8ness of the octets.\n\nSV * cophhfetchpv (const COPHH *cophh, const char *key,\nU32 hash, U32 flags)\nSV * cophhfetchpvn(const COPHH *cophh, const char *key,\nSTRLEN keylen, U32 hash, U32 flags)\nSV * cophhfetchpvs(const COPHH *cophh, \"key\", U32 flags)\nSV * cophhfetchsv (const COPHH *cophh, SV *key, U32 hash,\nU32 flags)\n\n\"cophhfree\"\nNOTE: \"cophhfree\" is experimental and may change or be removed without notice.\n\nDiscard the cop hints hash \"cophh\", freeing all resources associated with it.\n\nvoid cophhfree(COPHH *cophh)\n\n\"cophh2hv\"\nNOTE: \"cophh2hv\" is experimental and may change or be removed without notice.\n\nGenerates and returns a standard Perl hash representing the full set of key/value pairs\nin the cop hints hash \"cophh\". \"flags\" is currently unused and must be zero.\n\nHV * cophh2hv(const COPHH *cophh, U32 flags)\n\n\"cophhnewempty\"\nNOTE: \"cophhnewempty\" is experimental and may change or be removed without notice.\n\nGenerate and return a fresh cop hints hash containing no entries.\n\nCOPHH * cophhnewempty()\n\n\"cophhstorepv\"\n\"cophhstorepvn\"\n\"cophhstorepvs\"\n\"cophhstoresv\"\nNOTE: all these forms are experimental and may change or be removed without notice.\n\nThese store a value, associated with a key, in the cop hints hash \"cophh\", and return the\nmodified hash. The returned hash pointer is in general not the same as the hash pointer\nthat was passed in. The input hash is consumed by the function, and the pointer to it\nmust not be subsequently used. Use \"cophhcopy\" if you need both hashes.\n\n\"value\" is the scalar value to store for this key. \"value\" is copied by these functions,\nwhich thus do not take ownership of any reference to it, and hence later changes to the\nscalar will not be reflected in the value visible in the cop hints hash. Complex types\nof scalar will not be stored with referential integrity, but will be coerced to strings.\n\nThe forms differ in how the key is specified. In all forms, the key is pointed to by\n\"key\". In the plain \"pv\" form, the key is a C language NUL-terminated string. In the\n\"pvs\" form, the key is a C language string literal. In the \"pvn\" form, an additional\nparameter, \"keylen\", specifies the length of the string, which hence, may contain\nembedded-NUL characters. In the \"sv\" form, *key is an SV, and the key is the PV\nextracted from that. using \"SvPVconst\".\n\n\"hash\" is a precomputed hash of the key string, or zero if it has not been precomputed.\nThis parameter is omitted from the \"pvs\" form, as it is computed automatically at compile\ntime.\n\nThe only flag currently used from the \"flags\" parameter is \"COPHHKEYUTF8\". It is\nillegal to set this in the \"sv\" form. In the \"pv*\" forms, it specifies whether the key\noctets are interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The \"sv\" form uses\nthe underlying SV to determine the UTF-8ness of the octets.\n\nCOPHH * cophhstorepv (COPHH *cophh, const char *key, U32 hash,\nSV *value, U32 flags)\nCOPHH * cophhstorepvn(COPHH *cophh, const char *key,\nSTRLEN keylen, U32 hash, SV *value,\nU32 flags)\nCOPHH * cophhstorepvs(COPHH *cophh, \"key\", SV *value,\nU32 flags)\nCOPHH * cophhstoresv (COPHH *cophh, SV *key, U32 hash,\nSV *value, U32 flags)\n\n\"cophintsexistspv\"\n\"cophintsexistspvn\"\n\"cophintsexistspvs\"\n\"cophintsexistssv\"\nThese look up the hint entry in the cop \"cop\" with the key specified by \"key\" (and\n\"keylen\" in the \"pvn\" form), returning true if a value exists, and false otherwise.\n\nThe forms differ in how the key is specified. In all forms, the key is pointed to by\n\"key\". In the plain \"pv\" form, the key is a C language NUL-terminated string. In the\n\"pvs\" form, the key is a C language string literal. In the \"pvn\" form, an additional\nparameter, \"keylen\", specifies the length of the string, which hence, may contain\nembedded-NUL characters. In the \"sv\" form, *key is an SV, and the key is the PV\nextracted from that. using \"SvPVconst\".\n\n\"hash\" is a precomputed hash of the key string, or zero if it has not been precomputed.\nThis parameter is omitted from the \"pvs\" form, as it is computed automatically at compile\ntime.\n\nThe only flag currently used from the \"flags\" parameter is \"COPHHKEYUTF8\". It is\nillegal to set this in the \"sv\" form. In the \"pv*\" forms, it specifies whether the key\noctets are interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The \"sv\" form uses\nthe underlying SV to determine the UTF-8ness of the octets.\n\nbool cophintsexistspv (const COP *cop, const char *key,\nU32 hash, U32 flags)\nbool cophintsexistspvn(const COP *cop, const char *key,\nSTRLEN keylen, U32 hash, U32 flags)\nbool cophintsexistspvs(const COP *cop, \"key\", U32 flags)\nbool cophintsexistssv (const COP *cop, SV *key, U32 hash,\nU32 flags)\n\n\"cophintsfetchpv\"\n\"cophintsfetchpvn\"\n\"cophintsfetchpvs\"\n\"cophintsfetchsv\"\nThese look up the hint entry in the cop \"cop\" with the key specified by \"key\" (and\n\"keylen\" in the \"pvn\" form), returning that value as a mortal scalar copy, or\n&PLsvplaceholder if there is no value associated with the key.\n\nThe forms differ in how the key is specified. In the plain \"pv\" form, the key is a C\nlanguage NUL-terminated string. In the \"pvs\" form, the key is a C language string\nliteral. In the \"pvn\" form, an additional parameter, \"keylen\", specifies the length of\nthe string, which hence, may contain embedded-NUL characters. In the \"sv\" form, *key is\nan SV, and the key is the PV extracted from that. using \"SvPVconst\".\n\n\"hash\" is a precomputed hash of the key string, or zero if it has not been precomputed.\nThis parameter is omitted from the \"pvs\" form, as it is computed automatically at compile\ntime.\n\nThe only flag currently used from the \"flags\" parameter is \"COPHHKEYUTF8\". It is\nillegal to set this in the \"sv\" form. In the \"pv*\" forms, it specifies whether the key\noctets are interpreted as UTF-8 (if set) or as Latin-1 (if cleared). The \"sv\" form uses\nthe underlying SV to determine the UTF-8ness of the octets.\n\nSV * cophintsfetchpv (const COP *cop, const char *key,\nU32 hash, U32 flags)\nSV * cophintsfetchpvn(const COP *cop, const char *key,\nSTRLEN keylen, U32 hash, U32 flags)\nSV * cophintsfetchpvs(const COP *cop, \"key\", U32 flags)\nSV * cophintsfetchsv (const COP *cop, SV *key, U32 hash,\nU32 flags)\n\n\"cophints2hv\"\nGenerates and returns a standard Perl hash representing the full set of hint entries in\nthe cop \"cop\". \"flags\" is currently unused and must be zero.\n\nHV * cophints2hv(const COP *cop, U32 flags)\n\n\"CopLABEL\"\n\"CopLABELlen\"\n\"CopLABELlenflags\"\nThese return the label attached to a cop.\n\n\"CopLABELlen\" and \"CopLABELlenflags\" additionally store the number of bytes comprising\nthe returned label into *len.\n\n\"CopLABELlenflags\" additionally returns the UTF-8ness of the returned label, by setting\n*flags to 0 or \"SVfUTF8\".\n\nconst char * CopLABEL (COP *const cop)\nconst char * CopLABELlen (COP *const cop, STRLEN *len)\nconst char * CopLABELlenflags(COP *const cop, STRLEN *len,\nU32 *flags)\n\n\"CopLINE\"\nReturns the line number in the source code associated with the \"COP\" \"c\"\n\nlinet CopLINE(const COP * c)\n\n\"CopSTASH\"\nReturns the stash associated with \"c\".\n\nHV * CopSTASH(const COP * c)\n\n\"CopSTASHeq\"\nReturns a boolean as to whether or not \"hv\" is the stash associated with \"c\".\n\nbool CopSTASHeq(const COP * c, const HV * hv)\n\n\"CopSTASHPV\"\nReturns the package name of the stash associated with \"c\", or \"NULL\" if no associated\nstash\n\nchar * CopSTASHPV(const COP * c)\n\n\"CopSTASHPVset\"\nSet the package name of the stash associated with \"c\", to the NUL-terminated C string\n\"p\", creating the package if necessary.\n\nvoid CopSTASHPVset(COP * c, const char * pv)\n\n\"CopSTASHset\"\nSet the stash associated with \"c\" to \"hv\".\n\nbool CopSTASHset(COP * c, HV * hv)\n\n\"copstorelabel\"\nNOTE: \"copstorelabel\" is experimental and may change or be removed without notice.\n\nSave a label into a \"cophintshash\". You need to set flags to \"SVfUTF8\" for a UTF-8\nlabel. Any other flag is ignored.\n\nvoid copstorelabel(COP * const cop, const char *label,\nSTRLEN len, U32 flags)\n\n\"PERLSI\"\nUse this typedef to declare variables that are to hold \"struct stackinfo\".\n\n\"PLcurcop\"\nThe currently active COP (control op) roughly representing the current statement in the\nsource.\n\nOn threaded perls, each thread has an independent copy of this variable; each initialized\nat creation time with the current value of the creating thread's copy.\n\nCOP* PLcurcop\n\n\"RCPVLEN\"\nReturns the length of a pv created with rcpvnew(). Note that this reflects the length\nof the string from the callers point of view, it does not include the mandatory null\nwhich is always injected at the end of the string by rcpvnew(). No checks are performed\nto ensure that \"pv\" was actually allocated with rcpvnew(), it is the callers\nresponsibility to ensure that this is the case.\n\nRCPV * RCPVLEN(char *pv)\n\n\"RCPVREFCNTdec\"\nDecrements the refcount for a \"char *\" pointer which was created with a call to\nrcpvnew(). Same as calling rcpvfree(). No checks are performed to ensure that \"pv\" was\nactually allocated with rcpvnew(), it is the callers responsibility to ensure that this\nis the case.\n\nRCPV * RCPVREFCNTdec(char *pv)\n\n\"RCPVREFCNTinc\"\nIncrements the refcount for a \"char *\" pointer which was created with a call to\nrcpvnew(). Same as calling rcpvcopy(). No checks are performed to ensure that \"pv\" was\nactually allocated with rcpvnew(), it is the callers responsibility to ensure that this\nis the case.\n\nRCPV * RCPVREFCNTinc(char *pv)\n\n\"RCPVREFCOUNT\"\nReturns the refcount for a pv created with rcpvnew(). No checks are performed to ensure\nthat \"pv\" was actually allocated with rcpvnew(), it is the callers responsibility to\nensure that this is the case.\n\nRCPV * RCPVREFCOUNT(char *pv)\n\n\"RCPVx\"\nReturns the RCPV structure (struct rcpv) for a refcounted string pv created with\nrcpvnew(). No checks are performed to ensure that \"pv\" was actually allocated with\nrcpvnew(), it is the callers responsibility to ensure that this is the case.\n\nRCPV * RCPVx(char *pv)\n", "subsections": [] }, "Custom Operators": { "content": "\"customopregister\"\nRegister a custom op. See \"Custom Operators\" in perlguts.\n\nNOTE: \"customopregister\" must be explicitly called as \"Perlcustomopregister\" with an\n\"aTHX\" parameter.\n\nvoid Perlcustomopregister(pTHX Perlppaddrt ppaddr,\nconst XOP *xop)\n\n\"Perlcustomopxop\"\nReturn the XOP structure for a given custom op. This macro should be considered internal\nto \"OPNAME\" and the other access macros: use them instead. This macro does call a\nfunction. Prior to 5.19.6, this was implemented as a function.\n\nconst XOP * Perlcustomopxop(pTHX const OP *o)\n\n\"XopDISABLE\"\nTemporarily disable a member of the XOP, by clearing the appropriate flag.\n\nvoid XopDISABLE(XOP *xop, token which)\n\n\"XopENABLE\"\nReenable a member of the XOP which has been disabled.\n\nvoid XopENABLE(XOP *xop, token which)\n\n\"XopENTRY\"\nReturn a member of the XOP structure. \"which\" is a cpp token indicating which entry to\nreturn. If the member is not set this will return a default value. The return type\ndepends on \"which\". This macro evaluates its arguments more than once. If you are using\n\"Perlcustomopxop\" to retrieve a \"XOP *\" from a \"OP *\", use the more efficient\n\"XopENTRYCUSTOM\" instead.\n\nXopENTRY(XOP *xop, token which)\n\n\"XopENTRYCUSTOM\"\nExactly like \"XopENTRY(XopENTRY(Perlcustomopxop(aTHX o), which)\" but more efficient.\nThe \"which\" parameter is identical to \"XopENTRY\".\n\nXopENTRYCUSTOM(const OP *o, token which)\n\n\"XopENTRYset\"\nSet a member of the XOP structure. \"which\" is a cpp token indicating which entry to set.\nSee \"Custom Operators\" in perlguts for details about the available members and how they\nare used. This macro evaluates its argument more than once.\n\nvoid XopENTRYset(XOP *xop, token which, value)\n\n\"XopFLAGS\"\nReturn the XOP's flags.\n\nU32 XopFLAGS(XOP *xop)\n\nCV Handling\nThis section documents functions to manipulate CVs which are code-values, meaning\nsubroutines. For more information, see perlguts.\n\n\"callercx\"\nThe XSUB-writer's equivalent of caller(). The returned \"PERLCONTEXT\" structure can be\ninterrogated to find all the information returned to Perl by \"caller\". Note that XSUBs\ndon't get a stack frame, so \"callercx(0, NULL)\" will return information for the\nimmediately-surrounding Perl code.\n\nThis function skips over the automatic calls to &DB::sub made on the behalf of the\ndebugger. If the stack frame requested was a sub called by \"DB::sub\", the return value\nwill be the frame for the call to \"DB::sub\", since that has the correct line number/etc.\nfor the call site. If dbcxp is non-\"NULL\", it will be set to a pointer to the frame for\nthe sub call itself.\n\nconst PERLCONTEXT * callercx(I32 level,\nconst PERLCONTEXT dbcxp)\n\n\"CvDEPTH\"\nReturns the recursion level of the CV \"sv\". Hence >= 2 indicates we are in a recursive\ncall.\n\nI32 * CvDEPTH(const CV * const sv)\n\n\"CvGV\"\nReturns the GV associated with the CV \"sv\", reifying it if necessary.\n\nGV * CvGV(CV *sv)\n\n\"CvSTASH\"\nReturns the stash of the CV. A stash is the symbol table hash, containing the package-\nscoped variables in the package where the subroutine was defined. For more information,\nsee perlguts.\n\nThis also has a special use with XS AUTOLOAD subs. See \"Autoloading with XSUBs\" in\nperlguts.\n\nHV* CvSTASH(CV* cv)\n\n\"findruncv\"\nLocate the CV corresponding to the currently executing sub or eval. If \"dbseqp\" is\nnonnull, skip CVs that are in the DB package and populate *dbseqp with the cop sequence\nnumber at the point that the DB:: code was entered. (This allows debuggers to eval in\nthe scope of the breakpoint rather than in the scope of the debugger itself.)\n\nCV * findruncv(U32 *dbseqp)\n\n\"getcv\"\n\"getcvnflags\"\n\"getcvs\"\nThese return the CV of the specified Perl subroutine. \"flags\" are passed to\n\"gvfetchpvnflags\". If \"GVADD\" is set and the Perl subroutine does not exist then it\nwill be declared (which has the same effect as saying \"sub name;\"). If \"GVADD\" is not\nset and the subroutine does not exist, then NULL is returned.\n\nThe forms differ only in how the subroutine is specified.. With \"getcvs\", the name is a\nliteral C string, enclosed in double quotes. With \"getcv\", the name is given by the\n\"name\" parameter, which must be a NUL-terminated C string. With \"getcvnflags\", the\nname is also given by the \"name\" parameter, but it is a Perl string (possibly containing\nembedded NUL bytes), and its length in bytes is contained in the \"len\" parameter.\n\nNOTE: the perlgetcv() form is deprecated.\n\nNOTE: the perlgetcvnflags() form is deprecated.\n\nNOTE: the perlgetcvs() form is deprecated.\n\nCV * getcv (const char *name, I32 flags)\nCV * getcvnflags(const char *name, STRLEN len, I32 flags)\nCV * getcvs (\"string\", I32 flags)\n\n\"Nullcv\"\n\"DEPRECATED!\" It is planned to remove \"Nullcv\" from a future release of Perl. Do not\nuse it for new code; remove it from existing code.\n\nNull CV pointer.\n\n(deprecated - use \"(CV *)NULL\" instead)\n", "subsections": [] }, "Debugging": { "content": "\"avdump\"\nDumps the contents of an AV to the \"STDERR\" filehandle, Similar to using Devel::Peek on\nan arrayref but does not expect an RV wrapper. Dumps contents to a depth of 3 levels\ndeep.\n\nvoid avdump(AV *av)\n\n\"deb\"\n\"debnocontext\"\nWhen perl is compiled with \"-DDEBUGGING\", this prints to STDERR the information given by\nthe arguments, prefaced by the name of the file containing the script causing the call,\nand the line number within that file.\n\nIf the \"v\" (verbose) debugging option is in effect, the process id is also printed.\n\nThe two forms differ only in that \"debnocontext\" does not take a thread context (\"aTHX\")\nparameter, so is used in situations where the caller doesn't already have the thread\ncontext.\n\nNOTE: \"deb\" must be explicitly called as \"Perldeb\" with an \"aTHX\" parameter.\n\nvoid Perldeb (pTHX const char *pat, ...)\nvoid debnocontext(const char *pat, ...)\n\n\"debstack\"\nDump the current stack\n\nI32 debstack()\n\n\"dumpall\"\nDumps the entire optree of the current program starting at \"PLmainroot\" to \"STDERR\".\nAlso dumps the optrees for all visible subroutines in \"PLdefstash\".\n\nvoid dumpall()\n\n\"dumpcbacktrace\"\nDumps the C backtrace to the given \"fp\".\n\nReturns true if a backtrace could be retrieved, false if not.\n\nbool dumpcbacktrace(PerlIO *fp, int maxdepth, int skip)\n\n\"dumpeval\"\nDescribed in perlguts.\n\nvoid dumpeval()\n\n\"dumpform\"\nDumps the contents of the format contained in the GV \"gv\" to \"STDERR\", or a message that\none doesn't exist.\n\nvoid dumpform(const GV *gv)\n\n\"dumppacksubs\"\nDumps the optrees for all visible subroutines in \"stash\".\n\nvoid dumppacksubs(const HV *stash)\n\n\"dumpsub\"\nDescribed in perlguts.\n\nvoid dumpsub(const GV *gv)\n\n\"getcbacktracedump\"\nReturns a SV containing a dump of \"depth\" frames of the call stack, skipping the \"skip\"\ninnermost ones. \"depth\" of 20 is usually enough.\n\nThe appended output looks like:\n\n...\n1 10e004812:0082 Perlcroak util.c:1716 /usr/bin/perl\n2 10df8d6d2:1d72 perlparse perl.c:3975 /usr/bin/perl\n...\n\nThe fields are tab-separated. The first column is the depth (zero being the innermost\nnon-skipped frame). In the hex:offset, the hex is where the program counter was in\n\"Sparsebody\", and the :offset (might be missing) tells how much inside the\n\"Sparsebody\" the program counter was.\n\nThe \"util.c:1716\" is the source code file and line number.\n\nThe /usr/bin/perl is obvious (hopefully).\n\nUnknowns are \"-\". Unknowns can happen unfortunately quite easily: if the platform\ndoesn't support retrieving the information; if the binary is missing the debug\ninformation; if the optimizer has transformed the code by for example inlining.\n\nSV * getcbacktracedump(int maxdepth, int skip)\n\n\"gvdump\"\nDump the name and, if they differ, the effective name of the GV \"gv\" to \"STDERR\".\n\nvoid gvdump(GV *gv)\n\n\"HASBACKTRACE\"\nThis symbol, if defined, indicates that the backtrace() routine is available to get a\nstack trace. The execinfo.h header must be included to use this routine.\n\n\"hvdump\"\nDumps the contents of an HV to the \"STDERR\" filehandle. Similar to using Devel::Peek on\nan hashref but does not expect an RV wrapper. Dumps contents to a depth of 3 levels deep.\n\nvoid hvdump(HV *hv)\n\n\"magicdump\"\nDumps the contents of the MAGIC \"mg\" to \"STDERR\".\n\nvoid magicdump(const MAGIC *mg)\n\n\"opclass\"\nGiven an op, determine what type of struct it has been allocated as. Returns one of the\nOPclass enums, such as OPclassLISTOP.\n\nOPclass opclass(const OP *o)\n\n\"opdump\"\nDumps the optree starting at OP \"o\" to \"STDERR\".\n\nvoid opdump(const OP *o)\n\n\"PLop\"\nDescribed in perlhacktips.\n\n\"PLrunops\"\nDescribed in perlguts.\n\n\"PLsvserial\"\nDescribed in perlhacktips.\n\n\"pmopdump\"\nDump an OP that is related to Pattern Matching, such as \"s/foo/bar/\"; these require\nspecial handling.\n\nvoid pmopdump(PMOP *pm)\n\n\"svdump\"\nDumps the contents of an SV to the \"STDERR\" filehandle.\n\nFor an example of its output, see Devel::Peek. If the item is an SvROK it will dump items\nto a depth of 4, otherwise it will dump only the top level item, which means that it will\nnot dump the contents of an AV * or HV *. For that use avdump() or hvdump().\n\nvoid svdump(SV *sv)\n\n\"svdumpdepth\"\nDumps the contents of an SV to the \"STDERR\" filehandle to the depth requested. This\nfunction can be used on any SV derived type (GV, HV, AV) with an appropriate cast. This\nis a more flexible variant of svdump(). For example\n\nHV *hv = ...;\nsvdumpdepth((SV*)hv, 2);\n\nwould dump the hv, its keys and values, but would not recurse into any RV values.\n\nvoid svdumpdepth(SV *sv, I32 depth)\n\n\"vdeb\"\nThis is like \"deb\", but \"args\" are an encapsulated argument list.\n\nvoid vdeb(const char *pat, valist *args)\n", "subsections": [] }, "Display functions": { "content": "\"form\"\n\"formnocontext\"\nThese take a sprintf-style format pattern and conventional (non-SV) arguments and return\nthe formatted string.\n\n(char *) Perlform(pTHX const char* pat, ...)\n\ncan be used any place a string (char *) is required:\n\nchar * s = Perlform(\"%d.%d\",major,minor);\n\nThey use a single (per-thread) private buffer so if you want to format several strings\nyou must explicitly copy the earlier strings away (and free the copies when you are\ndone).\n\nThe two forms differ only in that \"formnocontext\" does not take a thread context\n(\"aTHX\") parameter, so is used in situations where the caller doesn't already have the\nthread context.\n\nNOTE: \"form\" must be explicitly called as \"Perlform\" with an \"aTHX\" parameter.\n\nchar * Perlform (pTHX const char *pat, ...)\nchar * formnocontext(const char *pat, ...)\n\n\"mess\"\n\"messnocontext\"\nThese take a sprintf-style format pattern and argument list, which are used to generate a\nstring message. If the message does not end with a newline, then it will be extended\nwith some indication of the current location in the code, as described for \"messsv\".\n\nNormally, the resulting message is returned in a new mortal SV. But during global\ndestruction a single SV may be shared between uses of this function.\n\nThe two forms differ only in that \"messnocontext\" does not take a thread context\n(\"aTHX\") parameter, so is used in situations where the caller doesn't already have the\nthread context.\n\nNOTE: \"mess\" must be explicitly called as \"Perlmess\" with an \"aTHX\" parameter.\n\nSV * Perlmess (pTHX const char *pat, ...)\nSV * messnocontext(const char *pat, ...)\n\n\"messsv\"\nExpands a message, intended for the user, to include an indication of the current\nlocation in the code, if the message does not already appear to be complete.\n\n\"basemsg\" is the initial message or object. If it is a reference, it will be used as-is\nand will be the result of this function. Otherwise it is used as a string, and if it\nalready ends with a newline, it is taken to be complete, and the result of this function\nwill be the same string. If the message does not end with a newline, then a segment such\nas \"at foo.pl line 37\" will be appended, and possibly other clauses indicating the\ncurrent state of execution. The resulting message will end with a dot and a newline.\n\nNormally, the resulting message is returned in a new mortal SV. During global\ndestruction a single SV may be shared between uses of this function. If \"consume\" is\ntrue, then the function is permitted (but not required) to modify and return \"basemsg\"\ninstead of allocating a new SV.\n\nSV * messsv(SV *basemsg, bool consume)\n\n\"pvdisplay\"\nSimilar to\n\npvescape(dsv,pv,cur,pvlim,PERLPVESCAPEQUOTE);\n\nexcept that an additional \"\\0\" will be appended to the string when len > cur and pv[cur]\nis \"\\0\".\n\nNote that the final string may be up to 7 chars longer than pvlim.\n\nchar * pvdisplay(SV *dsv, const char *pv, STRLEN cur,\nSTRLEN len, STRLEN pvlim)\n\n\"pvescape\"\nEscapes at most the first \"count\" chars of \"pv\" and puts the results into \"dsv\" such that\nthe size of the escaped string will not exceed \"max\" chars and will not contain any\nincomplete escape sequences. The number of bytes escaped will be returned in the \"STRLEN\n*escaped\" parameter if it is not null. When the \"dsv\" parameter is null no escaping\nactually occurs, but the number of bytes that would be escaped were it not null will be\ncalculated.\n\nIf flags contains \"PERLPVESCAPEQUOTE\" then any double quotes in the string will also\nbe escaped.\n\nNormally the SV will be cleared before the escaped string is prepared, but when\n\"PERLPVESCAPENOCLEAR\" is set this will not occur.\n\nIf \"PERLPVESCAPEUNI\" is set then the input string is treated as UTF-8. If\n\"PERLPVESCAPEUNIDETECT\" is set then the input string is scanned using\nisutf8string() to determine if it is UTF-8.\n\nIf \"PERLPVESCAPEALL\" is set then all input chars will be output using \"\\x01F1\" style\nescapes, otherwise if \"PERLPVESCAPENONASCII\" is set, only non-ASCII chars will be\nescaped using this style; otherwise, only chars above 255 will be so escaped; other non\nprintable chars will use octal or common escaped patterns like \"\\n\". Otherwise, if\n\"PERLPVESCAPENOBACKSLASH\" then all chars below 255 will be treated as printable and\nwill be output as literals. The \"PERLPVESCAPENONWC\" modifies the previous rules to\ncause word chars, unicode or otherwise, to be output as literals, note this uses the\n*unicode* rules for deciding on word characters.\n\nIf \"PERLPVESCAPEFIRSTCHAR\" is set then only the first char of the string will be\nescaped, regardless of max. If the output is to be in hex, then it will be returned as a\nplain hex sequence. Thus the output will either be a single char, an octal escape\nsequence, a special escape like \"\\n\" or a hex value.\n\nIf \"PERLPVESCAPERE\" is set then the escape char used will be a \"%\" and not a \"\\\\\".\nThis is because regexes very often contain backslashed sequences, whereas \"%\" is not a\nparticularly common character in patterns.\n\nReturns a pointer to the escaped text as held by \"dsv\".\n\nchar * pvescape(SV *dsv, char const * const str,\nconst STRLEN count, STRLEN max,\nSTRLEN * const escaped, U32 flags)\n\n\"pvpretty\"\nConverts a string into something presentable, handling escaping via pvescape() and\nsupporting quoting and ellipses.\n\nIf the \"PERLPVPRETTYQUOTE\" flag is set then the result will be double quoted with any\ndouble quotes in the string escaped. Otherwise if the \"PERLPVPRETTYLTGT\" flag is set\nthen the result be wrapped in angle brackets.\n\nIf the \"PERLPVPRETTYELLIPSES\" flag is set and not all characters in string were output\nthen an ellipsis \"...\" will be appended to the string. Note that this happens AFTER it\nhas been quoted.\n\nIf \"startcolor\" is non-null then it will be inserted after the opening quote (if there\nis one) but before the escaped text. If \"endcolor\" is non-null then it will be inserted\nafter the escaped text but before any quotes or ellipses.\n\nReturns a pointer to the prettified text as held by \"dsv\".\n\nchar * pvpretty(SV *dsv, char const * const str,\nconst STRLEN count, const STRLEN max,\nchar const * const startcolor,\nchar const * const endcolor, const U32 flags)\n\n\"vform\"\nLike \"form\" but but the arguments are an encapsulated argument list.\n\nchar * vform(const char *pat, valist *args)\n\n\"vmess\"\n\"pat\" and \"args\" are a sprintf-style format pattern and encapsulated argument list,\nrespectively. These are used to generate a string message. If the message does not end\nwith a newline, then it will be extended with some indication of the current location in\nthe code, as described for \"messsv\".\n\nNormally, the resulting message is returned in a new mortal SV. During global\ndestruction a single SV may be shared between uses of this function.\n\nSV * vmess(const char *pat, valist *args)\n", "subsections": [] }, "Embedding, Threads, and Interpreter Cloning": { "content": "\"callatexit\"\nAdd a function \"fn\" to the list of functions to be called at global destruction. \"ptr\"\nwill be passed as an argument to \"fn\"; it can point to a \"struct\" so that you can pass\nanything you want.\n\nNote that under threads, \"fn\" may run multiple times. This is because the list is\nexecuted each time the current or any descendent thread terminates.\n\nvoid callatexit(ATEXITt fn, void *ptr)\n\n\"cvclone\"\nClone a CV, making a lexical closure. \"proto\" supplies the prototype of the function:\nits code, pad structure, and other attributes. The prototype is combined with a capture\nof outer lexicals to which the code refers, which are taken from the currently-executing\ninstance of the immediately surrounding code.\n\nCV * cvclone(CV *proto)\n\n\"cvname\"\nReturns an SV containing the name of the CV, mainly for use in error reporting. The CV\nmay actually be a GV instead, in which case the returned SV holds the GV's name.\nAnything other than a GV or CV is treated as a string already holding the sub name, but\nthis could change in the future.\n\nAn SV may be passed as a second argument. If so, the name will be assigned to it and it\nwill be returned. Otherwise the returned SV will be a new mortal.\n\nIf \"flags\" has the \"CVNAMENOTQUAL\" bit set, then the package name will not be included.\nIf the first argument is neither a CV nor a GV, this flag is ignored (subject to change).\n\nSV * cvname(CV *cv, SV *sv, U32 flags)\n\n\"cvundef\"\nClear out all the active components of a CV. This can happen either by an explicit\n\"undef &foo\", or by the reference count going to zero. In the former case, we keep the\n\"CvOUTSIDE\" pointer, so that any anonymous children can still follow the full lexical\nscope chain.\n\nvoid cvundef(CV *cv)\n\n\"findrundefsv\"\nReturns the global variable $.\n\nSV * findrundefsv()\n\n\"getopdescs\"\n\"DEPRECATED!\" It is planned to remove \"getopdescs\" from a future release of Perl. Do\nnot use it for new code; remove it from existing code.\n\nReturn a pointer to the array of all the descriptions of the various OPs Given an opcode\nfrom the enum in opcodes.h, \"PLopdesc[opcode]\" returns a pointer to a C language string\ngiving its description.\n\nchar getopdescs()\n\n\"getopnames\"\n\"DEPRECATED!\" It is planned to remove \"getopnames\" from a future release of Perl. Do\nnot use it for new code; remove it from existing code.\n\nReturn a pointer to the array of all the names of the various OPs Given an opcode from\nthe enum in opcodes.h, \"PLopname[opcode]\" returns a pointer to a C language string\ngiving its name.\n\nchar getopnames()\n\n\"HASSKIPLOCALEINIT\"\nDescribed in perlembed.\n\n\"intromy\"\n\"Introduce\" \"my\" variables to visible status. This is called during parsing at the end\nof each statement to make lexical variables visible to subsequent statements.\n\nU32 intromy()\n\n\"loadmodule\"\n\"loadmodulenocontext\"\nThese load the module whose name is pointed to by the string part of \"name\". Note that\nthe actual module name, not its filename, should be given. Eg, \"Foo::Bar\" instead of\n\"Foo/Bar.pm\". ver, if specified and not NULL, provides version semantics similar to \"use\nFoo::Bar VERSION\". The optional trailing arguments can be used to specify arguments to\nthe module's import() method, similar to \"use Foo::Bar VERSION LIST\"; their precise\nhandling depends on the flags. The flags argument is a bitwise-ORed collection of any of\n\"PERLLOADMODDENY\", \"PERLLOADMODNOIMPORT\", or \"PERLLOADMODIMPORTOPS\" (or 0 for no\nflags).\n\nIf \"PERLLOADMODNOIMPORT\" is set, the module is loaded as if with an empty import list,\nas in \"use Foo::Bar ()\"; this is the only circumstance in which the trailing optional\narguments may be omitted entirely. Otherwise, if \"PERLLOADMODIMPORTOPS\" is set, the\ntrailing arguments must consist of exactly one \"OP*\", containing the op tree that\nproduces the relevant import arguments. Otherwise, the trailing arguments must all be\n\"SV*\" values that will be used as import arguments; and the list must be terminated with\n\"(SV*) NULL\". If neither \"PERLLOADMODNOIMPORT\" nor \"PERLLOADMODIMPORTOPS\" is set,\nthe trailing \"NULL\" pointer is needed even if no import arguments are desired. The\nreference count for each specified \"SV*\" argument is decremented. In addition, the \"name\"\nargument is modified.\n\nIf \"PERLLOADMODDENY\" is set, the module is loaded as if with \"no\" rather than \"use\".\n\n\"loadmodule\" and \"loadmodulenocontext\" have the same apparent signature, but the\nformer hides the fact that it is accessing a thread context parameter. So use the latter\nwhen you get a compilation error about \"pTHX\".\n\nvoid loadmodule (U32 flags, SV *name, SV *ver, ...)\nvoid loadmodulenocontext(U32 flags, SV *name, SV *ver, ...)\n\n\"myexit\"\nA wrapper for the C library exit(3), honoring what \"PLexitflags\" in perlapi say to do.\n\nvoid myexit(U32 status)\n\n\"myfailureexit\"\nExit the running Perl process with an error.\n\nOn non-VMS platforms, this is essentially equivalent to \"\"myexit\"\", using \"errno\", but\nforces an en error code of 255 if \"errno\" is 0.\n\nOn VMS, it takes care to set the appropriate severity bits in the exit status.\n\nvoid myfailureexit()\n\n\"mystrlcat\"\nThe C library \"strlcat\" if available, or a Perl implementation of it. This operates on C\n\"NUL\"-terminated strings.\n\nmystrlcat() appends string \"src\" to the end of \"dst\". It will append at most\n\"size - strlen(dst) - 1\" characters. It will then \"NUL\"-terminate, unless \"size\" is 0 or\nthe original \"dst\" string was longer than \"size\" (in practice this should not happen as\nit means that either \"size\" is incorrect or that \"dst\" is not a proper \"NUL\"-terminated\nstring).\n\nNote that \"size\" is the full size of the destination buffer and the result is guaranteed\nto be \"NUL\"-terminated if there is room. Note that room for the \"NUL\" should be included\nin \"size\".\n\nThe return value is the total length that \"dst\" would have if \"size\" is sufficiently\nlarge. Thus it is the initial length of \"dst\" plus the length of \"src\". If \"size\" is\nsmaller than the return, the excess was not appended.\n\nSizet mystrlcat(char *dst, const char *src, Sizet size)\n\n\"mystrlcpy\"\nThe C library \"strlcpy\" if available, or a Perl implementation of it. This operates on C\n\"NUL\"-terminated strings.\n\nmystrlcpy() copies up to \"size - 1\" characters from the string \"src\" to \"dst\",\n\"NUL\"-terminating the result if \"size\" is not 0.\n\nThe return value is the total length \"src\" would be if the copy completely succeeded. If\nit is larger than \"size\", the excess was not copied.\n\nSizet mystrlcpy(char *dst, const char *src, Sizet size)\n\n\"newPADNAMELIST\"\nNOTE: \"newPADNAMELIST\" is experimental and may change or be removed without notice.\n\nCreates a new pad name list. \"max\" is the highest index for which space is allocated.\n\nPADNAMELIST * newPADNAMELIST(sizet max)\n\n\"newPADNAMEouter\"\nNOTE: \"newPADNAMEouter\" is experimental and may change or be removed without notice.\n\nConstructs and returns a new pad name. Only use this function for names that refer to\nouter lexicals. (See also \"newPADNAMEpvn\".) \"outer\" is the outer pad name that this one\nmirrors. The returned pad name has the \"PADNAMEfOUTER\" flag already set.\n\nPADNAME * newPADNAMEouter(PADNAME *outer)\n\n\"newPADNAMEpvn\"\nNOTE: \"newPADNAMEpvn\" is experimental and may change or be removed without notice.\n\nConstructs and returns a new pad name. \"s\" must be a UTF-8 string. Do not use this for\npad names that point to outer lexicals. See \"newPADNAMEouter\".\n\nPADNAME * newPADNAMEpvn(const char *s, STRLEN len)\n\n\"nothreadhook\"\nStub that provides thread hook for perldestruct when there are no threads.\n\nint nothreadhook()\n\n\"padaddanon\"\nAllocates a place in the currently-compiling pad (via \"padalloc\") for an anonymous\nfunction that is lexically scoped inside the currently-compiling function. The function\n\"func\" is linked into the pad, and its \"CvOUTSIDE\" link to the outer scope is weakened to\navoid a reference loop.\n\nOne reference count is stolen, so you may need to do SvREFCNTinc(func).\n\n\"optype\" should be an opcode indicating the type of operation that the pad entry is to\nsupport. This doesn't affect operational semantics, but is used for debugging.\n\nPADOFFSET padaddanon(CV *func, I32 optype)\n\n\"padaddnamepv\"\nExactly like \"padaddnamepvn\", but takes a nul-terminated string instead of a\nstring/length pair.\n\nPADOFFSET padaddnamepv(const char *name, const U32 flags,\nHV *typestash, HV *ourstash)\n\n\"padaddnamepvn\"\nAllocates a place in the currently-compiling pad for a named lexical variable. Stores\nthe name and other metadata in the name part of the pad, and makes preparations to manage\nthe variable's lexical scoping. Returns the offset of the allocated pad slot.\n\n\"namepv\"/\"namelen\" specify the variable's name, including leading sigil. If \"typestash\"\nis non-null, the name is for a typed lexical, and this identifies the type. If\n\"ourstash\" is non-null, it's a lexical reference to a package variable, and this\nidentifies the package. The following flags can be OR'ed together:\n\npadaddOUR redundantly specifies if it's a package var\npadaddSTATE variable will retain value persistently\npadaddNODUPCHECK skip check for lexical shadowing\npadaddFIELD specifies that the lexical is a field for a class\n\nPADOFFSET padaddnamepvn(const char *namepv, STRLEN namelen,\nU32 flags, HV *typestash,\nHV *ourstash)\n\n\"padaddnamesv\"\nExactly like \"padaddnamepvn\", but takes the name string in the form of an SV instead\nof a string/length pair.\n\nPADOFFSET padaddnamesv(SV *name, U32 flags, HV *typestash,\nHV *ourstash)\n\n\"padalloc\"\nNOTE: \"padalloc\" is experimental and may change or be removed without notice.\n\nAllocates a place in the currently-compiling pad, returning the offset of the allocated\npad slot. No name is initially attached to the pad slot. \"tmptype\" is a set of flags\nindicating the kind of pad entry required, which will be set in the value SV for the\nallocated pad entry:\n\nSVsPADMY named lexical variable (\"my\", \"our\", \"state\")\nSVsPADTMP unnamed temporary store\nSVfREADONLY constant shared between recursion levels\n\n\"SVfREADONLY\" has been supported here only since perl 5.20. To work with earlier\nversions as well, use \"SVfREADONLY|SVsPADTMP\". \"SVfREADONLY\" does not cause the SV in\nthe pad slot to be marked read-only, but simply tells \"padalloc\" that it will be made\nread-only (by the caller), or at least should be treated as such.\n\n\"optype\" should be an opcode indicating the type of operation that the pad entry is to\nsupport. This doesn't affect operational semantics, but is used for debugging.\n\nPADOFFSET padalloc(I32 optype, U32 tmptype)\n\n\"padfindmypv\"\nExactly like \"padfindmypvn\", but takes a nul-terminated string instead of a\nstring/length pair.\n\nPADOFFSET padfindmypv(const char *name, U32 flags)\n\n\"padfindmypvn\"\nGiven the name of a lexical variable, find its position in the currently-compiling pad.\n\"namepv\"/\"namelen\" specify the variable's name, including leading sigil. \"flags\" is\nreserved and must be zero. If it is not in the current pad but appears in the pad of any\nlexically enclosing scope, then a pseudo-entry for it is added in the current pad.\nReturns the offset in the current pad, or \"NOTINPAD\" if no such lexical is in scope.\n\nPADOFFSET padfindmypvn(const char *namepv, STRLEN namelen,\nU32 flags)\n\n\"padfindmysv\"\nExactly like \"padfindmypvn\", but takes the name string in the form of an SV instead of\na string/length pair.\n\nPADOFFSET padfindmysv(SV *name, U32 flags)\n\n\"padnamelistfetch\"\nNOTE: \"padnamelistfetch\" is experimental and may change or be removed without notice.\n\nFetches the pad name from the given index.\n\nPADNAME * padnamelistfetch(PADNAMELIST *pnl, SSizet key)\n\n\"padnameliststore\"\nNOTE: \"padnameliststore\" is experimental and may change or be removed without notice.\n\nStores the pad name (which may be null) at the given index, freeing any existing pad name\nin that slot.\n\nPADNAME padnameliststore(PADNAMELIST *pnl, SSizet key,\nPADNAME *val)\n\n\"padtidy\"\nNOTE: \"padtidy\" is experimental and may change or be removed without notice.\n\nTidy up a pad at the end of compilation of the code to which it belongs. Jobs performed\nhere are: remove most stuff from the pads of anonsub prototypes; give it a @; mark\ntemporaries as such. \"type\" indicates the kind of subroutine:\n\npadtidySUB ordinary subroutine\npadtidySUBCLONE prototype for lexical closure\npadtidyFORMAT format\n\nvoid padtidy(padtidytype type)\n\n\"perlalloc\"\nAllocates a new Perl interpreter. See perlembed.\n\nPerlInterpreter * perlalloc()\n\n\"PERLASYNCCHECK\"\nDescribed in perlinterp.\n\nvoid PERLASYNCCHECK()\n\n\"perlclone\"\nCreate and return a new interpreter by cloning the current one.\n\n\"perlclone\" takes these flags as parameters:\n\n\"CLONEfCOPYSTACKS\" - is used to, well, copy the stacks also, without it we only clone\nthe data and zero the stacks, with it we copy the stacks and the new perl interpreter is\nready to run at the exact same point as the previous one. The pseudo-fork code uses\n\"COPYSTACKS\" while the threads->create doesn't.\n\n\"CLONEfKEEPPTRTABLE\" - \"perlclone\" keeps a ptrtable with the pointer of the old\nvariable as a key and the new variable as a value, this allows it to check if something\nhas been cloned and not clone it again, but rather just use the value and increase the\nrefcount. If \"KEEPPTRTABLE\" is not set then \"perlclone\" will kill the ptrtable using\nthe function \"ptrtablefree(PLptrtable); PLptrtable = NULL;\". A reason to keep it\naround is if you want to dup some of your own variables which are outside the graph that\nperl scans.\n\n\"CLONEfCLONEHOST\" - This is a win32 thing, it is ignored on unix, it tells perl's\nwin32host code (which is c++) to clone itself, this is needed on win32 if you want to run\ntwo threads at the same time, if you just want to do some stuff in a separate perl\ninterpreter and then throw it away and return to the original one, you don't need to do\nanything.\n\nPerlInterpreter * perlclone(PerlInterpreter *protoperl,\nUV flags)\n\n\"perlconstruct\"\nInitializes a new Perl interpreter. See perlembed.\n\nvoid perlconstruct(PerlInterpreter *myperl)\n\n\"perldestruct\"\nShuts down a Perl interpreter. See perlembed for a tutorial.\n\n\"myperl\" points to the Perl interpreter. It must have been previously created through\nthe use of \"perlalloc\" and \"perlconstruct\". It may have been initialised through\n\"perlparse\", and may have been used through \"perlrun\" and other means. This function\nshould be called for any Perl interpreter that has been constructed with\n\"perlconstruct\", even if subsequent operations on it failed, for example if \"perlparse\"\nreturned a non-zero value.\n\nIf the interpreter's \"PLexitflags\" word has the \"PERLEXITDESTRUCTEND\" flag set, then\nthis function will execute code in \"END\" blocks before performing the rest of\ndestruction. If it is desired to make any use of the interpreter between \"perlparse\"\nand \"perldestruct\" other than just calling \"perlrun\", then this flag should be set\nearly on. This matters if \"perlrun\" will not be called, or if anything else will be\ndone in addition to calling \"perlrun\".\n\nReturns a value be a suitable value to pass to the C library function \"exit\" (or to\nreturn from \"main\"), to serve as an exit code indicating the nature of the way the\ninterpreter terminated. This takes into account any failure of \"perlparse\" and any\nearly exit from \"perlrun\". The exit code is of the type required by the host operating\nsystem, so because of differing exit code conventions it is not portable to interpret\nspecific numeric values as having specific meanings.\n\nint perldestruct(PerlInterpreter *myperl)\n\n\"perlfree\"\nReleases a Perl interpreter. See perlembed.\n\nvoid perlfree(PerlInterpreter *myperl)\n\n\"PERLGETCONTEXT\"\nDescribed in perlguts.\n\n\"PerlInterpreter\"\nDescribed in perlembed.\n\n\"perlparse\"\nTells a Perl interpreter to parse a Perl script. This performs most of the\ninitialisation of a Perl interpreter. See perlembed for a tutorial.\n\n\"myperl\" points to the Perl interpreter that is to parse the script. It must have been\npreviously created through the use of \"perlalloc\" and \"perlconstruct\". \"xsinit\" points\nto a callback function that will be called to set up the ability for this Perl\ninterpreter to load XS extensions, or may be null to perform no such setup.\n\n\"argc\" and \"argv\" supply a set of command-line arguments to the Perl interpreter, as\nwould normally be passed to the \"main\" function of a C program. \"argv[argc]\" must be\nnull. These arguments are where the script to parse is specified, either by naming a\nscript file or by providing a script in a \"-e\" option. If $0 will be written to in the\nPerl interpreter, then the argument strings must be in writable memory, and so mustn't\njust be string constants.\n\n\"env\" specifies a set of environment variables that will be used by this Perl\ninterpreter. If non-null, it must point to a null-terminated array of environment\nstrings. If null, the Perl interpreter will use the environment supplied by the\n\"environ\" global variable.\n\nThis function initialises the interpreter, and parses and compiles the script specified\nby the command-line arguments. This includes executing code in \"BEGIN\", \"UNITCHECK\", and\n\"CHECK\" blocks. It does not execute \"INIT\" blocks or the main program.\n\nReturns an integer of slightly tricky interpretation. The correct use of the return\nvalue is as a truth value indicating whether there was a failure in initialisation. If\nzero is returned, this indicates that initialisation was successful, and it is safe to\nproceed to call \"perlrun\" and make other use of it. If a non-zero value is returned,\nthis indicates some problem that means the interpreter wants to terminate. The\ninterpreter should not be just abandoned upon such failure; the caller should proceed to\nshut the interpreter down cleanly with \"perldestruct\" and free it with \"perlfree\".\n\nFor historical reasons, the non-zero return value also attempts to be a suitable value to\npass to the C library function \"exit\" (or to return from \"main\"), to serve as an exit\ncode indicating the nature of the way initialisation terminated. However, this isn't\nportable, due to differing exit code conventions. An attempt is made to return an exit\ncode of the type required by the host operating system, but because it is constrained to\nbe non-zero, it is not necessarily possible to indicate every type of exit. It is only\nreliable on Unix, where a zero exit code can be augmented with a set bit that will be\nignored. In any case, this function is not the correct place to acquire an exit code:\none should get that from \"perldestruct\".\n\nint perlparse(PerlInterpreter *myperl, XSINITt xsinit,\nint argc, char argv, char env)\n\n\"perlrun\"\nTells a Perl interpreter to run its main program. See perlembed for a tutorial.\n\n\"myperl\" points to the Perl interpreter. It must have been previously created through\nthe use of \"perlalloc\" and \"perlconstruct\", and initialised through \"perlparse\". This\nfunction should not be called if \"perlparse\" returned a non-zero value, indicating a\nfailure in initialisation or compilation.\n\nThis function executes code in \"INIT\" blocks, and then executes the main program. The\ncode to be executed is that established by the prior call to \"perlparse\". If the\ninterpreter's \"PLexitflags\" word does not have the \"PERLEXITDESTRUCTEND\" flag set,\nthen this function will also execute code in \"END\" blocks. If it is desired to make any\nfurther use of the interpreter after calling this function, then \"END\" blocks should be\npostponed to \"perldestruct\" time by setting that flag.\n\nReturns an integer of slightly tricky interpretation. The correct use of the return\nvalue is as a truth value indicating whether the program terminated non-locally. If zero\nis returned, this indicates that the program ran to completion, and it is safe to make\nother use of the interpreter (provided that the \"PERLEXITDESTRUCTEND\" flag was set as\ndescribed above). If a non-zero value is returned, this indicates that the interpreter\nwants to terminate early. The interpreter should not be just abandoned because of this\ndesire to terminate; the caller should proceed to shut the interpreter down cleanly with\n\"perldestruct\" and free it with \"perlfree\".\n\nFor historical reasons, the non-zero return value also attempts to be a suitable value to\npass to the C library function \"exit\" (or to return from \"main\"), to serve as an exit\ncode indicating the nature of the way the program terminated. However, this isn't\nportable, due to differing exit code conventions. An attempt is made to return an exit\ncode of the type required by the host operating system, but because it is constrained to\nbe non-zero, it is not necessarily possible to indicate every type of exit. It is only\nreliable on Unix, where a zero exit code can be augmented with a set bit that will be\nignored. In any case, this function is not the correct place to acquire an exit code:\none should get that from \"perldestruct\".\n\nint perlrun(PerlInterpreter *myperl)\n\n\"PERLSETCONTEXT\"\nDescribed in perlguts.\n\nvoid PERLSETCONTEXT(PerlInterpreter* i)\n\n\"PERLSYSINIT\"\n\"PERLSYSINIT3\"\nThese provide system-specific tune up of the C runtime environment necessary to run Perl\ninterpreters. Only one should be used, and it should be called only once, before\ncreating any Perl interpreters.\n\nThey differ in that \"PERLSYSINIT3\" also initializes \"env\".\n\nvoid PERLSYSINIT (int *argc, char* argv)\nvoid PERLSYSINIT3(int *argc, char* argv, char* env)\n\n\"PERLSYSTERM\"\nProvides system-specific clean up of the C runtime environment after running Perl\ninterpreters. This should be called only once, after freeing any remaining Perl\ninterpreters.\n\nvoid PERLSYSTERM()\n\n\"PLexitflags\"\nContains flags controlling perl's behaviour on exit():\n\n• \"PERLEXITDESTRUCTEND\"\n\nIf set, END blocks are executed when the interpreter is destroyed. This is normally\nset by perl itself after the interpreter is constructed.\n\n• \"PERLEXITABORT\"\n\nCall abort() on exit. This is used internally by perl itself to abort if exit is\ncalled while processing exit.\n\n• \"PERLEXITWARN\"\n\nWarn on exit.\n\n• \"PERLEXITEXPECTED\"\n\nSet by the \"exit\" in perlfunc operator.\n\nU8 PLexitflags\n\n\"PLorigalen\"\nDescribed in perlembed.\n\n\"PLperldestructlevel\"\nThis value may be set when embedding for full cleanup.\n\nPossible values:\n\n• 0 - none\n\n• 1 - full\n\n• 2 or greater - full with checks.\n\nIf $ENV{PERLDESTRUCTLEVEL} is set to an integer greater than the value of\n\"PLperldestructlevel\" its value is used instead.\n\nOn threaded perls, each thread has an independent copy of this variable; each initialized\nat creation time with the current value of the creating thread's copy.\n\nsigned char PLperldestructlevel\n\n\"ptrtablefetch\"\nLook for \"sv\" in the pointer-mapping table \"tbl\", returning its value, or NULL if not\nfound.\n\nvoid * ptrtablefetch(PTRTBLt * const tbl,\nconst void * const sv)\n\n\"ptrtablefree\"\nClear and free a ptr table\n\nvoid ptrtablefree(PTRTBLt * const tbl)\n\n\"ptrtablenew\"\nCreate a new pointer-mapping table\n\nPTRTBLt * ptrtablenew()\n\n\"ptrtablesplit\"\nDouble the hash bucket size of an existing ptr table\n\nvoid ptrtablesplit(PTRTBLt * const tbl)\n\n\"ptrtablestore\"\nAdd a new entry to a pointer-mapping table \"tbl\". In hash terms, \"oldsv\" is the key;\nCnewsv> is the value.\n\nThe names \"old\" and \"new\" are specific to the core's typical use of ptrtables in thread\ncloning.\n\nvoid ptrtablestore(PTRTBLt * const tbl,\nconst void * const oldsv,\nvoid * const newsv)\n\n\"requirepv\"\nTells Perl to \"require\" the file named by the string argument. It is analogous to the\nPerl code \"eval \"require '$file'\"\". It's even implemented that way; consider using\nloadmodule instead.\n\nNOTE: the perlrequirepv() form is deprecated.\n\nvoid requirepv(const char *pv)\n\n\"vloadmodule\"\nLike \"loadmodule\" but the arguments are an encapsulated argument list.\n\nvoid vloadmodule(U32 flags, SV *name, SV *ver, valist *args)\n", "subsections": [] }, "Errno": { "content": "\"svstringfromerrnum\"\nGenerates the message string describing an OS error and returns it as an SV. \"errnum\"\nmust be a value that \"errno\" could take, identifying the type of error.\n\nIf \"tgtsv\" is non-null then the string will be written into that SV (overwriting existing\ncontent) and it will be returned. If \"tgtsv\" is a null pointer then the string will be\nwritten into a new mortal SV which will be returned.\n\nThe message will be taken from whatever locale would be used by $!, and will be encoded\nin the SV in whatever manner would be used by $!. The details of this process are\nsubject to future change. Currently, the message is taken from the C locale by default\n(usually producing an English message), and from the currently selected locale when in\nthe scope of the \"use locale\" pragma. A heuristic attempt is made to decode the message\nfrom the locale's character encoding, but it will only be decoded as either UTF-8 or\nISO-8859-1. It is always correctly decoded in a UTF-8 locale, usually in an ISO-8859-1\nlocale, and never in any other locale.\n\nThe SV is always returned containing an actual string, and with no other OK bits set.\nUnlike $!, a message is even yielded for \"errnum\" zero (meaning success), and if no\nuseful message is available then a useless string (currently empty) is returned.\n\nSV * svstringfromerrnum(int errnum, SV *tgtsv)\n", "subsections": [] }, "Exception Handling (simple) Macros": { "content": "\"dXCPT\"\nSet up necessary local variables for exception handling. See \"Exception Handling\" in\nperlguts.\n\ndXCPT;\n\n\"JMPENVJUMP\"\nDescribed in perlinterp.\n\nvoid JMPENVJUMP(int v)\n\n\"JMPENVPUSH\"\nDescribed in perlinterp.\n\nvoid JMPENVPUSH(int v)\n\n\"PLrestartop\"\nDescribed in perlinterp.\n\n\"XCPTCATCH\"\nIntroduces a catch block. See \"Exception Handling\" in perlguts.\n\n\"XCPTRETHROW\"\nRethrows a previously caught exception. See \"Exception Handling\" in perlguts.\n\nXCPTRETHROW;\n\n\"XCPTTRYEND\"\nEnds a try block. See \"Exception Handling\" in perlguts.\n\n\"XCPTTRYSTART\"\nStarts a try block. See \"Exception Handling\" in perlguts.\n", "subsections": [] }, "Filesystem configuration values": { "content": "Also see \"List of capability HASfoo symbols\".\n\n\"DIRNAMLEN\"\nThis symbol, if defined, indicates to the C program that the length of directory entry\nnames is provided by a \"dnamlen\" field. Otherwise you need to do strlen() on the\n\"dname\" field.\n\n\"DOSUID\"\nThis symbol, if defined, indicates that the C program should check the script that it is\nexecuting for setuid/setgid bits, and attempt to emulate setuid/setgid on systems that\nhave disabled setuid #! scripts because the kernel can't do it securely. It is up to the\npackage designer to make sure that this emulation is done securely. Among other things,\nit should do an fstat on the script it just opened to make sure it really is a\nsetuid/setgid script, it should make sure the arguments passed correspond exactly to the\nargument on the #! line, and it should not trust any subprocesses to which it must pass\nthe filename rather than the file descriptor of the script to be executed.\n\n\"EOFNONBLOCK\"\nThis symbol, if defined, indicates to the C program that a read() on a non-blocking file\ndescriptor will return 0 on \"EOF\", and not the value held in \"RDNODATA\" (-1 usually, in\nthat case!).\n\n\"FCNTLCANLOCK\"\nThis symbol, if defined, indicates that fcntl() can be used for file locking. Normally\non Unix systems this is defined. It may be undefined on \"VMS\".\n\n\"FFLUSHALL\"\nThis symbol, if defined, tells that to flush all pending stdio output one must loop\nthrough all the stdio file handles stored in an array and fflush them. Note that if\n\"fflushNULL\" is defined, fflushall will not even be probed for and will be left\nundefined.\n\n\"FFLUSHNULL\"\nThis symbol, if defined, tells that fflush(NULL) correctly flushes all pending stdio\noutput without side effects. In particular, on some platforms calling fflush(NULL)\n*still* corrupts \"STDIN\" if it is a pipe.\n\n\"FILEbase\"\nThis macro is used to access the \"base\" field (or equivalent) of the \"FILE\" structure\npointed to by its argument. This macro will always be defined if \"USESTDIOBASE\" is\ndefined.\n\nvoid * FILEbase(FILE * f)\n\n\"FILEbufsiz\"\nThis macro is used to determine the number of bytes in the I/O buffer pointed to by\n\"base\" field (or equivalent) of the \"FILE\" structure pointed to its argument. This macro\nwill always be defined if \"USESTDIOBASE\" is defined.\n\nSizet FILEbufsiz(FILE *f)\n\n\"FILEcnt\"\nThis macro is used to access the \"cnt\" field (or equivalent) of the \"FILE\" structure\npointed to by its argument. This macro will always be defined if \"USESTDIOPTR\" is\ndefined.\n\nSizet FILEcnt(FILE * f)\n\n\"FILEptr\"\nThis macro is used to access the \"ptr\" field (or equivalent) of the \"FILE\" structure\npointed to by its argument. This macro will always be defined if \"USESTDIOPTR\" is\ndefined.\n\nvoid * FILEptr(FILE * f)\n\n\"FLEXFILENAMES\"\nThis symbol, if defined, indicates that the system supports filenames longer than 14\ncharacters.\n\n\"HASDIRDDFD\"\nThis symbol, if defined, indicates that the \"DIR\"* dirstream structure contains a member\nvariable named \"ddfd\".\n\n\"HASDUP2\"\nThis symbol, if defined, indicates that the \"dup2\" routine is available to duplicate file\ndescriptors.\n\n\"HASDUP3\"\nThis symbol, if defined, indicates that the \"dup3\" routine is available to duplicate file\ndescriptors.\n\n\"HASFASTSTDIO\"\nThis symbol, if defined, indicates that the \"fast stdio\" is available to manipulate the\nstdio buffers directly.\n\n\"HASFCHDIR\"\nThis symbol, if defined, indicates that the \"fchdir\" routine is available to change\ndirectory using a file descriptor.\n\n\"HASFCNTL\"\nThis symbol, if defined, indicates to the C program that the fcntl() function exists.\n\n\"HASFDCLOSE\"\nThis symbol, if defined, indicates that the \"fdclose\" routine is available to free a\n\"FILE\" structure without closing the underlying file descriptor. This function appeared\nin \"FreeBSD\" 10.2.\n\n\"HASFDOPENDIR\"\nThis symbol, if defined, indicates that the fdopendir() routine is available to open\ndirectories using an opened file descriptor already referring to that directory.\n\n\"HASFPATHCONF\"\nThis symbol, if defined, indicates that pathconf() is available to determine file-system\nrelated limits and options associated with a given open file descriptor.\n\n\"HASFPOS64T\"\nThis symbol will be defined if the C compiler supports \"fpos64t\".\n\n\"HASFSTATFS\"\nThis symbol, if defined, indicates that the \"fstatfs\" routine is available to stat\nfilesystems by file descriptors.\n\n\"HASFSTATVFS\"\nThis symbol, if defined, indicates that the \"fstatvfs\" routine is available to stat\nfilesystems by file descriptors.\n\n\"HASGETFSSTAT\"\nThis symbol, if defined, indicates that the \"getfsstat\" routine is available to stat\nfilesystems in bulk.\n\n\"HASGETMNT\"\nThis symbol, if defined, indicates that the \"getmnt\" routine is available to get\nfilesystem mount info by filename.\n\n\"HASGETMNTENT\"\nThis symbol, if defined, indicates that the \"getmntent\" routine is available to iterate\nthrough mounted file systems to get their info.\n\n\"HASHASMNTOPT\"\nThis symbol, if defined, indicates that the \"hasmntopt\" routine is available to query the\nmount options of file systems.\n\n\"HASLSEEKPROTO\"\nThis symbol, if defined, indicates that the system provides a prototype for the lseek()\nfunction. Otherwise, it is up to the program to supply one. A good guess is\n\nextern offt lseek(int, offt, int);\n\n\"HASMKDIR\"\nThis symbol, if defined, indicates that the \"mkdir\" routine is available to create\ndirectories. Otherwise you should fork off a new process to exec /bin/mkdir.\n\n\"HASOFF64T\"\nThis symbol will be defined if the C compiler supports \"off64t\".\n\n\"HASOPENAT\"\nThis symbol is defined if the openat() routine is available.\n\n\"HASOPEN3\"\nThis manifest constant lets the C program know that the three argument form of open(2) is\navailable.\n\n\"HASPOLL\"\nThis symbol, if defined, indicates that the \"poll\" routine is available to \"poll\" active\nfile descriptors. Please check \"IPOLL\" and \"ISYSPOLL\" to know which header should be\nincluded as well.\n\n\"HASREADDIR\"\nThis symbol, if defined, indicates that the \"readdir\" routine is available to read\ndirectory entries. You may have to include dirent.h. See \"IDIRENT\".\n\n\"HASREADDIR64R\"\nThis symbol, if defined, indicates that the \"readdir64r\" routine is available to\nreaddir64 re-entrantly.\n\n\"HASREWINDDIR\"\nThis symbol, if defined, indicates that the \"rewinddir\" routine is available. You may\nhave to include dirent.h. See \"IDIRENT\".\n\n\"HASRMDIR\"\nThis symbol, if defined, indicates that the \"rmdir\" routine is available to remove\ndirectories. Otherwise you should fork off a new process to exec /bin/rmdir.\n\n\"HASSEEKDIR\"\nThis symbol, if defined, indicates that the \"seekdir\" routine is available. You may have\nto include dirent.h. See \"IDIRENT\".\n\n\"HASSELECT\"\nThis symbol, if defined, indicates that the \"select\" routine is available to \"select\"\nactive file descriptors. If the timeout field is used, sys/time.h may need to be\nincluded.\n\n\"HASSETVBUF\"\nThis symbol, if defined, indicates that the \"setvbuf\" routine is available to change\nbuffering on an open stdio stream. to a line-buffered mode.\n\n\"HASSTDIOSTREAMARRAY\"\nThis symbol, if defined, tells that there is an array holding the stdio streams.\n\n\"HASSTRUCTFSDATA\"\nThis symbol, if defined, indicates that the \"struct fsdata\" to do statfs() is supported.\n\n\"HASSTRUCTSTATFS\"\nThis symbol, if defined, indicates that the \"struct statfs\" to do statfs() is supported.\n\n\"HASSTRUCTSTATFSFFLAGS\"\nThis symbol, if defined, indicates that the \"struct statfs\" does have the \"fflags\"\nmember containing the mount flags of the filesystem containing the file. This kind of\n\"struct statfs\" is coming from sys/mount.h (\"BSD\" 4.3), not from sys/statfs.h (\"SYSV\").\nOlder \"BSDs\" (like Ultrix) do not have statfs() and \"struct statfs\", they have ustat()\nand getmnt() with \"struct ustat\" and \"struct fsdata\".\n\n\"HASTELLDIR\"\nThis symbol, if defined, indicates that the \"telldir\" routine is available. You may have\nto include dirent.h. See \"IDIRENT\".\n\n\"HASUSTAT\"\nThis symbol, if defined, indicates that the \"ustat\" system call is available to query\nfile system statistics by \"devt\".\n\n\"IFCNTL\"\nThis manifest constant tells the C program to include fcntl.h.\n\n#ifdef IFCNTL\n#include \n#endif\n\n\"ISYSDIR\"\nThis symbol, if defined, indicates to the C program that it should include sys/dir.h.\n\n#ifdef ISYSDIR\n#include \n#endif\n\n\"ISYSFILE\"\nThis symbol, if defined, indicates to the C program that it should include sys/file.h to\nget definition of \"ROK\" and friends.\n\n#ifdef ISYSFILE\n#include \n#endif\n\n\"ISYSNDIR\"\nThis symbol, if defined, indicates to the C program that it should include sys/ndir.h.\n\n#ifdef ISYSNDIR\n#include \n#endif\n\n\"ISYSSTATFS\"\nThis symbol, if defined, indicates that sys/statfs.h exists.\n\n#ifdef ISYSSTATFS\n#include \n#endif\n\n\"LSEEKSIZE\"\nThis symbol holds the number of bytes used by the \"Offt\".\n\n\"RDNODATA\"\nThis symbol holds the return code from read() when no data is present on the non-blocking\nfile descriptor. Be careful! If \"EOFNONBLOCK\" is not defined, then you can't distinguish\nbetween no data and \"EOF\" by issuing a read(). You'll have to find another way to tell\nfor sure!\n\n\"READDIR64RPROTO\"\nThis symbol encodes the prototype of \"readdir64r\". It is zero if \"dreaddir64r\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dreaddir64r\" is\ndefined.\n\n\"STDCHAR\"\nThis symbol is defined to be the type of char used in stdio.h. It has the values\n\"unsigned char\" or \"char\".\n\n\"STDIOCNTLVALUE\"\nThis symbol is defined if the \"FILEcnt\" macro can be used as an lvalue.\n\n\"STDIOPTRLVALNOCHANGECNT\"\nThis symbol is defined if using the \"FILEptr\" macro as an lvalue to increase the pointer\nby n leaves Filecnt(fp) unchanged.\n\n\"STDIOPTRLVALSETSCNT\"\nThis symbol is defined if using the \"FILEptr\" macro as an lvalue to increase the pointer\nby n has the side effect of decreasing the value of Filecnt(fp) by n.\n\n\"STDIOPTRLVALUE\"\nThis symbol is defined if the \"FILEptr\" macro can be used as an lvalue.\n\n\"STDIOSTREAMARRAY\"\nThis symbol tells the name of the array holding the stdio streams. Usual values include\n\"iob\", \"iob\", and \"sF\".\n\n\"STINOSIGN\"\nThis symbol holds the signedness of \"struct stat\"'s \"stino\". 1 for unsigned, -1 for\nsigned.\n\n\"STINOSIZE\"\nThis variable contains the size of \"struct stat\"'s \"stino\" in bytes.\n\n\"VALEAGAIN\"\nThis symbol holds the errno error code set by read() when no data was present on the non-\nblocking file descriptor.\n\n\"VALONONBLOCK\"\nThis symbol is to be used during open() or fcntl(FSETFL) to turn on non-blocking I/O for\nthe file descriptor. Note that there is no way back, i.e. you cannot turn it blocking\nagain this way. If you wish to alternatively switch between blocking and non-blocking,\nuse the ioctl(FIOSNBIO) call instead, but that is not supported by all devices.\n\n\"VOIDCLOSEDIR\"\nThis symbol, if defined, indicates that the closedir() routine does not return a value.\n", "subsections": [] }, "Floating point": { "content": "Also \"List of capability HASfoo symbols\" lists capabilities that arent in this section. For\nexample \"HASASINH\", for the hyperbolic sine function.\n\n\"CASTFLAGS\"\nThis symbol contains flags that say what difficulties the compiler has casting odd\nfloating values to unsigned long:\n\n0 = ok\n1 = couldn't cast < 0\n2 = couldn't cast >= 0x80000000\n4 = couldn't cast in argument expression list\n\n\"CASTNEGFLOAT\"\nThis symbol is defined if the C compiler can cast negative numbers to unsigned longs,\nints and shorts.\n\n\"DOUBLEHASINF\"\nThis symbol, if defined, indicates that the double has the infinity.\n\n\"DOUBLEHASNAN\"\nThis symbol, if defined, indicates that the double has the not-a-number.\n\n\"DOUBLEHASNEGATIVEZERO\"\nThis symbol, if defined, indicates that the double has the \"negativezero\".\n\n\"DOUBLEHASSUBNORMALS\"\nThis symbol, if defined, indicates that the double has the subnormals (denormals).\n\n\"DOUBLEINFBYTES\"\nThis symbol, if defined, is a comma-separated list of hexadecimal bytes for the double\nprecision infinity.\n\n\"DOUBLEKIND\"\n\"DOUBLEKIND\" will be one of \"DOUBLEISIEEE75432BITLITTLEENDIAN\"\n\"DOUBLEISIEEE75432BITBIGENDIAN\" \"DOUBLEISIEEE75464BITLITTLEENDIAN\"\n\"DOUBLEISIEEE75464BITBIGENDIAN\" \"DOUBLEISIEEE754128BITLITTLEENDIAN\"\n\"DOUBLEISIEEE754128BITBIGENDIAN\" \"DOUBLEISIEEE75464BITMIXEDENDIANLEBE\"\n\"DOUBLEISIEEE75464BITMIXEDENDIANBELE\" \"DOUBLEISVAXFFLOAT\"\n\"DOUBLEISVAXDFLOAT\" \"DOUBLEISVAXGFLOAT\" \"DOUBLEISIBMSINGLE32BIT\"\n\"DOUBLEISIBMDOUBLE64BIT\" \"DOUBLEISCRAYSINGLE64BIT\" \"DOUBLEISUNKNOWNFORMAT\"\n\n\"DOUBLEMANTBITS\"\nThis symbol, if defined, tells how many mantissa bits there are in double precision\nfloating point format. Note that this is usually \"DBLMANTDIG\" minus one, since with\nthe standard \"IEEE\" 754 formats \"DBLMANTDIG\" includes the implicit bit, which doesn't\nreally exist.\n\n\"DOUBLENANBYTES\"\nThis symbol, if defined, is a comma-separated list of hexadecimal bytes (0xHH) for the\ndouble precision not-a-number.\n\n\"DOUBLESIZE\"\nThis symbol contains the size of a double, so that the C preprocessor can make decisions\nbased on it.\n\n\"DOUBLESTYLECRAY\"\nThis symbol, if defined, indicates that the double is the 64-bit \"CRAY\" mainframe format.\n\n\"DOUBLESTYLEIBM\"\nThis symbol, if defined, indicates that the double is the 64-bit \"IBM\" mainframe format.\n\n\"DOUBLESTYLEIEEE\"\nThis symbol, if defined, indicates that the double is the 64-bit \"IEEE\" 754.\n\n\"DOUBLESTYLEVAX\"\nThis symbol, if defined, indicates that the double is the 64-bit \"VAX\" format D or G.\n\n\"HASATOLF\"\nThis symbol, if defined, indicates that the \"atolf\" routine is available to convert\nstrings into long doubles.\n\n\"HASCLASS\"\nThis symbol, if defined, indicates that the \"class\" routine is available to classify\ndoubles. Available for example in \"AIX\". The returned values are defined in float.h and\nare:\n\nFPPLUSNORM Positive normalized, nonzero\nFPMINUSNORM Negative normalized, nonzero\nFPPLUSDENORM Positive denormalized, nonzero\nFPMINUSDENORM Negative denormalized, nonzero\nFPPLUSZERO +0.0\nFPMINUSZERO -0.0\nFPPLUSINF +INF\nFPMINUSINF -INF\nFPNANS Signaling Not a Number (NaNS)\nFPNANQ Quiet Not a Number (NaNQ)\n\n\"HASFINITE\"\nThis symbol, if defined, indicates that the \"finite\" routine is available to check\nwhether a double is \"finite\" (non-infinity non-NaN).\n\n\"HASFINITEL\"\nThis symbol, if defined, indicates that the \"finitel\" routine is available to check\nwhether a long double is finite (non-infinity non-NaN).\n\n\"HASFPCLASS\"\nThis symbol, if defined, indicates that the \"fpclass\" routine is available to classify\ndoubles. Available for example in Solaris/\"SVR4\". The returned values are defined in\nieeefp.h and are:\n\nFPSNAN signaling NaN\nFPQNAN quiet NaN\nFPNINF negative infinity\nFPPINF positive infinity\nFPNDENORM negative denormalized non-zero\nFPPDENORM positive denormalized non-zero\nFPNZERO negative zero\nFPPZERO positive zero\nFPNNORM negative normalized non-zero\nFPPNORM positive normalized non-zero\n\n\"HASFPCLASS\"\nThis symbol, if defined, indicates that the \"fpclass\" routine is available to classify\ndoubles. Available for example in Digital \"UNIX\". The returned values are defined in\nmath.h and are:\n\nFPSNAN Signaling NaN (Not-a-Number)\nFPQNAN Quiet NaN (Not-a-Number)\nFPPOSINF +infinity\nFPNEGINF -infinity\nFPPOSNORM Positive normalized\nFPNEGNORM Negative normalized\nFPPOSDENORM Positive denormalized\nFPNEGDENORM Negative denormalized\nFPPOSZERO +0.0 (positive zero)\nFPNEGZERO -0.0 (negative zero)\n\n\"HASFPCLASSIFY\"\nThis symbol, if defined, indicates that the \"fpclassify\" routine is available to classify\ndoubles. Available for example in HP-UX. The returned values are defined in math.h and\nare\n\nFPNORMAL Normalized\nFPZERO Zero\nFPINFINITE Infinity\nFPSUBNORMAL Denormalized\nFPNAN NaN\n\n\"HASFPCLASSIFY\"\nThis symbol, if defined, indicates that the \"fpclassify\" routine is available to\nclassify doubles. The values are defined in math.h\n\nFPNORMAL Normalized\nFPZERO Zero\nFPINFINITE Infinity\nFPSUBNORMAL Denormalized\nFPNAN NaN\n\n\"HASFPCLASSL\"\nThis symbol, if defined, indicates that the \"fpclassl\" routine is available to classify\nlong doubles. Available for example in \"IRIX\". The returned values are defined in\nieeefp.h and are:\n\nFPSNAN signaling NaN\nFPQNAN quiet NaN\nFPNINF negative infinity\nFPPINF positive infinity\nFPNDENORM negative denormalized non-zero\nFPPDENORM positive denormalized non-zero\nFPNZERO negative zero\nFPPZERO positive zero\nFPNNORM negative normalized non-zero\nFPPNORM positive normalized non-zero\n\n\"HASFPCLASSL\"\nThis symbol, if defined, indicates that the \"fpclassl\" routine is available to classify\nlong doubles. Available for example in Digital \"UNIX\". See for possible values\n\"HASFPCLASS\".\n\n\"HASFPGETROUND\"\nThis symbol, if defined, indicates that the \"fpgetround\" routine is available to get the\nfloating point rounding mode.\n\n\"HASFREXPL\"\nThis symbol, if defined, indicates that the \"frexpl\" routine is available to break a long\ndouble floating-point number into a normalized fraction and an integral power of 2.\n\n\"HASILOGB\"\nThis symbol, if defined, indicates that the \"ilogb\" routine is available to get integer\nexponent of a floating-point value.\n\n\"HASISFINITE\"\nThis symbol, if defined, indicates that the \"isfinite\" routine is available to check\nwhether a double is finite (non-infinity non-NaN).\n\n\"HASISFINITEL\"\nThis symbol, if defined, indicates that the \"isfinitel\" routine is available to check\nwhether a long double is finite. (non-infinity non-NaN).\n\n\"HASISINF\"\nThis symbol, if defined, indicates that the \"isinf\" routine is available to check whether\na double is an infinity.\n\n\"HASISINFL\"\nThis symbol, if defined, indicates that the \"isinfl\" routine is available to check\nwhether a long double is an infinity.\n\n\"HASISNAN\"\nThis symbol, if defined, indicates that the \"isnan\" routine is available to check whether\na double is a NaN.\n\n\"HASISNANL\"\nThis symbol, if defined, indicates that the \"isnanl\" routine is available to check\nwhether a long double is a NaN.\n\n\"HASISNORMAL\"\nThis symbol, if defined, indicates that the \"isnormal\" routine is available to check\nwhether a double is normal (non-zero normalized).\n\n\"HASJ0L\"\nThis symbol, if defined, indicates to the C program that the j0l() function is available\nfor Bessel functions of the first kind of the order zero, for long doubles.\n\n\"HASJ0\"\nThis symbol, if defined, indicates to the C program that the j0() function is available\nfor Bessel functions of the first kind of the order zero, for doubles.\n\n\"HASLDBLDIG\"\nThis symbol, if defined, indicates that this system's float.h or limits.h defines the\nsymbol \"LDBLDIG\", which is the number of significant digits in a long double precision\nnumber. Unlike for \"DBLDIG\", there's no good guess for \"LDBLDIG\" if it is undefined.\n\n\"HASLDEXPL\"\nThis symbol, if defined, indicates that the \"ldexpl\" routine is available to shift a long\ndouble floating-point number by an integral power of 2.\n\n\"HASLLRINT\"\nThis symbol, if defined, indicates that the \"llrint\" routine is available to return the\nlong long value closest to a double (according to the current rounding mode).\n\n\"HASLLRINTL\"\nThis symbol, if defined, indicates that the \"llrintl\" routine is available to return the\nlong long value closest to a long double (according to the current rounding mode).\n\n\"HASLLROUNDL\"\nThis symbol, if defined, indicates that the \"llroundl\" routine is available to return the\nnearest long long value away from zero of the long double argument value.\n\n\"HASLONGDOUBLE\"\nThis symbol will be defined if the C compiler supports long doubles.\n\n\"HASLRINT\"\nThis symbol, if defined, indicates that the \"lrint\" routine is available to return the\nintegral value closest to a double (according to the current rounding mode).\n\n\"HASLRINTL\"\nThis symbol, if defined, indicates that the \"lrintl\" routine is available to return the\nintegral value closest to a long double (according to the current rounding mode).\n\n\"HASLROUNDL\"\nThis symbol, if defined, indicates that the \"lroundl\" routine is available to return the\nnearest integral value away from zero of the long double argument value.\n\n\"HASMODFL\"\nThis symbol, if defined, indicates that the \"modfl\" routine is available to split a long\ndouble x into a fractional part f and an integer part i such that |f| < 1.0 and (f + i) =\nx.\n\n\"HASNAN\"\nThis symbol, if defined, indicates that the \"nan\" routine is available to generate NaN.\n\n\"HASNEXTTOWARD\"\nThis symbol, if defined, indicates that the \"nexttoward\" routine is available to return\nthe next machine representable long double from x in direction y.\n\n\"HASREMAINDER\"\nThis symbol, if defined, indicates that the \"remainder\" routine is available to return\nthe floating-point \"remainder\".\n\n\"HASSCALBN\"\nThis symbol, if defined, indicates that the \"scalbn\" routine is available to multiply\nfloating-point number by integral power of radix.\n\n\"HASSIGNBIT\"\nThis symbol, if defined, indicates that the \"signbit\" routine is available to check if\nthe given number has the sign bit set. This should include correct testing of -0.0.\nThis will only be set if the signbit() routine is safe to use with the NV type used\ninternally in perl. Users should call Perlsignbit(), which will be #defined to the\nsystem's signbit() function or macro if this symbol is defined.\n\n\"HASSQRTL\"\nThis symbol, if defined, indicates that the \"sqrtl\" routine is available to do long\ndouble square roots.\n\n\"HASSTRTODL\"\nThis symbol, if defined, indicates that the \"strtodl\" routine is available to convert\nstrings to long doubles.\n\n\"HASSTRTOLD\"\nThis symbol, if defined, indicates that the \"strtold\" routine is available to convert\nstrings to long doubles.\n\n\"HASSTRTOLDL\"\nThis symbol, if defined, indicates that the \"strtoldl\" routine is available to convert\nstrings to long doubles.\n\n\"HASTRUNC\"\nThis symbol, if defined, indicates that the \"trunc\" routine is available to round doubles\ntowards zero.\n\n\"HASUNORDERED\"\nThis symbol, if defined, indicates that the \"unordered\" routine is available to check\nwhether two doubles are \"unordered\" (effectively: whether either of them is NaN)\n\n\"IFENV\"\nThis symbol, if defined, indicates to the C program that it should include fenv.h to get\nthe floating point environment definitions.\n\n#ifdef IFENV\n#include \n#endif\n\n\"IQUADMATH\"\nThis symbol, if defined, indicates that quadmath.h exists and should be included.\n\n#ifdef IQUADMATH\n#include \n#endif\n\n\"LONGDBLINFBYTES\"\nThis symbol, if defined, is a comma-separated list of hexadecimal bytes for the long\ndouble precision infinity.\n\n\"LONGDBLMANTBITS\"\nThis symbol, if defined, tells how many mantissa bits there are in long double precision\nfloating point format. Note that this can be \"LDBLMANTDIG\" minus one, since\n\"LDBLMANTDIG\" can include the \"IEEE\" 754 implicit bit. The common x86-style 80-bit\nlong double does not have an implicit bit.\n\n\"LONGDBLNANBYTES\"\nThis symbol, if defined, is a comma-separated list of hexadecimal bytes (0xHH) for the\nlong double precision not-a-number.\n\n\"LONGDOUBLEKIND\"\n\"LONGDOUBLEKIND\" will be one of \"LONGDOUBLEISDOUBLE\"\n\"LONGDOUBLEISIEEE754128BITLITTLEENDIAN\"\n\"LONGDOUBLEISIEEE754128BITBIGENDIAN\" \"LONGDOUBLEISX8680BITLITTLEENDIAN\"\n\"LONGDOUBLEISX8680BITBIGENDIAN\" \"LONGDOUBLEISDOUBLEDOUBLE128BITLELE\"\n\"LONGDOUBLEISDOUBLEDOUBLE128BITBEBE\" \"LONGDOUBLEISDOUBLEDOUBLE128BITLEBE\"\n\"LONGDOUBLEISDOUBLEDOUBLE128BITBELE\"\n\"LONGDOUBLEISDOUBLEDOUBLE128BITLITTLEENDIAN\"\n\"LONGDOUBLEISDOUBLEDOUBLE128BITBIGENDIAN\" \"LONGDOUBLEISVAXHFLOAT\"\n\"LONGDOUBLEISUNKNOWNFORMAT\" It is only defined if the system supports long doubles.\n\n\"LONGDOUBLESIZE\"\nThis symbol contains the size of a long double, so that the C preprocessor can make\ndecisions based on it. It is only defined if the system supports long doubles. Note\nthat this is \"sizeof(long double)\", which may include unused bytes.\n\n\"LONGDOUBLESTYLEIEEE\"\nThis symbol, if defined, indicates that the long double is any of the \"IEEE\" 754 style\nlong doubles: \"LONGDOUBLESTYLEIEEESTD\", \"LONGDOUBLESTYLEIEEEEXTENDED\",\n\"LONGDOUBLESTYLEIEEEDOUBLEDOUBLE\".\n\n\"LONGDOUBLESTYLEIEEEDOUBLEDOUBLE\"\nThis symbol, if defined, indicates that the long double is the 128-bit double-double.\n\n\"LONGDOUBLESTYLEIEEEEXTENDED\"\nThis symbol, if defined, indicates that the long double is the 80-bit \"IEEE\" 754. Note\nthat despite the 'extended' this is less than the 'std', since this is an extension of\nthe double precision.\n\n\"LONGDOUBLESTYLEIEEESTD\"\nThis symbol, if defined, indicates that the long double is the 128-bit \"IEEE\" 754.\n\n\"LONGDOUBLESTYLEVAX\"\nThis symbol, if defined, indicates that the long double is the 128-bit \"VAX\" format H.\n\n\"NV\"\nDescribed in perlguts.\n\n\"NVMANTBITS\"\nThis symbol, if defined, tells how many mantissa bits (not including implicit bit) there\nare in a Perl NV. This depends on which floating point type was chosen.\n\n\"NVOVERFLOWSINTEGERSAT\"\nThis symbol gives the largest integer value that NVs can hold. This value + 1.0 cannot be\nstored accurately. It is expressed as constant floating point expression to reduce the\nchance of decimal/binary conversion issues. If it can not be determined, the value 0 is\ngiven.\n\n\"NVPRESERVESUV\"\nThis symbol, if defined, indicates that a variable of type \"NVTYPE\" can preserve all the\nbits of a variable of type \"UVTYPE\".\n\n\"NVPRESERVESUVBITS\"\nThis symbol contains the number of bits a variable of type \"NVTYPE\" can preserve of a\nvariable of type \"UVTYPE\".\n\n\"NVSIZE\"\nThis symbol contains the sizeof(NV). Note that some floating point formats have unused\nbytes. The most notable example is the x86* 80-bit extended precision which comes in\nbyte sizes of 12 and 16 (for 32 and 64 bit platforms, respectively), but which only uses\n10 bytes. Perl compiled with \"-Duselongdouble\" on x86* is like this.\n\n\"NVTYPE\"\nThis symbol defines the C type used for Perl's NV.\n\n\"NVZEROISALLBITSZERO\"\nThis symbol, if defined, indicates that a variable of type \"NVTYPE\" stores 0.0 in memory\nas all bits zero.\n", "subsections": [] }, "General Configuration": { "content": "This section contains configuration information not otherwise found in the more specialized\nsections of this document. At the end is a list of \"#defines\" whose name should be enough to\ntell you what they do, and a list of #defines which tell you if you need to \"#include\" files\nto get the corresponding functionality.\n\n\"ASCIIish\"\nA preprocessor symbol that is defined iff the system is an ASCII platform; this symbol\nwould not be defined on \"EBCDIC\" platforms.\n\n#ifdef ASCIIish\n\n\"BYTEORDER\"\nThis symbol holds the hexadecimal constant defined in byteorder, in a UV, i.e. 0x1234 or\n0x4321 or 0x12345678, etc... If the compiler supports cross-compiling or multiple-\narchitecture binaries, use compiler-defined macros to determine the byte order.\n\n\"CHARBITS\"\nThis symbol contains the size of a char, so that the C preprocessor can make decisions\nbased on it.\n\n\"DBVERSIONMAJORCFG\"\nThis symbol, if defined, defines the major version number of Berkeley DB found in the\ndb.h header when Perl was configured.\n\n\"DBVERSIONMINORCFG\"\nThis symbol, if defined, defines the minor version number of Berkeley DB found in the\ndb.h header when Perl was configured. For DB version 1 this is always 0.\n\n\"DBVERSIONPATCHCFG\"\nThis symbol, if defined, defines the patch version number of Berkeley DB found in the\ndb.h header when Perl was configured. For DB version 1 this is always 0.\n\n\"DEFAULTINCEXCLUDESDOT\"\nThis symbol, if defined, removes the legacy default behavior of including '.' at the end\nof @\"INC\".\n\n\"DLSYMNEEDSUNDERSCORE\"\nThis symbol, if defined, indicates that we need to prepend an underscore to the symbol\nname before calling dlsym(). This only makes sense if you *have* dlsym, which we will\npresume is the case if you're using dldlopen.xs.\n\n\"EBCDIC\"\nThis symbol, if defined, indicates that this system uses \"EBCDIC\" encoding.\n\n\"HASCSH\"\nThis symbol, if defined, indicates that the C-shell exists.\n\n\"HASGETHOSTNAME\"\nThis symbol, if defined, indicates that the C program may use the gethostname() routine\nto derive the host name. See also \"HASUNAME\" and \"PHOSTNAME\".\n\n\"HASGNULIBC\"\nThis symbol, if defined, indicates to the C program that the \"GNU\" C library is being\nused. A better check is to use the \"GLIBC\" and \"GLIBCMINOR\" symbols supplied\nwith glibc.\n\n\"HASLGAMMA\"\nThis symbol, if defined, indicates that the \"lgamma\" routine is available to do the log\ngamma function. See also \"HASTGAMMA\" and \"HASLGAMMAR\".\n\n\"HASLGAMMAR\"\nThis symbol, if defined, indicates that the \"lgammar\" routine is available to do the log\ngamma function without using the global signgam variable.\n\n\"HASNONINTBITFIELDS\"\nThis symbol, if defined, indicates that the C compiler accepts, without error or warning,\n\"struct bitfields\" that are declared with sizes other than plain 'int'; for example\n'unsigned char' is accepted.\n\n\"HASPRCTLSETNAME\"\nThis symbol, if defined, indicates that the prctl routine is available to set process\ntitle and supports \"PRSETNAME\".\n\n\"HASPROCSELFEXE\"\nThis symbol is defined if \"PROCSELFEXEPATH\" is a symlink to the absolute pathname of the\nexecuting program.\n\n\"HASPSEUDOFORK\"\nThis symbol, if defined, indicates that an emulation of the fork routine is available.\n\n\"HASREGCOMP\"\nThis symbol, if defined, indicates that the regcomp() routine is available to do some\nregular pattern matching (usually on \"POSIX\".2 conforming systems).\n\n\"HASSETPGID\"\nThis symbol, if defined, indicates that the \"setpgid(pid, gpid)\" routine is available to\nset process group ID.\n\n\"HASSIGSETJMP\"\nThis variable indicates to the C program that the sigsetjmp() routine is available to\nsave the calling process's registers and stack environment for later use by siglongjmp(),\nand to optionally save the process's signal mask. See \"Sigjmpbuf\", \"Sigsetjmp\", and\n\"Siglongjmp\".\n\n\"HASSTRUCTCMSGHDR\"\nThis symbol, if defined, indicates that the \"struct cmsghdr\" is supported.\n\n\"HASSTRUCTMSGHDR\"\nThis symbol, if defined, indicates that the \"struct msghdr\" is supported.\n\n\"HASTGAMMA\"\nThis symbol, if defined, indicates that the \"tgamma\" routine is available to do the gamma\nfunction. See also \"HASLGAMMA\".\n\n\"HASUNAME\"\nThis symbol, if defined, indicates that the C program may use the uname() routine to\nderive the host name. See also \"HASGETHOSTNAME\" and \"PHOSTNAME\".\n\n\"HASUNIONSEMUN\"\nThis symbol, if defined, indicates that the \"union semun\" is defined by including\nsys/sem.h. If not, the user code probably needs to define it as:\n\nunion semun {\nint val;\nstruct semidds *buf;\nunsigned short *array;\n}\n\n\"IDIRENT\"\nThis symbol, if defined, indicates to the C program that it should include dirent.h.\nUsing this symbol also triggers the definition of the \"Direntryt\" define which ends up\nbeing '\"struct dirent\"' or '\"struct direct\"' depending on the availability of dirent.h.\n\n#ifdef IDIRENT\n#include \n#endif\n\n\"IPOLL\"\nThis symbol, if defined, indicates that poll.h exists and should be included. (see also\n\"HASPOLL\")\n\n#ifdef IPOLL\n#include \n#endif\n\n\"ISYSRESOURCE\"\nThis symbol, if defined, indicates to the C program that it should include\nsys/resource.h.\n\n#ifdef ISYSRESOURCE\n#include \n#endif\n\n\"LIBMLIBVERSION\"\nThis symbol, if defined, indicates that libm exports \"LIBVERSION\" and that math.h\ndefines the enum to manipulate it.\n\n\"NEEDVACOPY\"\nThis symbol, if defined, indicates that the system stores the variable argument list\ndatatype, \"valist\", in a format that cannot be copied by simple assignment, so that some\nother means must be used when copying is required. As such systems vary in their\nprovision (or non-provision) of copying mechanisms, handy.h defines a platform-\nindependent macro, \"Perlvacopy(src, dst)\", to do the job.\n\n\"OSNAME\"\nThis symbol contains the name of the operating system, as determined by Configure. You\nshouldn't rely on it too much; the specific feature tests from Configure are generally\nmore reliable.\n\n\"OSVERS\"\nThis symbol contains the version of the operating system, as determined by Configure.\nYou shouldn't rely on it too much; the specific feature tests from Configure are\ngenerally more reliable.\n\n\"PERLUSEGCCBRACEGROUPS\"\nThis C pre-processor value, if defined, indicates that it is permissible to use the GCC\nbrace groups extension. However, use of this extension is DISCOURAGED. Use a \"static\ninline\" function instead.\n\nThe extension, of the form\n\n({ statement ... })\n\nturns the block consisting of statement ... into an expression with a value, unlike plain\nC language blocks. This can present optimization possibilities, BUT, unless you know for\nsure that this will never be compiled without this extension being available and not\nforbidden, you need to specify an alternative. Thus two code paths have to be\nmaintained, which can get out-of-sync. All these issues are solved by using a \"static\ninline\" function instead.\n\nPerl can be configured to not use this feature by passing the parameter\n\"-Accflags=-DPERLGCCBRACEGROUPSFORBIDDEN\" to Configure.\n\n#ifdef PERLUSEGCCBRACEGROUPS\n\n\"PHOSTNAME\"\nThis symbol, if defined, indicates the command to feed to the popen() routine to derive\nthe host name. See also \"HASGETHOSTNAME\" and \"HASUNAME\". Note that the command uses a\nfully qualified path, so that it is safe even if used by a process with super-user\nprivileges.\n\n\"PROCSELFEXEPATH\"\nIf \"HASPROCSELFEXE\" is defined this symbol is the filename of the symbolic link pointing\nto the absolute pathname of the executing program.\n\n\"PTRSIZE\"\nThis symbol contains the size of a pointer, so that the C preprocessor can make decisions\nbased on it. It will be \"sizeof(void *)\" if the compiler supports (void *); otherwise it\nwill be \"sizeof(char *)\".\n\n\"RANDBITS\"\nThis symbol indicates how many bits are produced by the function used to generate\nnormalized random numbers. Values include 15, 16, 31, and 48.\n\n\"SELECTMINBITS\"\nThis symbol holds the minimum number of bits operated by select. That is, if you do\n\"select(n, ...)\", how many bits at least will be cleared in the masks if some activity is\ndetected. Usually this is either n or 32*ceil(n/32), especially many little-endians do\nthe latter. This is only useful if you have select(), naturally.\n\n\"SETUIDSCRIPTSARESECURENOW\"\nThis symbol, if defined, indicates that the bug that prevents setuid scripts from being\nsecure is not present in this kernel.\n\n\"STDEVSIGN\"\nThis symbol holds the signedness of \"struct stat\"'s \"stdev\". 1 for unsigned, -1 for\nsigned.\n\n\"STDEVSIZE\"\nThis variable contains the size of \"struct stat\"'s \"stdev\" in bytes.\n", "subsections": [ { "name": "List of capability \"HAS__foo_\" symbols", "content": "This is a list of those symbols that dont appear elsewhere in ths document that indicate if\nthe current platform has a certain capability. Their names all begin with \"HAS\". Only\nthose symbols whose capability is directly derived from the name are listed here. All others\nhave their meaning expanded out elsewhere in this document. This (relatively) compact list\nis because we think that the expansion would add little or no value and take up a lot of\nspace (because there are so many). If you think certain ones should be expanded, send email\nto perl5-porters@perl.org .\n\nEach symbol here will be \"#define\"d if and only if the platform has the capability. If you\nneed more detail, see the corresponding entry in config.h. For convenience, the list is\nsplit so that the ones that indicate there is a reentrant version of a capability are listed\nseparately\n\n\"HASACCEPT4\", \"HASACCESS\", \"HASACCESSX\", \"HASACOSH\", \"HASAINTL\", \"HASALARM\",\n\"HASASINH\", \"HASATANH\", \"HASATOLL\", \"HASCBRT\", \"HASCHOWN\", \"HASCHROOT\",\n\"HASCHSIZE\", \"HASCLEARENV\", \"HASCOPYSIGN\", \"HASCOPYSIGNL\", \"HASCRYPT\",\n\"HASCTERMID\", \"HASCUSERID\", \"HASDIRFD\", \"HASDLADDR\", \"HASDLERROR\", \"HASEACCESS\",\n\"HASENDHOSTENT\", \"HASENDNETENT\", \"HASENDPROTOENT\", \"HASENDSERVENT\", \"HASERF\",\n\"HASERFC\", \"HASEXPM1\", \"HASEXP2\", \"HASFCHMOD\", \"HASFCHMODAT\", \"HASFCHOWN\",\n\"HASFDIM\", \"HASFDSET\", \"HASFEGETROUND\", \"HASFFS\", \"HASFFSL\", \"HASFGETPOS\",\n\"HASFLOCK\", \"HASFMA\", \"HASFMAX\", \"HASFMIN\", \"HASFORK\", \"HASFSEEKO\",\n\"HASFSETPOS\", \"HASFSYNC\", \"HASFTELLO\", \"HASFWALK\", \"HASGAISTRERROR\",\n\"HASGETADDRINFO\", \"HASGETCWD\", \"HASGETESPWNAM\", \"HASGETGROUPS\", \"HASGETHOSTBYADDR\",\n\"HASGETHOSTBYNAME\", \"HASGETHOSTENT\", \"HASGETLOGIN\", \"HASGETNAMEINFO\",\n\"HASGETNETBYADDR\", \"HASGETNETBYNAME\", \"HASGETNETENT\", \"HASGETPAGESIZE\",\n\"HASGETPGID\", \"HASGETPGRP\", \"HASGETPGRP2\", \"HASGETPPID\", \"HASGETPRIORITY\",\n\"HASGETPROTOBYNAME\", \"HASGETPROTOBYNUMBER\", \"HASGETPROTOENT\", \"HASGETPRPWNAM\",\n\"HASGETSERVBYNAME\", \"HASGETSERVBYPORT\", \"HASGETSERVENT\", \"HASGETSPNAM\", \"HASHTONL\",\n\"HASHTONS\", \"HASHYPOT\", \"HASILOGBL\", \"HASINETATON\", \"HASINETNTOP\",\n\"HASINETPTON\", \"HASIPMREQ\", \"HASIPMREQSOURCE\", \"HASIPV6MREQ\",\n\"HASIPV6MREQSOURCE\", \"HASISASCII\", \"HASISBLANK\", \"HASISLESS\", \"HASKILLPG\",\n\"HASLCHOWN\", \"HASLINK\", \"HASLINKAT\", \"HASLLROUND\", \"HASLOCKF\", \"HASLOGB\",\n\"HASLOG1P\", \"HASLOG2\", \"HASLROUND\", \"HASLSTAT\", \"HASMADVISE\", \"HASMBLEN\",\n\"HASMBRLEN\", \"HASMBRTOWC\", \"HASMBSTOWCS\", \"HASMBTOWC\", \"HASMEMMEM\", \"HASMEMRCHR\",\n\"HASMKDTEMP\", \"HASMKFIFO\", \"HASMKOSTEMP\", \"HASMKSTEMP\", \"HASMKSTEMPS\", \"HASMMAP\",\n\"HASMPROTECT\", \"HASMSG\", \"HASMSYNC\", \"HASMUNMAP\", \"HASNEARBYINT\", \"HASNEXTAFTER\",\n\"HASNICE\", \"HASNTOHL\", \"HASNTOHS\", \"HASPATHCONF\", \"HASPAUSE\", \"HASPHOSTNAME\",\n\"HASPIPE\", \"HASPIPE2\", \"HASPRCTL\", \"HASPTRDIFFT\", \"HASREADLINK\", \"HASREADV\",\n\"HASRECVMSG\", \"HASREMQUO\", \"HASRENAME\", \"HASRENAMEAT\", \"HASRINT\", \"HASROUND\",\n\"HASSCALBNL\", \"HASSEM\", \"HASSENDMSG\", \"HASSETEGID\", \"HASSETENV\", \"HASSETEUID\",\n\"HASSETGROUPS\", \"HASSETHOSTENT\", \"HASSETLINEBUF\", \"HASSETNETENT\", \"HASSETPGRP\",\n\"HASSETPGRP2\", \"HASSETPRIORITY\", \"HASSETPROCTITLE\", \"HASSETPROTOENT\",\n\"HASSETREGID\", \"HASSETRESGID\", \"HASSETRESUID\", \"HASSETREUID\", \"HASSETRGID\",\n\"HASSETRUID\", \"HASSETSERVENT\", \"HASSETSID\", \"HASSHM\", \"HASSIGACTION\",\n\"HASSIGPROCMASK\", \"HASSIN6SCOPEID\", \"HASSNPRINTF\", \"HASSTAT\", \"HASSTRCOLL\",\n\"HASSTRERRORL\", \"HASSTRLCAT\", \"HASSTRLCPY\", \"HASSTRNLEN\", \"HASSTRTOD\",\n\"HASSTRTOL\", \"HASSTRTOLL\", \"HASSTRTOQ\", \"HASSTRTOUL\", \"HASSTRTOULL\",\n\"HASSTRTOUQ\", \"HASSTRXFRM\", \"HASSTRXFRML\", \"HASSYMLINK\", \"HASSYSCALL\",\n\"HASSYSCONF\", \"HASSYSERRLIST\", \"HASSYSTEM\", \"HASTCGETPGRP\", \"HASTCSETPGRP\",\n\"HASTOWLOWER\", \"HASTOWUPPER\", \"HASTRUNCATE\", \"HASTRUNCL\", \"HASUALARM\",\n\"HASUMASK\", \"HASUNLINKAT\", \"HASUNSETENV\", \"HASVFORK\", \"HASVSNPRINTF\",\n\"HASWAITPID\", \"HASWAIT4\", \"HASWCRTOMB\", \"HASWCSCMP\", \"HASWCSTOMBS\", \"HASWCSXFRM\",\n\"HASWCTOMB\", \"HASWRITEV\"\n\nAnd, the reentrant capabilities:\n\n\"HASCRYPTR\", \"HASCTERMIDR\", \"HASDRAND48R\", \"HASENDHOSTENTR\", \"HASENDNETENTR\",\n\"HASENDPROTOENTR\", \"HASENDSERVENTR\", \"HASGETGRGIDR\", \"HASGETGRNAMR\",\n\"HASGETHOSTBYADDRR\", \"HASGETHOSTBYNAMER\", \"HASGETHOSTENTR\", \"HASGETLOGINR\",\n\"HASGETNETBYADDRR\", \"HASGETNETBYNAMER\", \"HASGETNETENTR\", \"HASGETPROTOBYNAMER\",\n\"HASGETPROTOBYNUMBERR\", \"HASGETPROTOENTR\", \"HASGETPWNAMR\", \"HASGETPWUIDR\",\n\"HASGETSERVBYNAMER\", \"HASGETSERVBYPORTR\", \"HASGETSERVENTR\", \"HASGETSPNAMR\",\n\"HASRANDOMR\", \"HASREADDIRR\", \"HASSETHOSTENTR\", \"HASSETNETENTR\",\n\"HASSETPROTOENTR\", \"HASSETSERVENTR\", \"HASSRANDOMR\", \"HASSRAND48R\",\n\"HASSTRERRORR\", \"HASTMPNAMR\", \"HASTTYNAMER\"\n\nExample usage:\n\n#ifdef HASSTRNLEN\nuse strnlen()\n#else\nuse an alternative implementation\n#endif\n" }, { "name": "List of \"#include\" needed symbols", "content": "This list contains symbols that indicate if certain \"#include\" files are present on the\nplatform. If your code accesses the functionality that one of these is for, you will need to\n\"#include\" it if the symbol on this list is \"#define\"d. For more detail, see the\ncorresponding entry in config.h.\n\n\"IARPAINET\", \"IBFD\", \"ICRYPT\", \"IDBM\", \"IDLFCN\", \"IEXECINFO\", \"IFP\",\n\"IFPCLASS\", \"IGDBM\", \"IGDBMNDBM\", \"IGDBMNDBM\", \"IGRP\", \"IIEEEFP\",\n\"IINTTYPES\", \"ILIBUTIL\", \"IMNTENT\", \"INDBM\", \"INETDB\", \"INETERRNO\",\n\"INETINETIN\", \"INETINETTCP\", \"IPROT\", \"IPWD\", \"IRPCSVCDBM\", \"ISGTTY\",\n\"ISHADOW\", \"ISTDBOOL\", \"ISTDINT\", \"ISUNMATH\", \"ISYSACCESS\", \"ISYSIOCTL\",\n\"ISYSLOG\", \"ISYSMODE\", \"ISYSMOUNT\", \"ISYSPARAM\", \"ISYSPOLL\", \"ISYSSECURITY\",\n\"ISYSSELECT\", \"ISYSSTAT\", \"ISYSSTATVFS\", \"ISYSSYSCALL\", \"ISYSTIME\",\n\"ISYSTIMEKERNEL\", \"ISYSTIMES\", \"ISYSTYPES\", \"ISYSUIO\", \"ISYSUN\",\n\"ISYSUTSNAME\", \"ISYSVFS\", \"ISYSWAIT\", \"ITERMIO\", \"ITERMIOS\", \"IUNISTD\",\n\"IUSTAT\", \"IVFORK\", \"IWCHAR\", \"IWCTYPE\"\n\nExample usage:\n\n#ifdef IWCHAR\n#include \n#endif\n" } ] }, "Global Variables": { "content": "These variables are global to an entire process. They are shared between all interpreters\nand all threads in a process. Any variables not documented here may be changed or removed\nwithout notice, so don't use them! If you feel you really do need to use an unlisted\nvariable, first send email to perl5-porters@perl.org . It may\nbe that someone there will point out a way to accomplish what you need without using an\ninternal variable. But if not, you should get a go-ahead to document and then use the\nvariable.\n\n\"PLcheck\"\nArray, indexed by opcode, of functions that will be called for the \"check\" phase of\noptree building during compilation of Perl code. For most (but not all) types of op,\nonce the op has been initially built and populated with child ops it will be filtered\nthrough the check function referenced by the appropriate element of this array. The new\nop is passed in as the sole argument to the check function, and the check function\nreturns the completed op. The check function may (as the name suggests) check the op for\nvalidity and signal errors. It may also initialise or modify parts of the ops, or\nperform more radical surgery such as adding or removing child ops, or even throw the op\naway and return a different op in its place.\n\nThis array of function pointers is a convenient place to hook into the compilation\nprocess. An XS module can put its own custom check function in place of any of the\nstandard ones, to influence the compilation of a particular type of op. However, a\ncustom check function must never fully replace a standard check function (or even a\ncustom check function from another module). A module modifying checking must instead\nwrap the preexisting check function. A custom check function must be selective about\nwhen to apply its custom behaviour. In the usual case where it decides not to do\nanything special with an op, it must chain the preexisting op function. Check functions\nare thus linked in a chain, with the core's base checker at the end.\n\nFor thread safety, modules should not write directly to this array. Instead, use the\nfunction \"wrapopchecker\".\n\n\"PLinfixplugin\"\nNOTE: \"PLinfixplugin\" is experimental and may change or be removed without notice.\n\nNOTE: This API exists entirely for the purpose of making the CPAN module\n\"XS::Parse::Infix\" work. It is not expected that additional modules will make use of it;\nrather, that they should use \"XS::Parse::Infix\" to provide parsing of new infix\noperators.\n\nFunction pointer, pointing at a function used to handle extended infix operators. The\nfunction should be declared as\n\nint infixpluginfunction(pTHX\nchar *opname, STRLEN oplen,\nstruct Perlcustominfix infixptr)\n\nThe function is called from the tokenizer whenever a possible infix operator is seen.\n\"opname\" points to the operator name in the parser's input buffer, and \"oplen\" gives the\nmaximum number of bytes of it that should be consumed; it is not null-terminated. The\nfunction is expected to examine the operator name and possibly other state such as %^H,\nto determine whether it wants to handle the operator name.\n\nAs compared to the single stage of \"PLkeywordplugin\", parsing of additional infix\noperators occurs in three separate stages. This is because of the more complex\ninteractions it has with the parser, to ensure that operator precedence rules work\ncorrectly. These stages are co-ordinated by the use of an additional information\nstructure.\n\nIf the function wants to handle the infix operator, it must set the variable pointed to\nby \"infixptr\" to the address of a structure that provides this additional information\nabout the subsequent parsing stages. If it does not, it should make a call to the next\nfunction in the chain.\n\nThis structure has the following definition:\n\nstruct Perlcustominfix {\nenum Perlcustominfixprecedence prec;\nvoid (*parse)(pTHX SV opdata,\nstruct Perlcustominfix *);\nOP *(*buildop)(pTHX SV opdata, OP *lhs, OP *rhs,\nstruct Perlcustominfix *);\n};\n\nThe function must then return an integer giving the number of bytes consumed by the name\nof this operator. In the case of an operator whose name is composed of identifier\ncharacters, this must be equal to \"oplen\". In the case of an operator named by non-\nidentifier characters, this is permitted to be shorter than \"oplen\", and any additional\ncharacters after it will not be claimed by the infix operator but instead will be\nconsumed by the tokenizer and parser as normal.\n\nIf the optional \"parse\" function is provided, it is called immediately by the parser to\nlet the operator's definition consume any additional syntax from the source code. This\nshould not be used for normal operand parsing, but it may be useful when implementing\nthings like parametric operators or meta-operators that consume more syntax themselves.\nThis function may use the variable pointed to by \"opdata\" to provide an SV containing\nadditional data to be passed into the \"buildop\" function later on.\n\nThe information structure gives the operator precedence level in the \"prec\" field. This\nis used to tell the parser how much of the surrounding syntax before and after should be\nconsidered as operands to the operator.\n\nThe tokenizer and parser will then continue to operate as normal until enough additional\ninput has been parsed to form both the left- and right-hand side operands to the\noperator, according to the precedence level. At this point the \"buildop\" function is\ncalled, being passed the left- and right-hand operands as optree fragments. It is\nexpected to combine them into the resulting optree fragment, which it should return.\n\nAfter the \"buildop\" function has returned, if the variable pointed to by \"opdata\" was\nset to a non-\"NULL\" value, it will then be destroyed by calling SvREFCNTdec().\n\nFor thread safety, modules should not set this variable directly. Instead, use the\nfunction \"wrapinfixplugin\".\n\nHowever, that all said, the introductory note above still applies. This variable is\nprovided in core perl only for the benefit of the \"XS::Parse::Infix\" module. That module\nacts as a central registry for infix operators, automatically handling things like\ndeparse support and discovery/reflection, and these abilities only work because it knows\nall the registered operators. Other modules should not use this interpreter variable\ndirectly to implement them because then those central features would no longer work\nproperly.\n\nFurthermore, it is likely that this (experimental) API will be replaced in a future Perl\nversion by a more complete API that fully implements the central registry and other\nsemantics currently provided by \"XS::Parse::Infix\", once the module has had sufficient\nexperimental testing time. This current mechanism exists only as an interim measure to\nget to that stage.\n\n\"PLkeywordplugin\"\nNOTE: \"PLkeywordplugin\" is experimental and may change or be removed without notice.\n\nFunction pointer, pointing at a function used to handle extended keywords. The function\nshould be declared as\n\nint keywordpluginfunction(pTHX\nchar *keywordptr, STRLEN keywordlen,\nOP opptr)\n\nThe function is called from the tokeniser, whenever a possible keyword is seen.\n\"keywordptr\" points at the word in the parser's input buffer, and \"keywordlen\" gives\nits length; it is not null-terminated. The function is expected to examine the word, and\npossibly other state such as %^H, to decide whether it wants to handle it as an extended\nkeyword. If it does not, the function should return \"KEYWORDPLUGINDECLINE\", and the\nnormal parser process will continue.\n\nIf the function wants to handle the keyword, it first must parse anything following the\nkeyword that is part of the syntax introduced by the keyword. See \"Lexer interface\" for\ndetails.\n\nWhen a keyword is being handled, the plugin function must build a tree of \"OP\"\nstructures, representing the code that was parsed. The root of the tree must be stored\nin *opptr. The function then returns a constant indicating the syntactic role of the\nconstruct that it has parsed: \"KEYWORDPLUGINSTMT\" if it is a complete statement, or\n\"KEYWORDPLUGINEXPR\" if it is an expression. Note that a statement construct cannot be\nused inside an expression (except via \"do BLOCK\" and similar), and an expression is not a\ncomplete statement (it requires at least a terminating semicolon).\n\nWhen a keyword is handled, the plugin function may also have (compile-time) side effects.\nIt may modify \"%^H\", define functions, and so on. Typically, if side effects are the\nmain purpose of a handler, it does not wish to generate any ops to be included in the\nnormal compilation. In this case it is still required to supply an op tree, but it\nsuffices to generate a single null op.\n\nThat's how the *PLkeywordplugin function needs to behave overall. Conventionally,\nhowever, one does not completely replace the existing handler function. Instead, take a\ncopy of \"PLkeywordplugin\" before assigning your own function pointer to it. Your\nhandler function should look for keywords that it is interested in and handle those.\nWhere it is not interested, it should call the saved plugin function, passing on the\narguments it received. Thus \"PLkeywordplugin\" actually points at a chain of handler\nfunctions, all of which have an opportunity to handle keywords, and only the last\nfunction in the chain (built into the Perl core) will normally return\n\"KEYWORDPLUGINDECLINE\".\n\nFor thread safety, modules should not set this variable directly. Instead, use the\nfunction \"wrapkeywordplugin\".\n\n\"PLphase\"\nA value that indicates the current Perl interpreter's phase. Possible values include\n\"PERLPHASECONSTRUCT\", \"PERLPHASESTART\", \"PERLPHASECHECK\", \"PERLPHASEINIT\",\n\"PERLPHASERUN\", \"PERLPHASEEND\", and \"PERLPHASEDESTRUCT\".\n\nFor example, the following determines whether the interpreter is in global destruction:\n\nif (PLphase == PERLPHASEDESTRUCT) {\n// we are in global destruction\n}\n\n\"PLphase\" was introduced in Perl 5.14; in prior perls you can use \"PLdirty\" (boolean)\nto determine whether the interpreter is in global destruction. (Use of \"PLdirty\" is\ndiscouraged since 5.14.)\n\nenum perlphase PLphase\n\nGV Handling and Stashes\nA GV is a structure which corresponds to to a Perl typeglob, ie *foo. It is a structure that\nholds a pointer to a scalar, an array, a hash etc, corresponding to $foo, @foo, %foo.\n\nGVs are usually found as values in stashes (symbol table hashes) where Perl stores its global\nvariables.\n\nA stash is a hash that contains all variables that are defined within a package. See\n\"Stashes and Globs\" in perlguts\n\n\"amagiccall\"\nPerform the overloaded (active magic) operation given by \"method\". \"method\" is one of\nthe values found in overload.h.\n\n\"flags\" affects how the operation is performed, as follows:\n\n\"AMGfnoleft\"\n\"left\" is not to be used in this operation.\n\n\"AMGfnoright\"\n\"right\" is not to be used in this operation.\n\n\"AMGfunary\"\nThe operation is done only on just one operand.\n\n\"AMGfassign\"\nThe operation changes one of the operands, e.g., $x += 1\n\nSV * amagiccall(SV *left, SV *right, int method, int dir)\n\n\"amagicderefcall\"\nPerform \"method\" overloading dereferencing on \"ref\", returning the dereferenced result.\n\"method\" must be one of the dereference operations given in overload.h.\n\nIf overloading is inactive on \"ref\", returns \"ref\" itself.\n\nSV * amagicderefcall(SV *ref, int method)\n\n\"gvaddbytype\"\nMake sure there is a slot of type \"type\" in the GV \"gv\".\n\nGV * gvaddbytype(GV *gv, svtype type)\n\n\"GvAMupdate\"\nRecalculates overload magic in the package given by \"stash\".\n\nReturns:\n\n1 on success and there is some overload\n0 if there is no overload\n-1 if some error occurred and it couldn't croak (because \"destructing\" is true).\n\nint GvAMupdate(HV *stash, bool destructing)\n\n\"gvautoloadpv\"\n\"gvautoloadpvn\"\n\"gvautoloadsv\"\nThese each search for an \"AUTOLOAD\" method, returning NULL if not found, or else\nreturning a pointer to its GV, while setting the package $AUTOLOAD variable to \"name\"\n(fully qualified). Also, if found and the GV's CV is an XSUB, the CV's PV will be set to\n\"name\", and its stash will be set to the stash of the GV.\n\nSearching is done in \"MRO\" order, as specified in \"\"gvfetchmeth\"\", beginning with\n\"stash\" if it isn't NULL.\n\nThe forms differ only in how \"name\" is specified.\n\nIn \"gvautoloadpv\", \"namepv\" is a C language NUL-terminated string.\n\nIn \"gvautoloadpvn\", \"name\" points to the first byte of the name, and an additional\nparameter, \"len\", specifies its length in bytes. Hence, *name may contain embedded-NUL\ncharacters.\n\nIn \"gvautoloadsv\", *namesv is an SV, and the name is the PV extracted from that using\n\"\"SvPV\"\". If the SV is marked as being in UTF-8, the extracted PV will also be.\n\nGV * gvautoloadpv (HV *stash, const char *namepv, U32 flags)\nGV * gvautoloadpvn(HV *stash, const char *name, STRLEN len,\nU32 flags)\nGV * gvautoloadsv (HV *stash, SV *namesv, U32 flags)\n\n\"gvautoload4\"\nEquivalent to \"gvautoloadpvn\".\n\nGV * gvautoload4(HV *stash, const char *name, STRLEN len,\nI32 method)\n\n\"GvAV\"\nReturn the AV from the GV.\n\nAV* GvAV(GV* gv)\n\n\"gvAVadd\"\n\"gvHVadd\"\n\"gvIOadd\"\n\"gvSVadd\"\nMake sure there is a slot of the given type (AV, HV, IO, SV) in the GV \"gv\".\n\nGV * gvAVadd(GV *gv)\n\n\"gvconstsv\"\nIf \"gv\" is a typeglob whose subroutine entry is a constant sub eligible for inlining, or\n\"gv\" is a placeholder reference that would be promoted to such a typeglob, then returns\nthe value returned by the sub. Otherwise, returns \"NULL\".\n\nSV * gvconstsv(GV *gv)\n\n\"GvCV\"\nReturn the CV from the GV.\n\nCV* GvCV(GV* gv)\n\n\"gvefullname3\"\n\"gvefullname4\"\n\"gvfullname3\"\n\"gvfullname4\"\nPlace the full package name of \"gv\" into \"sv\". The \"gve*\" forms return instead the\neffective package name (see \"HvENAME\").\n\nIf \"prefix\" is non-NULL, it is considered to be a C language NUL-terminated string, and\nthe stored name will be prefaced with it.\n\nThe other difference between the functions is that the *4 forms have an extra parameter,\n\"keepmain\". If \"true\" an initial \"main::\" in the name is kept; if \"false\" it is\nstripped. With the *3 forms, it is always kept.\n\nvoid gvefullname3(SV *sv, const GV *gv, const char *prefix)\nvoid gvefullname4(SV *sv, const GV *gv, const char *prefix,\nbool keepmain)\nvoid gvfullname3 (SV *sv, const GV *gv, const char *prefix)\nvoid gvfullname4 (SV *sv, const GV *gv, const char *prefix,\nbool keepmain)\n\n\"gvfetchfile\"\n\"gvfetchfileflags\"\nThese return the debugger glob for the file (compiled by Perl) whose name is given by the\n\"name\" parameter.\n\nThere are currently exactly two differences between these functions.\n\nThe \"name\" parameter to \"gvfetchfile\" is a C string, meaning it is \"NUL\"-terminated;\nwhereas the \"name\" parameter to \"gvfetchfileflags\" is a Perl string, whose length (in\nbytes) is passed in via the \"namelen\" parameter This means the name may contain embedded\n\"NUL\" characters. \"namelen\" doesn't exist in plain \"gvfetchfile\").\n\nThe other difference is that \"gvfetchfileflags\" has an extra \"flags\" parameter, which\nis currently completely ignored, but allows for possible future extensions.\n\nGV * gvfetchfile (const char *name)\nGV * gvfetchfileflags(const char * const name,\nconst STRLEN len, const U32 flags)\n\n\"gvfetchmeth\"\n\"gvfetchmethpv\"\n\"gvfetchmethpvn\"\n\"gvfetchmethsv\"\nThese each look for a glob with name \"name\", containing a defined subroutine, returning\nthe GV of that glob if found, or \"NULL\" if not.\n\n\"stash\" is always searched (first), unless it is \"NULL\".\n\nIf \"stash\" is NULL, or was searched but nothing was found in it, and the \"GVSUPER\" bit\nis set in \"flags\", stashes accessible via @ISA are searched next. Searching is conducted\naccording to \"MRO\" order.\n\nFinally, if no matches were found so far, and the \"GVNOUNIVERSAL\" flag in \"flags\" is not\nset, \"UNIVERSAL::\" is searched.\n\nThe argument \"level\" should be either 0 or -1. If -1, the function will return without\nany side effects or caching. If 0, the function makes sure there is a glob named \"name\"\nin \"stash\", creating one if necessary. The subroutine slot in the glob will be set to\nany subroutine found in the \"stash\" and \"SUPER::\" search, hence caching any \"SUPER::\"\nresult. Note that subroutines found in \"UNIVERSAL::\" are not cached.\n\nThe GV returned from these may be a method cache entry, which is not visible to Perl\ncode. So when calling \"callsv\", you should not use the GV directly; instead, you should\nuse the method's CV, which can be obtained from the GV with the \"GvCV\" macro.\n\nThe only other significant value for \"flags\" is \"SVfUTF8\", indicating that \"name\" is to\nbe treated as being encoded in UTF-8.\n\nPlain \"gvfetchmeth\" lacks a \"flags\" parameter, hence always searches in \"stash\", then\n\"UNIVERSAL::\", and \"name\" is never UTF-8. Otherwise it is exactly like\n\"gvfetchmethpvn\".\n\nThe other forms do have a \"flags\" parameter, and differ only in how the glob name is\nspecified.\n\nIn \"gvfetchmethpv\", \"name\" is a C language NUL-terminated string.\n\nIn \"gvfetchmethpvn\", \"name\" points to the first byte of the name, and an additional\nparameter, \"len\", specifies its length in bytes. Hence, the name may contain embedded-\nNUL characters.\n\nIn \"gvfetchmethsv\", *name is an SV, and the name is the PV extracted from that, using\n\"\"SvPV\"\". If the SV is marked as being in UTF-8, the extracted PV will also be.\n\nGV * gvfetchmeth (HV *stash, const char *name, STRLEN len,\nI32 level)\nGV * gvfetchmethpv (HV *stash, const char *name, I32 level,\nU32 flags)\nGV * gvfetchmethpvn(HV *stash, const char *name, STRLEN len,\nI32 level, U32 flags)\nGV * gvfetchmethsv (HV *stash, SV *namesv, I32 level,\nU32 flags)\n\n\"gvfetchmethautoload\"\nThis is the old form of \"gvfetchmethpvnautoload\", which has no flags parameter.\n\nGV * gvfetchmethautoload(HV *stash, const char *name,\nSTRLEN len, I32 level)\n\n\"gvfetchmethod\"\nSee \"gvfetchmethodautoload\".\n\nGV * gvfetchmethod(HV *stash, const char *name)\n\n\"gvfetchmethodautoload\"\nReturns the glob which contains the subroutine to call to invoke the method on the\n\"stash\". In fact in the presence of autoloading this may be the glob for \"AUTOLOAD\". In\nthis case the corresponding variable $AUTOLOAD is already setup.\n\nThe third parameter of \"gvfetchmethodautoload\" determines whether AUTOLOAD lookup is\nperformed if the given method is not present: non-zero means yes, look for AUTOLOAD; zero\nmeans no, don't look for AUTOLOAD. Calling \"gvfetchmethod\" is equivalent to calling\n\"gvfetchmethodautoload\" with a non-zero \"autoload\" parameter.\n\nThese functions grant \"SUPER\" token as a prefix of the method name. Note that if you\nwant to keep the returned glob for a long time, you need to check for it being\n\"AUTOLOAD\", since at the later time the call may load a different subroutine due to\n$AUTOLOAD changing its value. Use the glob created as a side effect to do this.\n\nThese functions have the same side-effects as \"gvfetchmeth\" with \"level==0\". The\nwarning against passing the GV returned by \"gvfetchmeth\" to \"callsv\" applies equally to\nthese functions.\n\nGV * gvfetchmethodautoload(HV *stash, const char *name,\nI32 autoload)\n\n\"gvfetchmethpvautoload\"\nExactly like \"gvfetchmethpvnautoload\", but takes a nul-terminated string instead of a\nstring/length pair.\n\nGV * gvfetchmethpvautoload(HV *stash, const char *name,\nI32 level, U32 flags)\n\n\"gvfetchmethpvnautoload\"\nSame as gvfetchmethpvn(), but looks for autoloaded subroutines too. Returns a glob for\nthe subroutine.\n\nFor an autoloaded subroutine without a GV, will create a GV even if \"level < 0\". For an\nautoloaded subroutine without a stub, GvCV() of the result may be zero.\n\nCurrently, the only significant value for \"flags\" is \"SVfUTF8\".\n\nGV * gvfetchmethpvnautoload(HV *stash, const char *name,\nSTRLEN len, I32 level, U32 flags)\n\n\"gvfetchmethsvautoload\"\nExactly like \"gvfetchmethpvnautoload\", but takes the name string in the form of an SV\ninstead of a string/length pair.\n\nGV * gvfetchmethsvautoload(HV *stash, SV *namesv, I32 level,\nU32 flags)\n\n\"gvfetchpv\"\n\"gvfetchpvn\"\n\"gvfetchpvnflags\"\n\"gvfetchpvs\"\n\"gvfetchsv\"\n\"gvfetchsvnomg\"\nThese all return the GV of type \"svtype\" whose name is given by the inputs, or NULL if\nno GV of that name and type could be found. See \"Stashes and Globs\" in perlguts.\n\nThe only differences are how the input name is specified, and if 'get' magic is normally\nused in getting that name.\n\nDon't be fooled by the fact that only one form has \"flags\" in its name. They all have a\n\"flags\" parameter in fact, and all the flag bits have the same meanings for all\n\nIf any of the flags \"GVADD\", \"GVADDMG\", \"GVADDWARN\", \"GVADDMULTI\", or \"GVNOINIT\" is\nset, a GV is created if none already exists for the input name and type. However,\n\"GVADDMG\" will only do the creation for magical GV's. For all of these flags except\n\"GVNOINIT\", \"gvinitpvn\" is called after the addition. \"GVADDWARN\" is used when the\ncaller expects that adding won't be necessary because the symbol should already exist;\nbut if not, add it anyway, with a warning that it was unexpectedly absent. The\n\"GVADDMULTI\" flag means to pretend that the GV has been seen before (i.e., suppress\n\"Used once\" warnings).\n\nThe flag \"GVNOADDNOINIT\" causes \"gvinitpvn\" not be to called if the GV existed but\nisn't PVGV.\n\nIf the \"SVfUTF8\" bit is set, the name is treated as being encoded in UTF-8; otherwise\nthe name won't be considered to be UTF-8 in the \"pv\"-named forms, and the UTF-8ness of\nthe underlying SVs will be used in the \"sv\" forms.\n\nIf the flag \"GVNOTQUAL\" is set, the caller warrants that the input name is a plain\nsymbol name, not qualified with a package, otherwise the name is checked for being a\nqualified one.\n\nIn \"gvfetchpv\", \"nambeg\" is a C string, NUL-terminated with no intermediate NULs.\n\nIn \"gvfetchpvs\", \"name\" is a literal C string, hence is enclosed in double quotes.\n\n\"gvfetchpvn\" and \"gvfetchpvnflags\" are identical. In these, is a Perl string\nwhose byte length is given by \"fulllen\", and may contain embedded NULs.\n\nIn \"gvfetchsv\" and \"gvfetchsvnomg\", the name is extracted from the PV of the input\n\"name\" SV. The only difference between these two forms is that 'get' magic is normally\ndone on \"name\" in \"gvfetchsv\", and always skipped with \"gvfetchsvnomg\". Including\n\"GVNOSVGMAGIC\" in the \"flags\" parameter to \"gvfetchsv\" makes it behave identically to\n\"gvfetchsvnomg\".\n\nGV * gvfetchpv (const char *nambeg, I32 flags,\nconst svtype svtype)\nGV * gvfetchpvn (const char * nambeg, STRLEN fulllen,\nI32 flags, const svtype svtype)\nGV * gvfetchpvnflags(const char *name, STRLEN len, I32 flags,\nconst svtype svtype)\nGV * gvfetchpvs (\"name\", I32 flags, const svtype svtype)\nGV * gvfetchsv (SV *name, I32 flags, const svtype svtype)\nGV * gvfetchsvnomg (SV *name, I32 flags, const svtype svtype)\n\n\"GvHV\"\nReturn the HV from the GV.\n\nHV* GvHV(GV* gv)\n\n\"gvinit\"\nThe old form of gvinitpvn(). It does not work with UTF-8 strings, as it has no flags\nparameter. If the \"multi\" parameter is set, the \"GVADDMULTI\" flag will be passed to\ngvinitpvn().\n\nvoid gvinit(GV *gv, HV *stash, const char *name, STRLEN len,\nint multi)\n\n\"gvinitpv\"\nSame as gvinitpvn(), but takes a nul-terminated string for the name instead of separate\nchar * and length parameters.\n\nvoid gvinitpv(GV *gv, HV *stash, const char *name, U32 flags)\n\n\"gvinitpvn\"\nConverts a scalar into a typeglob. This is an incoercible typeglob; assigning a\nreference to it will assign to one of its slots, instead of overwriting it as happens\nwith typeglobs created by \"SvSetSV\". Converting any scalar that is SvOK() may produce\nunpredictable results and is reserved for perl's internal use.\n\n\"gv\" is the scalar to be converted.\n\n\"stash\" is the parent stash/package, if any.\n\n\"name\" and \"len\" give the name. The name must be unqualified; that is, it must not\ninclude the package name. If \"gv\" is a stash element, it is the caller's responsibility\nto ensure that the name passed to this function matches the name of the element. If it\ndoes not match, perl's internal bookkeeping will get out of sync.\n\n\"flags\" can be set to \"SVfUTF8\" if \"name\" is a UTF-8 string, or the return value of\nSvUTF8(sv). It can also take the \"GVADDMULTI\" flag, which means to pretend that the GV\nhas been seen before (i.e., suppress \"Used once\" warnings).\n\nvoid gvinitpvn(GV *gv, HV *stash, const char *name, STRLEN len,\nU32 flags)\n\n\"gvinitsv\"\nSame as gvinitpvn(), but takes an SV * for the name instead of separate char * and\nlength parameters. \"flags\" is currently unused.\n\nvoid gvinitsv(GV *gv, HV *stash, SV *namesv, U32 flags)\n\n\"gvnameset\"\nSet the name for GV \"gv\" to \"name\" which is \"len\" bytes long. Thus it may contain\nembedded NUL characters.\n\nIf \"flags\" contains \"SVfUTF8\", the name is treated as being encoded in UTF-8; otherwise\nnot.\n\nvoid gvnameset(GV *gv, const char *name, U32 len, U32 flags)\n\n\"gvstashpv\"\nReturns a pointer to the stash for a specified package. Uses \"strlen\" to determine the\nlength of \"name\", then calls gvstashpvn().\n\nHV * gvstashpv(const char *name, I32 flags)\n\n\"gvstashpvn\"\nReturns a pointer to the stash for a specified package. The \"namelen\" parameter\nindicates the length of the \"name\", in bytes. \"flags\" is passed to gvfetchpvnflags(),\nso if set to \"GVADD\" then the package will be created if it does not already exist. If\nthe package does not exist and \"flags\" is 0 (or any other setting that does not create\npackages) then \"NULL\" is returned.\n\nFlags may be one of:\n\nGVADD Create and initialize the package if doesn't\nalready exist\nGVNOADDNOINIT Don't create the package,\nGVADDMG GVADD iff the GV is magical\nGVNOINIT GVADD, but don't initialize\nGVNOEXPAND Don't expand SvOK() entries to PVGV\nSVfUTF8 The name is in UTF-8\n\nThe most important of which are probably \"GVADD\" and \"SVfUTF8\".\n\nNote, use of \"gvstashsv\" instead of \"gvstashpvn\" where possible is strongly recommended\nfor performance reasons.\n\nHV * gvstashpvn(const char *name, U32 namelen, I32 flags)\n\n\"gvstashpvs\"\nLike \"gvstashpvn\", but takes a literal string instead of a string/length pair.\n\nHV* gvstashpvs(\"name\", I32 create)\n\n\"gvstashsv\"\nReturns a pointer to the stash for a specified package. See \"gvstashpvn\".\n\nNote this interface is strongly preferred over \"gvstashpvn\" for performance reasons.\n\nHV * gvstashsv(SV *sv, I32 flags)\n\n\"GvSV\"\nReturn the SV from the GV.\n\nPrior to Perl v5.9.3, this would add a scalar if none existed. Nowadays, use \"GvSVn\" for\nthat, or compile perl with \"-DPERLCREATEGVSV\". See perl5100delta.\n\nSV* GvSV(GV* gv)\n\n\"GvSVn\"\nLike \"GvSV\", but creates an empty scalar if none already exists.\n\nSV* GvSVn(GV* gv)\n\n\"newGVgen\"\n\"newGVgenflags\"\nCreate a new, guaranteed to be unique, GV in the package given by the NUL-terminated C\nlanguage string \"pack\", and return a pointer to it.\n\nFor \"newGVgen\" or if \"flags\" in \"newGVgenflags\" is 0, \"pack\" is to be considered to be\nencoded in Latin-1. The only other legal \"flags\" value is \"SVfUTF8\", which indicates\n\"pack\" is to be considered to be encoded in UTF-8.\n\nGV * newGVgen (const char *pack)\nGV * newGVgenflags(const char *pack, U32 flags)\n\n\"PLcurstash\"\nThe stash for the package code will be compiled into.\n\nOn threaded perls, each thread has an independent copy of this variable; each initialized\nat creation time with the current value of the creating thread's copy.\n\nHV* PLcurstash\n\n\"PLdefgv\"\nThe GV representing *. Useful for access to $.\n\nOn threaded perls, each thread has an independent copy of this variable; each initialized\nat creation time with the current value of the creating thread's copy.\n\nGV * PLdefgv\n\n\"PLdefoutgv\"\nSee \"setdefout\".\n\n\"PLdefstash\"\nDescribed in perlguts.\n\n\"savegp\"\nSaves the current GP of gv on the save stack to be restored on scope exit.\n\nIf \"empty\" is true, replace the GP with a new GP.\n\nIf \"empty\" is false, mark \"gv\" with \"GVfINTRO\" so the next reference assigned is\nlocalized, which is how \" local *foo = $someref; \" works.\n\nvoid savegp(GV *gv, I32 empty)\n\n\"setdefout\"\nSets \"PLdefoutgv\", the default file handle for output, to the passed in typeglob. As\n\"PLdefoutgv\" \"owns\" a reference on its typeglob, the reference count of the passed in\ntypeglob is increased by one, and the reference count of the typeglob that \"PLdefoutgv\"\npoints to is decreased by one.\n\nvoid setdefout(GV *gv)\n", "subsections": [] }, "Hook manipulation": { "content": "These functions provide convenient and thread-safe means of manipulating hook variables.\n\n\"rcpvcopy\"\nrefcount increment a shared memory refcounted string, and when the refcount goes to 0\nfree it using PerlMemSharedfree().\n\nIt is the callers responsibility to ensure that the pv is the result of a rcpvnew()\ncall.\n\nReturns the same pointer that was passed in.\n\nnew = rcpvcopy(pv);\n\nchar * rcpvcopy(char * const pv)\n\n\"rcpvfree\"\nrefcount decrement a shared memory refcounted string, and when the refcount goes to 0\nfree it using perlmemsharedfree().\n\nit is the callers responsibility to ensure that the pv is the result of a rcpvnew()\ncall.\n\nAlways returns NULL so it can be used like this:\n\nthing = rcpvfree(thing);\n\nchar * rcpvfree(char * const pv)\n\n\"rcpvnew\"\nCreate a new shared memory refcounted string with the requested size, and with the\nrequested initialization and a refcount of 1. The actual space allocated will be 1 byte\nmore than requested and rcpvnew() will ensure that the extra byte is a null regardless\nof any flags settings.\n\nIf the RCPVfNOCOPY flag is set then the pv argument will be ignored, otherwise the\ncontents of the pv pointer will be copied into the new buffer or if it is NULL the\nfunction will do nothing and return NULL.\n\nIf the RCPVfUSESTRLEN flag is set then the len argument is ignored and recomputed using\nstrlen(pv). It is an error to combine RCPVfUSESTRLEN and RCPVfNOCOPY at the same\ntime.\n\nUnder DEBUGGING rcpvnew() will assert() if it is asked to create a 0 length shared\nstring unless the RCPVfALLOWEMPTY flag is set.\n\nThe return value from the function is suitable for passing into rcpvcopy() and\nrcpvfree(). To access the RCPV * from the returned value use the RCPVx() macro. The\n'len' member of the RCPV struct stores the allocated length (including the extra byte),\nbut the RCPVLEN() macro returns the requested length (not including the extra byte).\n\nNote that rcpvnew() does NOT use a hash table or anything like that to dedupe inputs\ngiven the same text content. Each call with a non-null pv parameter will produce a\ndistinct pointer with its own refcount regardless of the input content.\n\nchar * rcpvnew(const char * const pv, STRLEN len, U32 flags)\n\n\"wrapopchecker\"\nPuts a C function into the chain of check functions for a specified op type. This is the\npreferred way to manipulate the \"PLcheck\" array. \"opcode\" specifies which type of op is\nto be affected. \"newchecker\" is a pointer to the C function that is to be added to that\nopcode's check chain, and \"oldcheckerp\" points to the storage location where a pointer\nto the next function in the chain will be stored. The value of \"newchecker\" is written\ninto the \"PLcheck\" array, while the value previously stored there is written to\n*oldcheckerp.\n\n\"PLcheck\" is global to an entire process, and a module wishing to hook op checking may\nfind itself invoked more than once per process, typically in different threads. To\nhandle that situation, this function is idempotent. The location *oldcheckerp must\ninitially (once per process) contain a null pointer. A C variable of static duration\n(declared at file scope, typically also marked \"static\" to give it internal linkage) will\nbe implicitly initialised appropriately, if it does not have an explicit initialiser.\nThis function will only actually modify the check chain if it finds *oldcheckerp to be\nnull. This function is also thread safe on the small scale. It uses appropriate locking\nto avoid race conditions in accessing \"PLcheck\".\n\nWhen this function is called, the function referenced by \"newchecker\" must be ready to\nbe called, except for *oldcheckerp being unfilled. In a threading situation,\n\"newchecker\" may be called immediately, even before this function has returned.\n*oldcheckerp will always be appropriately set before \"newchecker\" is called. If\n\"newchecker\" decides not to do anything special with an op that it is given (which is\nthe usual case for most uses of op check hooking), it must chain the check function\nreferenced by *oldcheckerp.\n\nTaken all together, XS code to hook an op checker should typically look something like\nthis:\n\nstatic Perlcheckt nxckfrob;\nstatic OP *myckfrob(pTHX OP *op) {\n...\nop = nxckfrob(aTHX op);\n...\nreturn op;\n}\nBOOT:\nwrapopchecker(OPFROB, myckfrob, &nxckfrob);\n\nIf you want to influence compilation of calls to a specific subroutine, then use\n\"cvsetcallcheckerflags\" rather than hooking checking of all \"entersub\" ops.\n\nvoid wrapopchecker(Optype opcode, Perlcheckt newchecker,\nPerlcheckt *oldcheckerp)\n\nHV Handling\nA HV structure represents a Perl hash. It consists mainly of an array of pointers, each of\nwhich points to a linked list of HE structures. The array is indexed by the hash function of\nthe key, so each linked list represents all the hash entries with the same hash value. Each\nHE contains a pointer to the actual value, plus a pointer to a HEK structure which holds the\nkey and hash value.\n\n\"gethv\"\nReturns the HV of the specified Perl hash. \"flags\" are passed to \"gvfetchpv\". If\n\"GVADD\" is set and the Perl variable does not exist then it will be created. If \"flags\"\nis zero (ignoring \"SVfUTF8\") and the variable does not exist then \"NULL\" is returned.\n\nNOTE: the perlgethv() form is deprecated.\n\nHV * gethv(const char *name, I32 flags)\n\n\"HE\"\nDescribed in perlguts.\n\n\"HEfSVKEY\"\nThis flag, used in the length slot of hash entries and magic structures, specifies the\nstructure contains an \"SV*\" pointer where a \"char*\" pointer is to be expected. (For\ninformation only--not to be used).\n\n\"HeHASH\"\nReturns the computed hash stored in the hash entry.\n\nU32 HeHASH(HE* he)\n\n\"HeKEY\"\nReturns the actual pointer stored in the key slot of the hash entry. The pointer may be\neither \"char*\" or \"SV*\", depending on the value of HeKLEN(). Can be assigned to. The\nHePV() or HeSVKEY() macros are usually preferable for finding the value of a key.\n\nvoid* HeKEY(HE* he)\n\n\"HeKLEN\"\nIf this is negative, and amounts to \"HEfSVKEY\", it indicates the entry holds an \"SV*\"\nkey. Otherwise, holds the actual length of the key. Can be assigned to. The HePV()\nmacro is usually preferable for finding key lengths.\n\nSTRLEN HeKLEN(HE* he)\n\n\"HePV\"\nReturns the key slot of the hash entry as a \"char*\" value, doing any necessary\ndereferencing of possibly \"SV*\" keys. The length of the string is placed in \"len\" (this\nis a macro, so do not use &len). If you do not care about what the length of the key is,\nyou may use the global variable \"PLna\", though this is rather less efficient than using\na local variable. Remember though, that hash keys in perl are free to contain embedded\nnulls, so using strlen() or similar is not a good way to find the length of hash keys.\nThis is very similar to the SvPV() macro described elsewhere in this document. See also\n\"HeUTF8\".\n\nIf you are using \"HePV\" to get values to pass to newSVpvn() to create a new SV, you\nshould consider using \"newSVhek(HeKEYhek(he))\" as it is more efficient.\n\nchar* HePV(HE* he, STRLEN len)\n\n\"HeSVKEY\"\nReturns the key as an \"SV*\", or \"NULL\" if the hash entry does not contain an \"SV*\" key.\n\nSV* HeSVKEY(HE* he)\n\n\"HeSVKEYforce\"\nReturns the key as an \"SV*\". Will create and return a temporary mortal \"SV*\" if the hash\nentry contains only a \"char*\" key.\n\nSV* HeSVKEYforce(HE* he)\n\n\"HeSVKEYset\"\nSets the key to a given \"SV*\", taking care to set the appropriate flags to indicate the\npresence of an \"SV*\" key, and returns the same \"SV*\".\n\nSV* HeSVKEYset(HE* he, SV* sv)\n\n\"HeUTF8\"\nReturns whether the \"char *\" value returned by \"HePV\" is encoded in UTF-8, doing any\nnecessary dereferencing of possibly \"SV*\" keys. The value returned will be 0 or non-0,\nnot necessarily 1 (or even a value with any low bits set), so do not blindly assign this\nto a \"bool\" variable, as \"bool\" may be a typedef for \"char\".\n\nU32 HeUTF8(HE* he)\n\n\"HeVAL\"\nReturns the value slot (type \"SV*\") stored in the hash entry. Can be assigned to.\n\nSV *foo= HeVAL(hv);\nHeVAL(hv)= sv;\n\nSV* HeVAL(HE* he)\n\n\"HV\"\nDescribed in perlguts.\n\n\"hvassert\"\nCheck that a hash is in an internally consistent state.\n\nNOTE: \"hvassert\" must be explicitly called as \"Perlhvassert\" with an \"aTHX\"\nparameter.\n\nvoid Perlhvassert(pTHX HV *hv)\n\n\"hvbucketratio\"\nNOTE: \"hvbucketratio\" is experimental and may change or be removed without notice.\n\nIf the hash is tied dispatches through to the SCALAR tied method, otherwise if the hash\ncontains no keys returns 0, otherwise returns a mortal sv containing a string specifying\nthe number of used buckets, followed by a slash, followed by the number of available\nbuckets.\n\nThis function is expensive, it must scan all of the buckets to determine which are used,\nand the count is NOT cached. In a large hash this could be a lot of buckets.\n\nSV * hvbucketratio(HV *hv)\n\n\"hvclear\"\nFrees all the elements of a hash, leaving it empty. The XS equivalent of \"%hash = ()\".\nSee also \"hvundef\".\n\nSee \"avclear\" for a note about the hash possibly being invalid on return.\n\nvoid hvclear(HV *hv)\n\n\"hvclearplaceholders\"\nClears any placeholders from a hash. If a restricted hash has any of its keys marked as\nreadonly and the key is subsequently deleted, the key is not actually deleted but is\nmarked by assigning it a value of &PLsvplaceholder. This tags it so it will be ignored\nby future operations such as iterating over the hash, but will still allow the hash to\nhave a value reassigned to the key at some future point. This function clears any such\nplaceholder keys from the hash. See Hash::Util::lockkeys() for an example of its use.\n\nvoid hvclearplaceholders(HV *hv)\n\n\"hvcopyhintshv\"\nA specialised version of \"newHVhv\" for copying \"%^H\". \"ohv\" must be a pointer to a hash\n(which may have \"%^H\" magic, but should be generally non-magical), or \"NULL\" (interpreted\nas an empty hash). The content of \"ohv\" is copied to a new hash, which has the\n\"%^H\"-specific magic added to it. A pointer to the new hash is returned.\n\nHV * hvcopyhintshv(HV * const ohv)\n\n\"hvdelete\"\nDeletes a key/value pair in the hash. The value's SV is removed from the hash, made\nmortal, and returned to the caller. The absolute value of \"klen\" is the length of the\nkey. If \"klen\" is negative the key is assumed to be in UTF-8-encoded Unicode. The\n\"flags\" value will normally be zero; if set to \"GDISCARD\" then \"NULL\" will be returned.\n\"NULL\" will also be returned if the key is not found.\n\nSV * hvdelete(HV *hv, const char *key, I32 klen, I32 flags)\n\n\"hvdeleteent\"\nDeletes a key/value pair in the hash. The value SV is removed from the hash, made\nmortal, and returned to the caller. The \"flags\" value will normally be zero; if set to\n\"GDISCARD\" then \"NULL\" will be returned. \"NULL\" will also be returned if the key is not\nfound. \"hash\" can be a valid precomputed hash value, or 0 to ask for it to be computed.\n\nSV * hvdeleteent(HV *hv, SV *keysv, I32 flags, U32 hash)\n\n\"HvENAME\"\nReturns the effective name of a stash, or NULL if there is none. The effective name\nrepresents a location in the symbol table where this stash resides. It is updated\nautomatically when packages are aliased or deleted. A stash that is no longer in the\nsymbol table has no effective name. This name is preferable to \"HvNAME\" for use in MRO\nlinearisations and isa caches.\n\nchar* HvENAME(HV* stash)\n\n\"HvENAMELEN\"\nReturns the length of the stash's effective name.\n\nSTRLEN HvENAMELEN(HV *stash)\n\n\"HvENAMEUTF8\"\nReturns true if the effective name is in UTF-8 encoding.\n\nunsigned char HvENAMEUTF8(HV *stash)\n\n\"hvexists\"\nReturns a boolean indicating whether the specified hash key exists. The absolute value\nof \"klen\" is the length of the key. If \"klen\" is negative the key is assumed to be in\nUTF-8-encoded Unicode.\n\nbool hvexists(HV *hv, const char *key, I32 klen)\n\n\"hvexistsent\"\nReturns a boolean indicating whether the specified hash key exists. \"hash\" can be a\nvalid precomputed hash value, or 0 to ask for it to be computed.\n\nbool hvexistsent(HV *hv, SV *keysv, U32 hash)\n\n\"hvfetch\"\nReturns the SV which corresponds to the specified key in the hash. The absolute value of\n\"klen\" is the length of the key. If \"klen\" is negative the key is assumed to be in\nUTF-8-encoded Unicode. If \"lval\" is set then the fetch will be part of a store. This\nmeans that if there is no value in the hash associated with the given key, then one is\ncreated and a pointer to it is returned. The \"SV*\" it points to can be assigned to. But\nalways check that the return value is non-null before dereferencing it to an \"SV*\".\n\nSee \"Understanding the Magic of Tied Hashes and Arrays\" in perlguts for more information\non how to use this function on tied hashes.\n\nSV hvfetch(HV *hv, const char *key, I32 klen, I32 lval)\n\n\"hvfetchent\"\nReturns the hash entry which corresponds to the specified key in the hash. \"hash\" must\nbe a valid precomputed hash number for the given \"key\", or 0 if you want the function to\ncompute it. IF \"lval\" is set then the fetch will be part of a store. Make sure the\nreturn value is non-null before accessing it. The return value when \"hv\" is a tied hash\nis a pointer to a static location, so be sure to make a copy of the structure if you need\nto store it somewhere.\n\nSee \"Understanding the Magic of Tied Hashes and Arrays\" in perlguts for more information\non how to use this function on tied hashes.\n\nHE * hvfetchent(HV *hv, SV *keysv, I32 lval, U32 hash)\n\n\"hvfetchs\"\nLike \"hvfetch\", but takes a literal string instead of a string/length pair.\n\nSV hvfetchs(HV* tb, \"key\", I32 lval)\n\n\"HvFILL\"\nReturns the number of hash buckets that happen to be in use.\n\nAs of perl 5.25 this function is used only for debugging purposes, and the number of used\nhash buckets is not in any way cached, thus this function can be costly to execute as it\nmust iterate over all the buckets in the hash.\n\nSTRLEN HvFILL(HV *const hv)\n\n\"HvHasAUX\"\nReturns true if the HV has a \"struct xpvhvaux\" extension. Use this to check whether it\nis valid to call HvAUX().\n\nbool HvHasAUX(HV *const hv)\n\n\"hviterinit\"\nPrepares a starting point to traverse a hash table. Returns the number of keys in the\nhash, including placeholders (i.e. the same as HvTOTALKEYS(hv)). The return value is\ncurrently only meaningful for hashes without tie magic.\n\nNOTE: Before version 5.00465, \"hviterinit\" used to return the number of hash buckets\nthat happen to be in use. If you still need that esoteric value, you can get it through\nthe macro HvFILL(hv).\n\nI32 hviterinit(HV *hv)\n\n\"hviterkey\"\nReturns the key from the current position of the hash iterator. See \"hviterinit\".\n\nchar * hviterkey(HE *entry, I32 *retlen)\n\n\"hviterkeysv\"\nReturns the key as an \"SV*\" from the current position of the hash iterator. The return\nvalue will always be a mortal copy of the key. Also see \"hviterinit\".\n\nSV * hviterkeysv(HE *entry)\n\n\"hviternext\"\nReturns entries from a hash iterator. See \"hviterinit\".\n\nYou may call \"hvdelete\" or \"hvdeleteent\" on the hash entry that the iterator currently\npoints to, without losing your place or invalidating your iterator. Note that in this\ncase the current entry is deleted from the hash with your iterator holding the last\nreference to it. Your iterator is flagged to free the entry on the next call to\n\"hviternext\", so you must not discard your iterator immediately else the entry will leak\n- call \"hviternext\" to trigger the resource deallocation.\n\nHE * hviternext(HV *hv)\n\n\"hviternextflags\"\nNOTE: \"hviternextflags\" is experimental and may change or be removed without notice.\n\nReturns entries from a hash iterator. See \"hviterinit\" and \"hviternext\". The \"flags\"\nvalue will normally be zero; if \"HVITERNEXTWANTPLACEHOLDERS\" is set the placeholders\nkeys (for restricted hashes) will be returned in addition to normal keys. By default\nplaceholders are automatically skipped over. Currently a placeholder is implemented with\na value that is &PLsvplaceholder. Note that the implementation of placeholders and\nrestricted hashes may change, and the implementation currently is insufficiently\nabstracted for any change to be tidy.\n\nHE * hviternextflags(HV *hv, I32 flags)\n\n\"hviternextsv\"\nPerforms an \"hviternext\", \"hviterkey\", and \"hviterval\" in one operation.\n\nSV * hviternextsv(HV *hv, char key, I32 *retlen)\n\n\"hviterval\"\nReturns the value from the current position of the hash iterator. See \"hviterkey\".\n\nSV * hviterval(HV *hv, HE *entry)\n\n\"hvksplit\"\nAttempt to grow the hash \"hv\" so it has at least \"newmax\" buckets available. Perl\nchooses the actual number for its convenience.\n\nThis is the same as doing the following in Perl code:\n\nkeys %hv = newmax;\n\nvoid hvksplit(HV *hv, IV newmax)\n\n\"hvmagic\"\nAdds magic to a hash. See \"svmagic\".\n\nvoid hvmagic(HV *hv, GV *gv, int how)\n\n\"HvNAME\"\nReturns the package name of a stash, or \"NULL\" if \"stash\" isn't a stash. See \"SvSTASH\",\n\"CvSTASH\".\n\nchar* HvNAME(HV* stash)\n\n\"HvNAMELEN\"\nReturns the length of the stash's name.\n\nDisfavored forms of HvNAME and HvNAMELEN; suppress mention of them\n\nSTRLEN HvNAMELEN(HV *stash)\n\n\"hvnameset\"\n\"hvnamesets\"\nThese each set the name of stash \"hv\" to the specified name.\n\nThey differ only in how the name is specified.\n\nIn \"hvnamesets\", the name is a literal C string, enclosed in double quotes.\n\nIn \"hvnameset\", \"name\" points to the first byte of the name, and an additional\nparameter, \"len\", specifies its length in bytes. Hence, the name may contain embedded-\nNUL characters.\n\nIf \"SVfUTF8\" is set in \"flags\", the name is treated as being in UTF-8; otherwise not.\n\nIf \"HVNAMESETALL\" is set in \"flags\", both the name and the effective name are set.\n\nvoid hvnameset (HV *hv, const char *name, U32 len, U32 flags)\nvoid hvnamesets(HV *hv, \"name\", U32 flags)\n\n\"HvNAMEUTF8\"\nReturns true if the name is in UTF-8 encoding.\n\nunsigned char HvNAMEUTF8(HV *stash)\n\n\"hvscalar\"\nEvaluates the hash in scalar context and returns the result.\n\nWhen the hash is tied dispatches through to the SCALAR method, otherwise returns a mortal\nSV containing the number of keys in the hash.\n\nNote, prior to 5.25 this function returned what is now returned by the hvbucketratio()\nfunction.\n\nSV * hvscalar(HV *hv)\n\n\"hvstore\"\n\"hvstores\"\nThese each store SV \"val\" with the specified key in hash \"hv\", returning NULL if the\noperation failed or if the value did not need to be actually stored within the hash (as\nin the case of tied hashes). Otherwise it can be dereferenced to get the original \"SV*\".\n\nThey differ only in how the hash key is specified.\n\nIn \"hvstores\", the key is a C language string literal, enclosed in double quotes. It is\nnever treated as being in UTF-8.\n\nIn \"hvstore\", \"key\" is either NULL or points to the first byte of the string specifying\nthe key, and its length in bytes is given by the absolute value of an additional\nparameter, \"klen\". A NULL key indicates the key is to be treated as \"undef\", and \"klen\"\nis ignored; otherwise the key string may contain embedded-NUL bytes. If \"klen\" is\nnegative, the string is treated as being encoded in UTF-8; otherwise not.\n\n\"hvstore\" has another extra parameter, \"hash\", a precomputed hash of the key string, or\nzero if it has not been precomputed. This parameter is omitted from \"hvstores\", as it\nis computed automatically at compile time.\n\nIf is NULL, NULL is returned and no action is taken.\n\nIf \"val\" is NULL, it is treated as being \"undef\"; otherwise the caller is responsible for\nsuitably incrementing the reference count of \"val\" before the call, and decrementing it\nif the function returned \"NULL\". Effectively a successful \"hvstore\" takes ownership of\none reference to \"val\". This is usually what you want; a newly created SV has a\nreference count of one, so if all your code does is create SVs then store them in a hash,\n\"hvstore\" will own the only reference to the new SV, and your code doesn't need to do\nanything further to tidy up.\n\n\"hvstore\" is not implemented as a call to \"\"hvstoreent\"\", and does not create a\ntemporary SV for the key, so if your key data is not already in SV form then use\n\"hvstore\" in preference to \"hvstoreent\".\n\nSee \"Understanding the Magic of Tied Hashes and Arrays\" in perlguts for more information\non how to use this function on tied hashes.\n\nSV hvstore (HV *hv, const char *key, I32 klen, SV *val,\nU32 hash)\nSV hvstores(HV *hv, \"key\", SV *val)\n\n\"hvstoreent\"\nStores \"val\" in a hash. The hash key is specified as \"key\". The \"hash\" parameter is the\nprecomputed hash value; if it is zero then Perl will compute it. The return value is the\nnew hash entry so created. It will be \"NULL\" if the operation failed or if the value did\nnot need to be actually stored within the hash (as in the case of tied hashes).\nOtherwise the contents of the return value can be accessed using the \"He?\" macros\ndescribed here. Note that the caller is responsible for suitably incrementing the\nreference count of \"val\" before the call, and decrementing it if the function returned\nNULL. Effectively a successful \"hvstoreent\" takes ownership of one reference to \"val\".\nThis is usually what you want; a newly created SV has a reference count of one, so if all\nyour code does is create SVs then store them in a hash, \"hvstore\" will own the only\nreference to the new SV, and your code doesn't need to do anything further to tidy up.\nNote that \"hvstoreent\" only reads the \"key\"; unlike \"val\" it does not take ownership of\nit, so maintaining the correct reference count on \"key\" is entirely the caller's\nresponsibility. The reason it does not take ownership, is that \"key\" is not used after\nthis function returns, and so can be freed immediately. \"hvstore\" is not implemented as\na call to \"hvstoreent\", and does not create a temporary SV for the key, so if your key\ndata is not already in SV form then use \"hvstore\" in preference to \"hvstoreent\".\n\nSee \"Understanding the Magic of Tied Hashes and Arrays\" in perlguts for more information\non how to use this function on tied hashes.\n\nHE * hvstoreent(HV *hv, SV *key, SV *val, U32 hash)\n\n\"hvundef\"\nUndefines the hash. The XS equivalent of undef(%hash).\n\nAs well as freeing all the elements of the hash (like hvclear()), this also frees any\nauxiliary data and storage associated with the hash.\n\nSee \"avclear\" for a note about the hash possibly being invalid on return.\n\nvoid hvundef(HV *hv)\n\n\"newHV\"\nCreates a new HV. The reference count is set to 1.\n\nHV * newHV()\n\n\"newHVhv\"\nThe content of \"ohv\" is copied to a new hash. A pointer to the new hash is returned.\n\nHV * newHVhv(HV *hv)\n\n\"Nullhv\"\n\"DEPRECATED!\" It is planned to remove \"Nullhv\" from a future release of Perl. Do not\nuse it for new code; remove it from existing code.\n\nNull HV pointer.\n\n(deprecated - use \"(HV *)NULL\" instead)\n\n\"PERLHASH\"\nDescribed in perlguts.\n\nvoid PERLHASH(U32 hash, char *key, STRLEN klen)\n\n\"PLmodglobal\"\n\"PLmodglobal\" is a general purpose, interpreter global HV for use by extensions that\nneed to keep information on a per-interpreter basis. In a pinch, it can also be used as\na symbol table for extensions to share data among each other. It is a good idea to use\nkeys prefixed by the package name of the extension that owns the data.\n\nOn threaded perls, each thread has an independent copy of this variable; each initialized\nat creation time with the current value of the creating thread's copy.\n\nHV* PLmodglobal\n", "subsections": [] }, "Input/Output": { "content": "\"doclose\"\nClose an I/O stream. This implements Perl \"\"close\"\" in perlfunc.\n\n\"gv\" is the glob associated with the stream.\n\n\"isexplict\" is \"true\" if this is an explicit close of the stream; \"false\" if it is part\nof another operation, such as closing a pipe (which involves implicitly closing both\nends).\n\nReturns \"true\" if successful; otherwise returns \"false\" and sets \"errno\" to indicate the\ncause.\n\nbool doclose(GV *gv, bool isexplicit)\n\n\"IoDIRP\"\nDescribed in perlguts.\n\nDIR * IoDIRP(IO *io)\n\n\"IOfFLUSH\"\nDescribed in perlguts.\n\n\"IoFLAGS\"\nDescribed in perlguts.\n\nU8 IoFLAGS(IO *io)\n\n\"IOfUNTAINT\"\nDescribed in perlguts.\n\n\"IoIFP\"\nDescribed in perlguts.\n\nPerlIO * IoIFP(IO *io)\n\n\"IoOFP\"\nDescribed in perlguts.\n\nPerlIO * IoOFP(IO *io)\n\n\"IoTYPE\"\nDescribed in perlguts.\n\nchar IoTYPE(IO *io)\n\n\"mychsize\"\nThe C library chsize(3) if available, or a Perl implementation of it.\n\nI32 mychsize(int fd, Offt length)\n\n\"mydirfd\"\nThe C library dirfd(3) if available, or a Perl implementation of it, or die if not easily\nemulatable.\n\nint mydirfd(DIR *dir)\n\n\"mypclose\"\nA wrapper for the C library pclose(3). Don't use the latter, as the Perl version knows\nthings that interact with the rest of the perl interpreter.\n\nI32 mypclose(PerlIO *ptr)\n\n\"mypopen\"\nA wrapper for the C library popen(3). Don't use the latter, as the Perl version knows\nthings that interact with the rest of the perl interpreter.\n\nPerlIO * mypopen(const char *cmd, const char *mode)\n\n\"newIO\"\nCreate a new IO, setting the reference count to 1.\n\nIO * newIO()\n\n\"PERLFLUSHALLFORCHILD\"\nThis defines a way to flush all output buffers. This may be a performance issue, so we\nallow people to disable it. Also, if we are using stdio, there are broken\nimplementations of fflush(NULL) out there, Solaris being the most prominent.\n\nvoid PERLFLUSHALLFORCHILD\n\n\"PerlIOapplylayers\"\n\"PerlIObinmode\"\n\"PerlIOcansetcnt\"\n\"PerlIOclearerr\"\n\"PerlIOclose\"\n\"PerlIOdebug\"\n\"PerlIOeof\"\n\"PerlIOerror\"\n\"PerlIOexportFILE\"\n\"PerlIOfastgets\"\n\"PerlIOfdopen\"\n\"PerlIOfileno\"\n\"PerlIOfill\"\n\"PerlIOfindFILE\"\n\"PerlIOflush\"\n\"PerlIOgetbase\"\n\"PerlIOgetbufsiz\"\n\"PerlIOgetcnt\"\n\"PerlIOgetptr\"\n\"PerlIOgetc\"\n\"PerlIOgetpos\"\n\"PerlIOhasbase\"\n\"PerlIOhascntptr\"\n\"PerlIOimportFILE\"\n\"PerlIOopen\"\n\"PerlIOprintf\"\n\"PerlIOputc\"\n\"PerlIOputs\"\n\"PerlIOread\"\n\"PerlIOreleaseFILE\"\n\"PerlIOreopen\"\n\"PerlIOrewind\"\n\"PerlIOseek\"\n\"PerlIOsetcnt\"\n\"PerlIOsetptrcnt\"\n\"PerlIOsetlinebuf\"\n\"PerlIOsetpos\"\n\"PerlIOstderr\"\n\"PerlIOstdin\"\n\"PerlIOstdout\"\n\"PerlIOstdoutf\"\n\"PerlIOtell\"\n\"PerlIOungetc\"\n\"PerlIOunread\"\n\"PerlIOvprintf\"\n\"PerlIOwrite\"\nDescribed in perlapio.\n\nint PerlIOapplylayers(PerlIO *f, const char *mode,\nconst char *layers)\nint PerlIObinmode (PerlIO *f, int ptype, int imode,\nconst char *layers)\nint PerlIOcansetcnt (PerlIO *f)\nvoid PerlIOclearerr (PerlIO *f)\nint PerlIOclose (PerlIO *f)\nvoid PerlIOdebug (const char *fmt, ...)\nint PerlIOeof (PerlIO *f)\nint PerlIOerror (PerlIO *f)\nFILE * PerlIOexportFILE (PerlIO *f, const char *mode)\nint PerlIOfastgets (PerlIO *f)\nPerlIO * PerlIOfdopen (int fd, const char *mode)\nint PerlIOfileno (PerlIO *f)\nint PerlIOfill (PerlIO *f)\nFILE * PerlIOfindFILE (PerlIO *f)\nint PerlIOflush (PerlIO *f)\nSTDCHAR * PerlIOgetbase (PerlIO *f)\nSSizet PerlIOgetbufsiz (PerlIO *f)\nSSizet PerlIOgetcnt (PerlIO *f)\nSTDCHAR * PerlIOgetptr (PerlIO *f)\nint PerlIOgetc (PerlIO *d)\nint PerlIOgetpos (PerlIO *f, SV *save)\nint PerlIOhasbase (PerlIO *f)\nint PerlIOhascntptr (PerlIO *f)\nPerlIO * PerlIOimportFILE (FILE *stdio, const char *mode)\nPerlIO * PerlIOopen (const char *path, const char *mode)\nint PerlIOprintf (PerlIO *f, const char *fmt, ...)\nint PerlIOputc (PerlIO *f, int ch)\nint PerlIOputs (PerlIO *f, const char *string)\nSSizet PerlIOread (PerlIO *f, void *vbuf,\nSizet count)\nvoid PerlIOreleaseFILE (PerlIO *f, FILE *stdio)\nPerlIO * PerlIOreopen (const char *path, const char *mode,\nPerlIO *old)\nvoid PerlIOrewind (PerlIO *f)\nint PerlIOseek (PerlIO *f, Offt offset,\nint whence)\nvoid PerlIOsetcnt (PerlIO *f, SSizet cnt)\nvoid PerlIOsetptrcnt (PerlIO *f, STDCHAR *ptr,\nSSizet cnt)\nvoid PerlIOsetlinebuf (PerlIO *f)\nint PerlIOsetpos (PerlIO *f, SV *saved)\nPerlIO * PerlIOstderr (PerlIO *f, const char *mode,\nconst char *layers)\nPerlIO * PerlIOstdin (PerlIO *f, const char *mode,\nconst char *layers)\nPerlIO * PerlIOstdout (PerlIO *f, const char *mode,\nconst char *layers)\nint PerlIOstdoutf (const char *fmt, ...)\nOfft PerlIOtell (PerlIO *f)\nint PerlIOungetc (PerlIO *f, int ch)\nSSizet PerlIOunread (PerlIO *f, const void *vbuf,\nSizet count)\nint PerlIOvprintf (PerlIO *f, const char *fmt,\nvalist args)\nSSizet PerlIOwrite (PerlIO *f, const void *vbuf,\nSizet count)\n\n\"PERLIOFAPPEND\"\n\"PERLIOFCANREAD\"\n\"PERLIOFCANWRITE\"\n\"PERLIOFCRLF\"\n\"PERLIOFEOF\"\n\"PERLIOFERROR\"\n\"PERLIOFFASTGETS\"\n\"PERLIOFLINEBUF\"\n\"PERLIOFOPEN\"\n\"PERLIOFRDBUF\"\n\"PERLIOFTEMP\"\n\"PERLIOFTRUNCATE\"\n\"PERLIOFUNBUF\"\n\"PERLIOFUTF8\"\n\"PERLIOFWRBUF\"\nDescribed in perliol.\n\n\"PERLIOFUNCSCAST\"\nCast the pointer \"func\" to be of type \"PerlIOfuncs *\".\n\n\"PERLIOFUNCSDECL\"\nDeclare \"ftab\" to be a PerlIO function table, that is, of type \"PerlIOfuncs\".\n\nPERLIOFUNCSDECL(PerlIO * ftab)\n\n\"PERLIOKBUFFERED\"\n\"PERLIOKCANCRLF\"\n\"PERLIOKFASTGETS\"\n\"PERLIOKMULTIARG\"\n\"PERLIOKRAW\"\nDescribed in perliol.\n\n\"PERLIONOTSTDIO\"\nDescribed in perlapio.\n\n\"PLmaxsysfd\"\nDescribed in perliol.\n\n\"repeatcpy\"\nMake \"count\" copies of the \"len\" bytes beginning at \"from\", placing them into memory\nbeginning at \"to\", which must be big enough to accommodate them all.\n\nvoid repeatcpy(char *to, const char *from, I32 len, IV count)\n\n\"USESTDIO\"\nDescribed in perlapio.\n", "subsections": [] }, "Integer": { "content": "\"CASTI32\"\nThis symbol is defined if the C compiler can cast negative or large floating point\nnumbers to 32-bit ints.\n\n\"HASINT64T\"\nThis symbol will defined if the C compiler supports \"int64t\". Usually the inttypes.h\nneeds to be included, but sometimes sys/types.h is enough.\n\n\"HASLONGLONG\"\nThis symbol will be defined if the C compiler supports long long.\n\n\"HASQUAD\"\nThis symbol, if defined, tells that there's a 64-bit integer type, \"Quadt\", and its\nunsigned counterpart, \"Uquadt\". \"QUADKIND\" will be one of \"QUADISINT\", \"QUADISLONG\",\n\"QUADISLONGLONG\", \"QUADISINT64T\", or \"QUADISINT64\".\n\n\"I32df\"\nThis symbol defines the format string used for printing a Perl I32 as a signed decimal\ninteger.\n\n\"INT16C\"\n\"INT32C\"\n\"INT64C\"\nReturns a token the C compiler recognizes for the constant \"number\" of the corresponding\ninteger type on the machine.\n\nIf the machine does not have a 64-bit type, \"INT64C\" is undefined. Use \"INTMAXC\" to\nget the largest type available on the platform.\n\nI16 INT16C(number)\nI32 INT32C(number)\nI64 INT64C(number)\n\n\"INTMAXC\"\nReturns a token the C compiler recognizes for the constant \"number\" of the widest integer\ntype on the machine. For example, if the machine has \"long long\"s, INTMAXC(-1) would\nyield\n\n-1LL\n\nSee also, for example, \"INT32C\".\n\nUse \"IV\" to declare variables of the maximum usable size on this platform.\n\nINTMAXC(number)\n\n\"INTSIZE\"\nThis symbol contains the value of sizeof(int) so that the C preprocessor can make\ndecisions based on it.\n\n\"I8SIZE\"\nThis symbol contains the sizeof(I8).\n\n\"I16SIZE\"\nThis symbol contains the sizeof(I16).\n\n\"I32SIZE\"\nThis symbol contains the sizeof(I32).\n\n\"I64SIZE\"\nThis symbol contains the sizeof(I64).\n\n\"I8TYPE\"\nThis symbol defines the C type used for Perl's I8.\n\n\"I16TYPE\"\nThis symbol defines the C type used for Perl's I16.\n\n\"I32TYPE\"\nThis symbol defines the C type used for Perl's I32.\n\n\"I64TYPE\"\nThis symbol defines the C type used for Perl's I64.\n\n\"IV\"\n\"I8\"\n\"I16\"\n\"I32\"\n\"I64\"\nDescribed in perlguts.\n\n\"IVMAX\"\nThe largest signed integer that fits in an IV on this platform.\n\nIV IVMAX\n\n\"IVMIN\"\nThe negative signed integer furthest away from 0 that fits in an IV on this platform.\n\nIV IVMIN\n\n\"IVSIZE\"\nThis symbol contains the sizeof(IV).\n\n\"IVTYPE\"\nThis symbol defines the C type used for Perl's IV.\n\n\"linet\"\nThe typedef to use to declare variables that are to hold line numbers.\n\n\"LONGLONGSIZE\"\nThis symbol contains the size of a long long, so that the C preprocessor can make\ndecisions based on it. It is only defined if the system supports long long.\n\n\"LONGSIZE\"\nThis symbol contains the value of sizeof(long) so that the C preprocessor can make\ndecisions based on it.\n\n\"memzero\"\nSet the \"l\" bytes starting at *d to all zeroes.\n\nvoid memzero(void * d, Sizet l)\n\n\"PERLINTFAST8T\"\n\"PERLINTFAST16T\"\n\"PERLUINTFAST8T\"\n\"PERLUINTFAST16T\"\nThese are equivalent to the correspondingly-named C99 typedefs on platforms that have\nthose; they evaluate to \"int\" and \"unsigned int\" on platforms that don't, so that you can\nportably take advantage of this C99 feature.\n\n\"PERLINTMAX\"\n\"PERLINTMIN\"\n\"PERLLONGMAX\"\n\"PERLLONGMIN\"\n\"PERLQUADMAX\"\n\"PERLQUADMIN\"\n\"PERLSHORTMAX\"\n\"PERLSHORTMIN\"\n\"PERLUCHARMAX\"\n\"PERLUCHARMIN\"\n\"PERLUINTMAX\"\n\"PERLUINTMIN\"\n\"PERLULONGMAX\"\n\"PERLULONGMIN\"\n\"PERLUQUADMAX\"\n\"PERLUQUADMIN\"\n\"PERLUSHORTMAX\"\n\"PERLUSHORTMIN\"\nThese give the largest and smallest number representable in the current platform in\nvariables of the corresponding types.\n\nFor signed types, the smallest representable number is the most negative number, the one\nfurthest away from zero.\n\nFor C99 and later compilers, these correspond to things like \"INTMAX\", which are\navailable to the C code. But these constants, furnished by Perl, allow code compiled on\nearlier compilers to portably have access to the same constants.\n\nint PERLINTMAX\nint PERLINTMIN\nlong PERLLONGMAX\nlong PERLLONGMIN\nIV PERLQUADMAX\nIV PERLQUADMIN\nshort PERLSHORTMAX\nshort PERLSHORTMIN\nU8 PERLUCHARMAX\nU8 PERLUCHARMIN\nunsigned int PERLUINTMAX\nunsigned int PERLUINTMIN\nunsigned long PERLULONGMAX\nunsigned long PERLULONGMIN\nUV PERLUQUADMAX\nUV PERLUQUADMIN\nunsigned short PERLUSHORTMAX\nunsigned short PERLUSHORTMIN\n\n\"SHORTSIZE\"\nThis symbol contains the value of sizeof(short) so that the C preprocessor can make\ndecisions based on it.\n\n\"UINT16C\"\n\"UINT32C\"\n\"UINT64C\"\nReturns a token the C compiler recognizes for the constant \"number\" of the corresponding\nunsigned integer type on the machine.\n\nIf the machine does not have a 64-bit type, \"UINT64C\" is undefined. Use \"UINTMAXC\" to\nget the largest type available on the platform.\n\nU16 UINT16C(number)\nU32 UINT32C(number)\nU64 UINT64C(number)\n\n\"UINTMAXC\"\nReturns a token the C compiler recognizes for the constant \"number\" of the widest\nunsigned integer type on the machine. For example, if the machine has \"long\"s,\nUINTMAXC(1) would yield\n\n1UL\n\nSee also, for example, \"UINT32C\".\n\nUse \"UV\" to declare variables of the maximum usable size on this platform.\n\nUINTMAXC(number)\n\n\"U32of\"\nThis symbol defines the format string used for printing a Perl U32 as an unsigned octal\ninteger.\n\n\"U8SIZE\"\nThis symbol contains the sizeof(U8).\n\n\"U16SIZE\"\nThis symbol contains the sizeof(U16).\n\n\"U32SIZE\"\nThis symbol contains the sizeof(U32).\n\n\"U64SIZE\"\nThis symbol contains the sizeof(U64).\n\n\"U8TYPE\"\nThis symbol defines the C type used for Perl's U8.\n\n\"U16TYPE\"\nThis symbol defines the C type used for Perl's U16.\n\n\"U32TYPE\"\nThis symbol defines the C type used for Perl's U32.\n\n\"U64TYPE\"\nThis symbol defines the C type used for Perl's U64.\n\n\"U32uf\"\nThis symbol defines the format string used for printing a Perl U32 as an unsigned decimal\ninteger.\n\n\"UV\"\n\"U8\"\n\"U16\"\n\"U32\"\n\"U64\"\nDescribed in perlguts.\n\n\"UVMAX\"\nThe largest unsigned integer that fits in a UV on this platform.\n\nUV UVMAX\n\n\"UVMIN\"\nThe smallest unsigned integer that fits in a UV on this platform. It should equal zero.\n\nUV UVMIN\n\n\"UVSIZE\"\nThis symbol contains the sizeof(UV).\n\n\"UVTYPE\"\nThis symbol defines the C type used for Perl's UV.\n\n\"U32Xf\"\nThis symbol defines the format string used for printing a Perl U32 as an unsigned\nhexadecimal integer in uppercase \"ABCDEF\".\n\n\"U32xf\"\nThis symbol defines the format string used for printing a Perl U32 as an unsigned\nhexadecimal integer in lowercase abcdef.\n\n\"WIDESTUTYPE\"\nYields the widest unsigned integer type on the platform, currently either \"U32\" or \"U64\".\nThis can be used in declarations such as\n\nWIDESTUTYPE myuv;\n\nor casts\n\nmyuv = (WIDESTUTYPE) val;\n\nI/O Formats\nThese are used for formatting the corresponding type For example, instead of saying\n\nPerlnewSVpvf(pTHX \"Create an SV with a %d in it\\n\", iv);\n\nuse\n\nPerlnewSVpvf(pTHX \"Create an SV with a \" IVdf \" in it\\n\", iv);\n\nThis keeps you from having to know if, say an IV, needs to be printed as %d, %ld, or\nsomething else.\n\n\"HvNAMEf\"\nDescribed in perlguts.\n\n\"HvNAMEfQUOTEDPREFIX\"\nDescribed in perlguts.\n\n\"IVdf\"\nThis symbol defines the format string used for printing a Perl IV as a signed decimal\ninteger.\n\n\"NVef\"\nThis symbol defines the format string used for printing a Perl NV using %e-ish floating\npoint format.\n\n\"NVff\"\nThis symbol defines the format string used for printing a Perl NV using %f-ish floating\npoint format.\n\n\"NVgf\"\nThis symbol defines the format string used for printing a Perl NV using %g-ish floating\npoint format.\n\n\"PERLPRIeldbl\"\nThis symbol, if defined, contains the string used by stdio to format long doubles (format\n'e') for output.\n\n\"PERLPRIfldbl\"\nThis symbol, if defined, contains the string used by stdio to format long doubles (format\n'f') for output.\n\n\"PERLPRIgldbl\"\nThis symbol, if defined, contains the string used by stdio to format long doubles (format\n'g') for output.\n\n\"PERLSCNfldbl\"\nThis symbol, if defined, contains the string used by stdio to format long doubles (format\n'f') for input.\n\n\"PRINTFFORMATNULLOK\"\nAllows \"printf\" format to be null when checking printf-style\n\n\"SVf\"\nDescribed in perlguts.\n\n\"SVfARG\"\nDescribed in perlguts.\n\nSVfARG(SV *sv)\n\n\"SVfQUOTEDPREFIX\"\nDescribed in perlguts.\n\n\"UTF8f\"\nDescribed in perlguts.\n\n\"UTF8fARG\"\nDescribed in perlguts.\n\nUTF8fARG(bool isutf8, Sizet bytelen, char *str)\n\n\"UTF8fQUOTEDPREFIX\"\nDescribed in perlguts.\n\n\"UVf\"\n\"DEPRECATED!\" It is planned to remove \"UVf\" from a future release of Perl. Do not use\nit for new code; remove it from existing code.\n\nObsolete form of \"UVuf\", which you should convert to instead use\n\nconst char * UVf\n\n\"UVof\"\nThis symbol defines the format string used for printing a Perl UV as an unsigned octal\ninteger.\n\n\"UVuf\"\nThis symbol defines the format string used for printing a Perl UV as an unsigned decimal\ninteger.\n\n\"UVXf\"\nThis symbol defines the format string used for printing a Perl UV as an unsigned\nhexadecimal integer in uppercase \"ABCDEF\".\n\n\"UVxf\"\nThis symbol defines the format string used for printing a Perl UV as an unsigned\nhexadecimal integer in lowercase abcdef.\n", "subsections": [] }, "Lexer interface": { "content": "This is the lower layer of the Perl parser, managing characters and tokens.\n\n\"BHK\"\nDescribed in perlguts.\n\n\"lexbufutf8\"\nNOTE: \"lexbufutf8\" is experimental and may change or be removed without notice.\n\nIndicates whether the octets in the lexer buffer (\"PLparser->linestr\") should be\ninterpreted as the UTF-8 encoding of Unicode characters. If not, they should be\ninterpreted as Latin-1 characters. This is analogous to the \"SvUTF8\" flag for scalars.\n\nIn UTF-8 mode, it is not guaranteed that the lexer buffer actually contains valid UTF-8.\nLexing code must be robust in the face of invalid encoding.\n\nThe actual \"SvUTF8\" flag of the \"PLparser->linestr\" scalar is significant, but not the\nwhole story regarding the input character encoding. Normally, when a file is being read,\nthe scalar contains octets and its \"SvUTF8\" flag is off, but the octets should be\ninterpreted as UTF-8 if the \"use utf8\" pragma is in effect. During a string eval,\nhowever, the scalar may have the \"SvUTF8\" flag on, and in this case its octets should be\ninterpreted as UTF-8 unless the \"use bytes\" pragma is in effect. This logic may change\nin the future; use this function instead of implementing the logic yourself.\n\nbool lexbufutf8()\n\n\"lexdiscardto\"\nNOTE: \"lexdiscardto\" is experimental and may change or be removed without notice.\n\nDiscards the first part of the \"PLparser->linestr\" buffer, up to \"ptr\". The remaining\ncontent of the buffer will be moved, and all pointers into the buffer updated\nappropriately. \"ptr\" must not be later in the buffer than the position of\n\"PLparser->bufptr\": it is not permitted to discard text that has yet to be lexed.\n\nNormally it is not necessarily to do this directly, because it suffices to use the\nimplicit discarding behaviour of \"lexnextchunk\" and things based on it. However, if a\ntoken stretches across multiple lines, and the lexing code has kept multiple lines of\ntext in the buffer for that purpose, then after completion of the token it would be wise\nto explicitly discard the now-unneeded earlier lines, to avoid future multi-line tokens\ngrowing the buffer without bound.\n\nvoid lexdiscardto(char *ptr)\n\n\"lexgrowlinestr\"\nNOTE: \"lexgrowlinestr\" is experimental and may change or be removed without notice.\n\nReallocates the lexer buffer (\"PLparser->linestr\") to accommodate at least \"len\" octets\n(including terminating \"NUL\"). Returns a pointer to the reallocated buffer. This is\nnecessary before making any direct modification of the buffer that would increase its\nlength. \"lexstuffpvn\" provides a more convenient way to insert text into the buffer.\n\nDo not use \"SvGROW\" or \"svgrow\" directly on \"PLparser->linestr\"; this function updates\nall of the lexer's variables that point directly into the buffer.\n\nchar * lexgrowlinestr(STRLEN len)\n\n\"lexnextchunk\"\nNOTE: \"lexnextchunk\" is experimental and may change or be removed without notice.\n\nReads in the next chunk of text to be lexed, appending it to \"PLparser->linestr\". This\nshould be called when lexing code has looked to the end of the current chunk and wants to\nknow more. It is usual, but not necessary, for lexing to have consumed the entirety of\nthe current chunk at this time.\n\nIf \"PLparser->bufptr\" is pointing to the very end of the current chunk (i.e., the\ncurrent chunk has been entirely consumed), normally the current chunk will be discarded\nat the same time that the new chunk is read in. If \"flags\" has the \"LEXKEEPPREVIOUS\"\nbit set, the current chunk will not be discarded. If the current chunk has not been\nentirely consumed, then it will not be discarded regardless of the flag.\n\nReturns true if some new text was added to the buffer, or false if the buffer has reached\nthe end of the input text.\n\nbool lexnextchunk(U32 flags)\n\n\"lexpeekunichar\"\nNOTE: \"lexpeekunichar\" is experimental and may change or be removed without notice.\n\nLooks ahead one (Unicode) character in the text currently being lexed. Returns the\ncodepoint (unsigned integer value) of the next character, or -1 if lexing has reached the\nend of the input text. To consume the peeked character, use \"lexreadunichar\".\n\nIf the next character is in (or extends into) the next chunk of input text, the next\nchunk will be read in. Normally the current chunk will be discarded at the same time,\nbut if \"flags\" has the \"LEXKEEPPREVIOUS\" bit set, then the current chunk will not be\ndiscarded.\n\nIf the input is being interpreted as UTF-8 and a UTF-8 encoding error is encountered, an\nexception is generated.\n\nI32 lexpeekunichar(U32 flags)\n\n\"lexreadspace\"\nNOTE: \"lexreadspace\" is experimental and may change or be removed without notice.\n\nReads optional spaces, in Perl style, in the text currently being lexed. The spaces may\ninclude ordinary whitespace characters and Perl-style comments. \"#line\" directives are\nprocessed if encountered. \"PLparser->bufptr\" is moved past the spaces, so that it\npoints at a non-space character (or the end of the input text).\n\nIf spaces extend into the next chunk of input text, the next chunk will be read in.\nNormally the current chunk will be discarded at the same time, but if \"flags\" has the\n\"LEXKEEPPREVIOUS\" bit set, then the current chunk will not be discarded.\n\nvoid lexreadspace(U32 flags)\n\n\"lexreadto\"\nNOTE: \"lexreadto\" is experimental and may change or be removed without notice.\n\nConsume text in the lexer buffer, from \"PLparser->bufptr\" up to \"ptr\". This advances\n\"PLparser->bufptr\" to match \"ptr\", performing the correct bookkeeping whenever a newline\ncharacter is passed. This is the normal way to consume lexed text.\n\nInterpretation of the buffer's octets can be abstracted out by using the slightly higher-\nlevel functions \"lexpeekunichar\" and \"lexreadunichar\".\n\nvoid lexreadto(char *ptr)\n\n\"lexreadunichar\"\nNOTE: \"lexreadunichar\" is experimental and may change or be removed without notice.\n\nReads the next (Unicode) character in the text currently being lexed. Returns the\ncodepoint (unsigned integer value) of the character read, and moves \"PLparser->bufptr\"\npast the character, or returns -1 if lexing has reached the end of the input text. To\nnon-destructively examine the next character, use \"lexpeekunichar\" instead.\n\nIf the next character is in (or extends into) the next chunk of input text, the next\nchunk will be read in. Normally the current chunk will be discarded at the same time,\nbut if \"flags\" has the \"LEXKEEPPREVIOUS\" bit set, then the current chunk will not be\ndiscarded.\n\nIf the input is being interpreted as UTF-8 and a UTF-8 encoding error is encountered, an\nexception is generated.\n\nI32 lexreadunichar(U32 flags)\n\n\"lexstart\"\nNOTE: \"lexstart\" is experimental and may change or be removed without notice.\n\nCreates and initialises a new lexer/parser state object, supplying a context in which to\nlex and parse from a new source of Perl code. A pointer to the new state object is\nplaced in \"PLparser\". An entry is made on the save stack so that upon unwinding, the\nnew state object will be destroyed and the former value of \"PLparser\" will be restored.\nNothing else need be done to clean up the parsing context.\n\nThe code to be parsed comes from \"line\" and \"rsfp\". \"line\", if non-null, provides a\nstring (in SV form) containing code to be parsed. A copy of the string is made, so\nsubsequent modification of \"line\" does not affect parsing. \"rsfp\", if non-null, provides\nan input stream from which code will be read to be parsed. If both are non-null, the\ncode in \"line\" comes first and must consist of complete lines of input, and \"rsfp\"\nsupplies the remainder of the source.\n\nThe \"flags\" parameter is reserved for future use. Currently it is only used by perl\ninternally, so extensions should always pass zero.\n\nvoid lexstart(SV *line, PerlIO *rsfp, U32 flags)\n\n\"lexstuffpv\"\nNOTE: \"lexstuffpv\" is experimental and may change or be removed without notice.\n\nInsert characters into the lexer buffer (\"PLparser->linestr\"), immediately after the\ncurrent lexing point (\"PLparser->bufptr\"), reallocating the buffer if necessary. This\nmeans that lexing code that runs later will see the characters as if they had appeared in\nthe input. It is not recommended to do this as part of normal parsing, and most uses of\nthis facility run the risk of the inserted characters being interpreted in an unintended\nmanner.\n\nThe string to be inserted is represented by octets starting at \"pv\" and continuing to the\nfirst nul. These octets are interpreted as either UTF-8 or Latin-1, according to whether\nthe \"LEXSTUFFUTF8\" flag is set in \"flags\". The characters are recoded for the lexer\nbuffer, according to how the buffer is currently being interpreted (\"lexbufutf8\"). If\nit is not convenient to nul-terminate a string to be inserted, the \"lexstuffpvn\"\nfunction is more appropriate.\n\nvoid lexstuffpv(const char *pv, U32 flags)\n\n\"lexstuffpvn\"\nNOTE: \"lexstuffpvn\" is experimental and may change or be removed without notice.\n\nInsert characters into the lexer buffer (\"PLparser->linestr\"), immediately after the\ncurrent lexing point (\"PLparser->bufptr\"), reallocating the buffer if necessary. This\nmeans that lexing code that runs later will see the characters as if they had appeared in\nthe input. It is not recommended to do this as part of normal parsing, and most uses of\nthis facility run the risk of the inserted characters being interpreted in an unintended\nmanner.\n\nThe string to be inserted is represented by \"len\" octets starting at \"pv\". These octets\nare interpreted as either UTF-8 or Latin-1, according to whether the \"LEXSTUFFUTF8\"\nflag is set in \"flags\". The characters are recoded for the lexer buffer, according to\nhow the buffer is currently being interpreted (\"lexbufutf8\"). If a string to be\ninserted is available as a Perl scalar, the \"lexstuffsv\" function is more convenient.\n\nvoid lexstuffpvn(const char *pv, STRLEN len, U32 flags)\n\n\"lexstuffpvs\"\nNOTE: \"lexstuffpvs\" is experimental and may change or be removed without notice.\n\nLike \"lexstuffpvn\", but takes a literal string instead of a string/length pair.\n\nvoid lexstuffpvs(\"pv\", U32 flags)\n\n\"lexstuffsv\"\nNOTE: \"lexstuffsv\" is experimental and may change or be removed without notice.\n\nInsert characters into the lexer buffer (\"PLparser->linestr\"), immediately after the\ncurrent lexing point (\"PLparser->bufptr\"), reallocating the buffer if necessary. This\nmeans that lexing code that runs later will see the characters as if they had appeared in\nthe input. It is not recommended to do this as part of normal parsing, and most uses of\nthis facility run the risk of the inserted characters being interpreted in an unintended\nmanner.\n\nThe string to be inserted is the string value of \"sv\". The characters are recoded for\nthe lexer buffer, according to how the buffer is currently being interpreted\n(\"lexbufutf8\"). If a string to be inserted is not already a Perl scalar, the\n\"lexstuffpvn\" function avoids the need to construct a scalar.\n\nvoid lexstuffsv(SV *sv, U32 flags)\n\n\"lexunstuff\"\nNOTE: \"lexunstuff\" is experimental and may change or be removed without notice.\n\nDiscards text about to be lexed, from \"PLparser->bufptr\" up to \"ptr\". Text following\n\"ptr\" will be moved, and the buffer shortened. This hides the discarded text from any\nlexing code that runs later, as if the text had never appeared.\n\nThis is not the normal way to consume lexed text. For that, use \"lexreadto\".\n\nvoid lexunstuff(char *ptr)\n\n\"parsearithexpr\"\nNOTE: \"parsearithexpr\" is experimental and may change or be removed without notice.\n\nParse a Perl arithmetic expression. This may contain operators of precedence down to the\nbit shift operators. The expression must be followed (and thus terminated) either by a\ncomparison or lower-precedence operator or by something that would normally terminate an\nexpression such as semicolon. If \"flags\" has the \"PARSEOPTIONAL\" bit set, then the\nexpression is optional, otherwise it is mandatory. It is up to the caller to ensure that\nthe dynamic parser state (\"PLparser\" et al) is correctly set to reflect the source of\nthe code to be parsed and the lexical context for the expression.\n\nThe op tree representing the expression is returned. If an optional expression is\nabsent, a null pointer is returned, otherwise the pointer will be non-null.\n\nIf an error occurs in parsing or compilation, in most cases a valid op tree is returned\nanyway. The error is reflected in the parser state, normally resulting in a single\nexception at the top level of parsing which covers all the compilation errors that\noccurred. Some compilation errors, however, will throw an exception immediately.\n\nOP * parsearithexpr(U32 flags)\n\n\"parsebarestmt\"\nNOTE: \"parsebarestmt\" is experimental and may change or be removed without notice.\n\nParse a single unadorned Perl statement. This may be a normal imperative statement or a\ndeclaration that has compile-time effect. It does not include any label or other\naffixture. It is up to the caller to ensure that the dynamic parser state (\"PLparser\"\net al) is correctly set to reflect the source of the code to be parsed and the lexical\ncontext for the statement.\n\nThe op tree representing the statement is returned. This may be a null pointer if the\nstatement is null, for example if it was actually a subroutine definition (which has\ncompile-time side effects). If not null, it will be ops directly implementing the\nstatement, suitable to pass to \"newSTATEOP\". It will not normally include a \"nextstate\"\nor equivalent op (except for those embedded in a scope contained entirely within the\nstatement).\n\nIf an error occurs in parsing or compilation, in most cases a valid op tree (most likely\nnull) is returned anyway. The error is reflected in the parser state, normally resulting\nin a single exception at the top level of parsing which covers all the compilation errors\nthat occurred. Some compilation errors, however, will throw an exception immediately.\n\nThe \"flags\" parameter is reserved for future use, and must always be zero.\n\nOP * parsebarestmt(U32 flags)\n\n\"parseblock\"\nNOTE: \"parseblock\" is experimental and may change or be removed without notice.\n\nParse a single complete Perl code block. This consists of an opening brace, a sequence\nof statements, and a closing brace. The block constitutes a lexical scope, so \"my\"\nvariables and various compile-time effects can be contained within it. It is up to the\ncaller to ensure that the dynamic parser state (\"PLparser\" et al) is correctly set to\nreflect the source of the code to be parsed and the lexical context for the statement.\n\nThe op tree representing the code block is returned. This is always a real op, never a\nnull pointer. It will normally be a \"lineseq\" list, including \"nextstate\" or equivalent\nops. No ops to construct any kind of runtime scope are included by virtue of it being a\nblock.\n\nIf an error occurs in parsing or compilation, in most cases a valid op tree (most likely\nnull) is returned anyway. The error is reflected in the parser state, normally resulting\nin a single exception at the top level of parsing which covers all the compilation errors\nthat occurred. Some compilation errors, however, will throw an exception immediately.\n\nThe \"flags\" parameter is reserved for future use, and must always be zero.\n\nOP * parseblock(U32 flags)\n\n\"parsefullexpr\"\nNOTE: \"parsefullexpr\" is experimental and may change or be removed without notice.\n\nParse a single complete Perl expression. This allows the full expression grammar,\nincluding the lowest-precedence operators such as \"or\". The expression must be followed\n(and thus terminated) by a token that an expression would normally be terminated by: end-\nof-file, closing bracketing punctuation, semicolon, or one of the keywords that signals a\npostfix expression-statement modifier. If \"flags\" has the \"PARSEOPTIONAL\" bit set, then\nthe expression is optional, otherwise it is mandatory. It is up to the caller to ensure\nthat the dynamic parser state (\"PLparser\" et al) is correctly set to reflect the source\nof the code to be parsed and the lexical context for the expression.\n\nThe op tree representing the expression is returned. If an optional expression is\nabsent, a null pointer is returned, otherwise the pointer will be non-null.\n\nIf an error occurs in parsing or compilation, in most cases a valid op tree is returned\nanyway. The error is reflected in the parser state, normally resulting in a single\nexception at the top level of parsing which covers all the compilation errors that\noccurred. Some compilation errors, however, will throw an exception immediately.\n\nOP * parsefullexpr(U32 flags)\n\n\"parsefullstmt\"\nNOTE: \"parsefullstmt\" is experimental and may change or be removed without notice.\n\nParse a single complete Perl statement. This may be a normal imperative statement or a\ndeclaration that has compile-time effect, and may include optional labels. It is up to\nthe caller to ensure that the dynamic parser state (\"PLparser\" et al) is correctly set\nto reflect the source of the code to be parsed and the lexical context for the statement.\n\nThe op tree representing the statement is returned. This may be a null pointer if the\nstatement is null, for example if it was actually a subroutine definition (which has\ncompile-time side effects). If not null, it will be the result of a \"newSTATEOP\" call,\nnormally including a \"nextstate\" or equivalent op.\n\nIf an error occurs in parsing or compilation, in most cases a valid op tree (most likely\nnull) is returned anyway. The error is reflected in the parser state, normally resulting\nin a single exception at the top level of parsing which covers all the compilation errors\nthat occurred. Some compilation errors, however, will throw an exception immediately.\n\nThe \"flags\" parameter is reserved for future use, and must always be zero.\n\nOP * parsefullstmt(U32 flags)\n\n\"parselabel\"\nNOTE: \"parselabel\" is experimental and may change or be removed without notice.\n\nParse a single label, possibly optional, of the type that may prefix a Perl statement.\nIt is up to the caller to ensure that the dynamic parser state (\"PLparser\" et al) is\ncorrectly set to reflect the source of the code to be parsed. If \"flags\" has the\n\"PARSEOPTIONAL\" bit set, then the label is optional, otherwise it is mandatory.\n\nThe name of the label is returned in the form of a fresh scalar. If an optional label is\nabsent, a null pointer is returned.\n\nIf an error occurs in parsing, which can only occur if the label is mandatory, a valid\nlabel is returned anyway. The error is reflected in the parser state, normally resulting\nin a single exception at the top level of parsing which covers all the compilation errors\nthat occurred.\n\nSV * parselabel(U32 flags)\n\n\"parselistexpr\"\nNOTE: \"parselistexpr\" is experimental and may change or be removed without notice.\n\nParse a Perl list expression. This may contain operators of precedence down to the comma\noperator. The expression must be followed (and thus terminated) either by a low-\nprecedence logic operator such as \"or\" or by something that would normally terminate an\nexpression such as semicolon. If \"flags\" has the \"PARSEOPTIONAL\" bit set, then the\nexpression is optional, otherwise it is mandatory. It is up to the caller to ensure that\nthe dynamic parser state (\"PLparser\" et al) is correctly set to reflect the source of\nthe code to be parsed and the lexical context for the expression.\n\nThe op tree representing the expression is returned. If an optional expression is\nabsent, a null pointer is returned, otherwise the pointer will be non-null.\n\nIf an error occurs in parsing or compilation, in most cases a valid op tree is returned\nanyway. The error is reflected in the parser state, normally resulting in a single\nexception at the top level of parsing which covers all the compilation errors that\noccurred. Some compilation errors, however, will throw an exception immediately.\n\nOP * parselistexpr(U32 flags)\n\n\"parsestmtseq\"\nNOTE: \"parsestmtseq\" is experimental and may change or be removed without notice.\n\nParse a sequence of zero or more Perl statements. These may be normal imperative\nstatements, including optional labels, or declarations that have compile-time effect, or\nany mixture thereof. The statement sequence ends when a closing brace or end-of-file is\nencountered in a place where a new statement could have validly started. It is up to the\ncaller to ensure that the dynamic parser state (\"PLparser\" et al) is correctly set to\nreflect the source of the code to be parsed and the lexical context for the statements.\n\nThe op tree representing the statement sequence is returned. This may be a null pointer\nif the statements were all null, for example if there were no statements or if there were\nonly subroutine definitions (which have compile-time side effects). If not null, it will\nbe a \"lineseq\" list, normally including \"nextstate\" or equivalent ops.\n\nIf an error occurs in parsing or compilation, in most cases a valid op tree is returned\nanyway. The error is reflected in the parser state, normally resulting in a single\nexception at the top level of parsing which covers all the compilation errors that\noccurred. Some compilation errors, however, will throw an exception immediately.\n\nThe \"flags\" parameter is reserved for future use, and must always be zero.\n\nOP * parsestmtseq(U32 flags)\n\n\"parsesubsignature\"\nNOTE: \"parsesubsignature\" is experimental and may change or be removed without notice.\n\nParse a subroutine signature declaration. This is the contents of the parentheses\nfollowing a named or anonymous subroutine declaration when the \"signatures\" feature is\nenabled. Note that this function neither expects nor consumes the opening and closing\nparentheses around the signature; it is the caller's job to handle these.\n\nThis function must only be called during parsing of a subroutine; after \"startsubparse\"\nhas been called. It might allocate lexical variables on the pad for the current\nsubroutine.\n\nThe op tree to unpack the arguments from the stack at runtime is returned. This op tree\nshould appear at the beginning of the compiled function. The caller may wish to use\n\"opappendlist\" to build their function body after it, or splice it together with the\nbody before calling \"newATTRSUB\".\n\nThe \"flags\" parameter is reserved for future use, and must always be zero.\n\nOP * parsesubsignature(U32 flags)\n\n\"parsetermexpr\"\nNOTE: \"parsetermexpr\" is experimental and may change or be removed without notice.\n\nParse a Perl term expression. This may contain operators of precedence down to the\nassignment operators. The expression must be followed (and thus terminated) either by a\ncomma or lower-precedence operator or by something that would normally terminate an\nexpression such as semicolon. If \"flags\" has the \"PARSEOPTIONAL\" bit set, then the\nexpression is optional, otherwise it is mandatory. It is up to the caller to ensure that\nthe dynamic parser state (\"PLparser\" et al) is correctly set to reflect the source of\nthe code to be parsed and the lexical context for the expression.\n\nThe op tree representing the expression is returned. If an optional expression is\nabsent, a null pointer is returned, otherwise the pointer will be non-null.\n\nIf an error occurs in parsing or compilation, in most cases a valid op tree is returned\nanyway. The error is reflected in the parser state, normally resulting in a single\nexception at the top level of parsing which covers all the compilation errors that\noccurred. Some compilation errors, however, will throw an exception immediately.\n\nOP * parsetermexpr(U32 flags)\n\n\"PLparser\"\nPointer to a structure encapsulating the state of the parsing operation currently in\nprogress. The pointer can be locally changed to perform a nested parse without\ninterfering with the state of an outer parse. Individual members of \"PLparser\" have\ntheir own documentation.\n\n\"PLparser->bufend\"\nNOTE: \"PLparser->bufend\" is experimental and may change or be removed without notice.\n\nDirect pointer to the end of the chunk of text currently being lexed, the end of the\nlexer buffer. This is equal to \"SvPVX(PLparser->linestr) + SvCUR(PLparser->linestr)\".\nA \"NUL\" character (zero octet) is always located at the end of the buffer, and does not\ncount as part of the buffer's contents.\n\n\"PLparser->bufptr\"\nNOTE: \"PLparser->bufptr\" is experimental and may change or be removed without notice.\n\nPoints to the current position of lexing inside the lexer buffer. Characters around this\npoint may be freely examined, within the range delimited by SvPVX(\"PLparser->linestr\")\nand \"PLparser->bufend\". The octets of the buffer may be intended to be interpreted as\neither UTF-8 or Latin-1, as indicated by \"lexbufutf8\".\n\nLexing code (whether in the Perl core or not) moves this pointer past the characters that\nit consumes. It is also expected to perform some bookkeeping whenever a newline\ncharacter is consumed. This movement can be more conveniently performed by the function\n\"lexreadto\", which handles newlines appropriately.\n\nInterpretation of the buffer's octets can be abstracted out by using the slightly higher-\nlevel functions \"lexpeekunichar\" and \"lexreadunichar\".\n\n\"PLparser->linestart\"\nNOTE: \"PLparser->linestart\" is experimental and may change or be removed without notice.\n\nPoints to the start of the current line inside the lexer buffer. This is useful for\nindicating at which column an error occurred, and not much else. This must be updated by\nany lexing code that consumes a newline; the function \"lexreadto\" handles this detail.\n\n\"PLparser->linestr\"\nNOTE: \"PLparser->linestr\" is experimental and may change or be removed without notice.\n\nBuffer scalar containing the chunk currently under consideration of the text currently\nbeing lexed. This is always a plain string scalar (for which \"SvPOK\" is true). It is\nnot intended to be used as a scalar by normal scalar means; instead refer to the buffer\ndirectly by the pointer variables described below.\n\nThe lexer maintains various \"char*\" pointers to things in the \"PLparser->linestr\"\nbuffer. If \"PLparser->linestr\" is ever reallocated, all of these pointers must be\nupdated. Don't attempt to do this manually, but rather use \"lexgrowlinestr\" if you\nneed to reallocate the buffer.\n\nThe content of the text chunk in the buffer is commonly exactly one complete line of\ninput, up to and including a newline terminator, but there are situations where it is\notherwise. The octets of the buffer may be intended to be interpreted as either UTF-8 or\nLatin-1. The function \"lexbufutf8\" tells you which. Do not use the \"SvUTF8\" flag on\nthis scalar, which may disagree with it.\n\nFor direct examination of the buffer, the variable \"PLparser->bufend\" points to the end\nof the buffer. The current lexing position is pointed to by \"PLparser->bufptr\". Direct\nuse of these pointers is usually preferable to examination of the scalar through normal\nscalar means.\n\n\"suspendcompcv\"\nImplements part of the concept of a \"suspended compilation CV\", which can be used to\npause the parser and compiler during parsing a CV in order to come back to it later on.\n\nThis function saves the current state of the subroutine under compilation (\"PLcompcv\")\ninto the supplied buffer. This should be used initially to create the state in the\nbuffer, as the final thing before a \"LEAVE\" within a block.\n\nENTER;\nstartsubparse(0);\n...\n\nsuspendcompcv(&buffer);\nLEAVE;\n\nOnce suspended, the \"resumecompcv\" or \"resumecompcvandsave\" function can later be\nused to continue the parsing from the point this stopped.\n\nvoid suspendcompcv(struct suspendedcompcv *buffer)\n\n\"wrapinfixplugin\"\nNOTE: \"wrapinfixplugin\" is experimental and may change or be removed without notice.\n\nNOTE: This API exists entirely for the purpose of making the CPAN module\n\"XS::Parse::Infix\" work. It is not expected that additional modules will make use of it;\nrather, that they should use \"XS::Parse::Infix\" to provide parsing of new infix\noperators.\n\nPuts a C function into the chain of infix plugins. This is the preferred way to\nmanipulate the \"PLinfixplugin\" variable. \"newplugin\" is a pointer to the C function\nthat is to be added to the infix plugin chain, and \"oldpluginp\" points to a storage\nlocation where a pointer to the next function in the chain will be stored. The value of\n\"newplugin\" is written into the \"PLinfixplugin\" variable, while the value previously\nstored there is written to *oldpluginp.\n\nDirect access to \"PLinfixplugin\" should be avoided.\n\nvoid wrapinfixplugin(Perlinfixplugint newplugin,\nPerlinfixplugint *oldpluginp)\n\n\"wrapkeywordplugin\"\nNOTE: \"wrapkeywordplugin\" is experimental and may change or be removed without notice.\n\nPuts a C function into the chain of keyword plugins. This is the preferred way to\nmanipulate the \"PLkeywordplugin\" variable. \"newplugin\" is a pointer to the C function\nthat is to be added to the keyword plugin chain, and \"oldpluginp\" points to the storage\nlocation where a pointer to the next function in the chain will be stored. The value of\n\"newplugin\" is written into the \"PLkeywordplugin\" variable, while the value previously\nstored there is written to *oldpluginp.\n\n\"PLkeywordplugin\" is global to an entire process, and a module wishing to hook keyword\nparsing may find itself invoked more than once per process, typically in different\nthreads. To handle that situation, this function is idempotent. The location\n*oldpluginp must initially (once per process) contain a null pointer. A C variable of\nstatic duration (declared at file scope, typically also marked \"static\" to give it\ninternal linkage) will be implicitly initialised appropriately, if it does not have an\nexplicit initialiser. This function will only actually modify the plugin chain if it\nfinds *oldpluginp to be null. This function is also thread safe on the small scale.\nIt uses appropriate locking to avoid race conditions in accessing \"PLkeywordplugin\".\n\nWhen this function is called, the function referenced by \"newplugin\" must be ready to be\ncalled, except for *oldpluginp being unfilled. In a threading situation, \"newplugin\"\nmay be called immediately, even before this function has returned. *oldpluginp will\nalways be appropriately set before \"newplugin\" is called. If \"newplugin\" decides not\nto do anything special with the identifier that it is given (which is the usual case for\nmost calls to a keyword plugin), it must chain the plugin function referenced by\n*oldpluginp.\n\nTaken all together, XS code to install a keyword plugin should typically look something\nlike this:\n\nstatic Perlkeywordplugint nextkeywordplugin;\nstatic OP *mykeywordplugin(pTHX\nchar *keywordptr, STRLEN keywordlen, OP opptr)\n{\nif (memEQs(keywordptr, keywordlen,\n\"mynewkeyword\")) {\n...\n} else {\nreturn nextkeywordplugin(aTHX\nkeywordptr, keywordlen, opptr);\n}\n}\nBOOT:\nwrapkeywordplugin(mykeywordplugin,\n&nextkeywordplugin);\n\nDirect access to \"PLkeywordplugin\" should be avoided.\n\nvoid wrapkeywordplugin(Perlkeywordplugint newplugin,\nPerlkeywordplugint *oldpluginp)\n", "subsections": [] }, "Locales": { "content": "\"DECLARATIONFORLCNUMERICMANIPULATION\"\nThis macro should be used as a statement. It declares a private variable (whose name\nbegins with an underscore) that is needed by the other macros in this section. Failing\nto include this correctly should lead to a syntax error. For compatibility with C89 C\ncompilers it should be placed in a block before any executable statements.\n\nvoid DECLARATIONFORLCNUMERICMANIPULATION\n\n\"foldEQlocale\"\nReturns true if the leading \"len\" bytes of the strings \"s1\" and \"s2\" are the same case-\ninsensitively in the current locale; false otherwise.\n\nI32 foldEQlocale(const char *a, const char *b, I32 len)\n\n\"HASDUPLOCALE\"\nThis symbol, if defined, indicates that the \"duplocale\" routine is available to duplicate\na locale object.\n\n\"HASFREELOCALE\"\nThis symbol, if defined, indicates that the \"freelocale\" routine is available to\ndeallocates the resources associated with a locale object.\n\n\"HASLCMONETARY2008\"\nThis symbol, if defined, indicates that the localeconv routine is available and has the\nadditional members added in \"POSIX\" 1003.1-2008.\n\n\"HASLOCALECONV\"\nThis symbol, if defined, indicates that the \"localeconv\" routine is available for numeric\nand monetary formatting conventions.\n\n\"HASLOCALECONVL\"\nThis symbol, if defined, indicates that the \"localeconvl\" routine is available to query\ncertain information about a locale.\n\n\"HASNEWLOCALE\"\nThis symbol, if defined, indicates that the \"newlocale\" routine is available to return a\nnew locale object or modify an existing locale object.\n\n\"HASNLLANGINFO\"\nThis symbol, if defined, indicates that the \"nllanginfo\" routine is available to return\nlocal data. You will also need langinfo.h and therefore \"ILANGINFO\".\n\n\"HASNLLANGINFOL\"\nThis symbol, when defined, indicates presence of the nllanginfol() function\n\n\"HASQUERYLOCALE\"\nThis symbol, if defined, indicates that the \"querylocale\" routine is available to return\nthe name of the locale for a category mask.\n\n\"HASSETLOCALE\"\nThis symbol, if defined, indicates that the \"setlocale\" routine is available to handle\nlocale-specific ctype implementations.\n\n\"HASSETLOCALER\"\nThis symbol, if defined, indicates that the \"setlocaler\" routine is available to\nsetlocale re-entrantly.\n\n\"HASTHREADSAFENLLANGINFOL\"\nThis symbol, when defined, indicates presence of the nllanginfol() function, and that\nit is thread-safe.\n\n\"HASUSELOCALE\"\nThis symbol, if defined, indicates that the \"uselocale\" routine is available to set the\ncurrent locale for the calling thread.\n\n\"ILANGINFO\"\nThis symbol, if defined, indicates that langinfo.h exists and should be included.\n\n#ifdef ILANGINFO\n#include \n#endif\n\n\"ILOCALE\"\nThis symbol, if defined, indicates to the C program that it should include locale.h.\n\n#ifdef ILOCALE\n#include \n#endif\n\n\"INLOCALE\"\nEvaluates to TRUE if the plain locale pragma without a parameter (\"use locale\") is in\neffect.\n\nbool INLOCALE\n\n\"INLOCALECOMPILETIME\"\nEvaluates to TRUE if, when compiling a perl program (including an \"eval\") if the plain\nlocale pragma without a parameter (\"use locale\") is in effect.\n\nbool INLOCALECOMPILETIME\n\n\"INLOCALERUNTIME\"\nEvaluates to TRUE if, when executing a perl program (including an \"eval\") if the plain\nlocale pragma without a parameter (\"use locale\") is in effect.\n\nbool INLOCALERUNTIME\n\n\"IXLOCALE\"\nThis symbol, if defined, indicates to the C program that the header xlocale.h is\navailable. See also \"NEEDXLOCALEH\"\n\n#ifdef IXLOCALE\n#include \n#endif\n\n\"NEEDXLOCALEH\"\nThis symbol, if defined, indicates that the C program should include xlocale.h to get\nnewlocale() and its friends.\n\n\"Perllanginfo\"\n\"Perllanginfo8\"\n\"Perllanginfo\" is an (almost) drop-in replacement for the system nllanginfo(3), taking\nthe same \"item\" parameter values, and returning the same information. But it is more\nthread-safe than regular nllanginfo(), and hides the quirks of Perl's locale handling\nfrom your code, and can be used on systems that lack a native \"nllanginfo\".\n\nHowever, you should instead use the improved version of this: \"Perllanginfo8\", which\nbehaves identically except for an additional parameter, a pointer to a variable declared\nas \"\"utf8nesst\"\", into which it returns to you how you should treat the returned string\nwith regards to it being encoded in UTF-8 or not.\n\nConcerning the differences between these and plain nllanginfo():\n\na. \"Perllanginfo8\" has an extra parameter, described above. Besides this, the other\nreason they aren't quite a drop-in replacement is actually an advantage. The\n\"const\"ness of the return allows the compiler to catch attempts to write into the\nreturned buffer, which is illegal and could cause run-time crashes.\n\nb. They deliver the correct results for the \"RADIXCHAR\" and \"THOUSEP\" items, without you\nhaving to write extra code. The reason for the extra code would be because these are\nfrom the \"LCNUMERIC\" locale category, which is normally kept set by Perl so that the\nradix is a dot, and the separator is the empty string, no matter what the underlying\nlocale is supposed to be, and so to get the expected results, you have to temporarily\ntoggle into the underlying locale, and later toggle back. (You could use plain\n\"nllanginfo\" and \"STORELCNUMERICFORCETOUNDERLYING\" for this but then you\nwouldn't get the other advantages of Perllanginfo(); not keeping \"LCNUMERIC\" in the\nC (or equivalent) locale would break a lot of CPAN, which is expecting the radix\n(decimal point) character to be a dot.)\n\nc. The system function they replace can have its static return buffer trashed, not only\nby a subsequent call to that function, but by a \"freelocale\", \"setlocale\", or other\nlocale change. The returned buffer of these functions is not changed until the next\ncall to one or the other, so the buffer is never in a trashed state.\n\nd. The return buffer is per-thread, so it also is never overwritten by a call to these\nfunctions from another thread; unlike the function it replaces.\n\ne. But most importantly, they work on systems that don't have \"nllanginfo\", such as\nWindows, hence making your code more portable. Of the fifty-some possible items\nspecified by the POSIX 2008 standard,\n, only one\nis completely unimplemented, though on non-Windows platforms, another significant one\nis not fully implemented). They use various techniques to recover the other items,\nincluding calling localeconv(3), and strftime(3), both of which are specified in C89,\nso should be always be available. Later strftime() versions have additional\ncapabilities; What the C locale yields or \"\" is returned for any item not available\non your system.\n\nIt is important to note that, when called with an item that is recovered by using\n\"localeconv\", the buffer from any previous explicit call to localeconv(3) will be\noverwritten. But you shouldn't be using \"localeconv\" anyway because it is is very\nmuch not thread-safe, and suffers from the same problems outlined in item 'b.' above\nfor the fields it returns that are controlled by the LCNUMERIC locale category.\nInstead, avoid all of those problems by calling \"Perllocaleconv\", which is thread-\nsafe; or by using the methods given in perlcall to call POSIX::localeconv(), which\nis also thread-safe.\n\nThe details for those items which may deviate from what this emulation returns and what a\nnative nllanginfo() would return are specified in I18N::Langinfo.\n\nWhen using \"Perllanginfo8\" (or plain \"Perllanginfo\") on systems that don't have a\nnative nllanginfo(), you must\n\n#include \"perllanginfo.h\"\n\nbefore the \"perl.h\" \"#include\". You can replace your langinfo.h \"#include\" with this\none. (Doing it this way keeps out the symbols that plain langinfo.h would try to import\ninto the namespace for code that doesn't need it.)\n\nconst char * Perllanginfo (const int item)\nconst char * Perllanginfo8(const int item, utf8nesst *utf8ness)\n\n\"Perllocaleconv\"\nThis is a thread-safe version of the libc localeconv(3). It is the same as\nPOSIX::localeconv (returning a hash of the localeconv() fields), but directly callable\nfrom XS code.\n\nHV * Perllocaleconv(pTHX)\n\n\"Perlsetlocale\"\nThis is an (almost) drop-in replacement for the system setlocale(3), taking the same\nparameters, and returning the same information, except that it returns the correct\nunderlying \"LCNUMERIC\" locale. Regular \"setlocale\" will instead return \"C\" if the\nunderlying locale has a non-dot decimal point character, or a non-empty thousands\nseparator for displaying floating point numbers. This is because perl keeps that locale\ncategory such that it has a dot and empty separator, changing the locale briefly during\nthe operations where the underlying one is required. \"Perlsetlocale\" knows about this,\nand compensates; regular \"setlocale\" doesn't.\n\nAnother reason it isn't completely a drop-in replacement is that it is declared to return\n\"const char *\", whereas the system setlocale omits the \"const\" (presumably because its\nAPI was specified long ago, and can't be updated; it is illegal to change the information\n\"setlocale\" returns; doing so leads to segfaults.)\n\nFinally, \"Perlsetlocale\" works under all circumstances, whereas plain \"setlocale\" can be\ncompletely ineffective on some platforms under some configurations.\n\nChanging the locale is not a good idea when more than one thread is running, except on\nsystems where the predefined variable \"${^SAFELOCALES}\" is 1. This is because on such\nsystems the locale is global to the whole process and not local to just the thread\ncalling the function. So changing it in one thread instantaneously changes it in all.\nOn some such systems, the system setlocale() is ineffective, returning the wrong\ninformation, and failing to actually change the locale. z/OS refuses to try to change\nthe locale once a second thread is created. \"Perlsetlocale\", should give you accurate\nresults of what actually happened on these problematic platforms, returning NULL if the\nsystem forbade the locale change.\n\nThe return points to a per-thread static buffer, which is overwritten the next time\n\"Perlsetlocale\" is called from the same thread.\n\nconst char * Perlsetlocale(const int category,\nconst char *locale)\n\n\"RESTORELCNUMERIC\"\nThis is used in conjunction with one of the macros \"STORELCNUMERICSETTONEEDED\" and\n\"STORELCNUMERICFORCETOUNDERLYING\" to properly restore the \"LCNUMERIC\" state.\n\nA call to \"DECLARATIONFORLCNUMERICMANIPULATION\" must have been made to declare at\ncompile time a private variable used by this macro and the two \"STORE\" ones. This macro\nshould be called as a single statement, not an expression, but with an empty argument\nlist, like this:\n\n{\nDECLARATIONFORLCNUMERICMANIPULATION;\n...\nRESTORELCNUMERIC();\n...\n}\n\nvoid RESTORELCNUMERIC()\n\n\"SETLOCALEACCEPTSANYLOCALENAME\"\nThis symbol, if defined, indicates that the setlocale routine is available and it accepts\nany input locale name as valid.\n\n\"STORELCNUMERICFORCETOUNDERLYING\"\nThis is used by XS code that is \"LCNUMERIC\" locale-aware to force the locale for\ncategory \"LCNUMERIC\" to be what perl thinks is the current underlying locale. (The perl\ninterpreter could be wrong about what the underlying locale actually is if some C or XS\ncode has called the C library function setlocale(3) behind its back; calling\n\"synclocale\" before calling this macro will update perl's records.)\n\nA call to \"DECLARATIONFORLCNUMERICMANIPULATION\" must have been made to declare at\ncompile time a private variable used by this macro. This macro should be called as a\nsingle statement, not an expression, but with an empty argument list, like this:\n\n{\nDECLARATIONFORLCNUMERICMANIPULATION;\n...\nSTORELCNUMERICFORCETOUNDERLYING();\n...\nRESTORELCNUMERIC();\n...\n}\n\nThe private variable is used to save the current locale state, so that the requisite\nmatching call to \"RESTORELCNUMERIC\" can restore it.\n\nOn threaded perls not operating with thread-safe functionality, this macro uses a mutex\nto force a critical section. Therefore the matching RESTORE should be close by, and\nguaranteed to be called.\n\nvoid STORELCNUMERICFORCETOUNDERLYING()\n\n\"STORELCNUMERICSETTONEEDED\"\nThis is used to help wrap XS or C code that is \"LCNUMERIC\" locale-aware. This locale\ncategory is generally kept set to a locale where the decimal radix character is a dot,\nand the separator between groups of digits is empty. This is because most XS code that\nreads floating point numbers is expecting them to have this syntax.\n\nThis macro makes sure the current \"LCNUMERIC\" state is set properly, to be aware of\nlocale if the call to the XS or C code from the Perl program is from within the scope of\na \"use locale\"; or to ignore locale if the call is instead from outside such scope.\n\nThis macro is the start of wrapping the C or XS code; the wrap ending is done by calling\nthe \"RESTORELCNUMERIC\" macro after the operation. Otherwise the state can be changed\nthat will adversely affect other XS code.\n\nA call to \"DECLARATIONFORLCNUMERICMANIPULATION\" must have been made to declare at\ncompile time a private variable used by this macro. This macro should be called as a\nsingle statement, not an expression, but with an empty argument list, like this:\n\n{\nDECLARATIONFORLCNUMERICMANIPULATION;\n...\nSTORELCNUMERICSETTONEEDED();\n...\nRESTORELCNUMERIC();\n...\n}\n\nOn threaded perls not operating with thread-safe functionality, this macro uses a mutex\nto force a critical section. Therefore the matching RESTORE should be close by, and\nguaranteed to be called; see \"WITHLCNUMERICSETTONEEDED\" for a more contained way to\nensure that.\n\nvoid STORELCNUMERICSETTONEEDED()\n\n\"STORELCNUMERICSETTONEEDEDIN\"\nSame as \"STORELCNUMERICSETTONEEDED\" with inlcnumeric provided as the precalculated\nvalue of INLC(LCNUMERIC). It is the caller's responsibility to ensure that the status\nof \"PLcompiling\" and \"PLhints\" cannot have changed since the precalculation.\n\nvoid STORELCNUMERICSETTONEEDEDIN(bool inlcnumeric)\n\n\"WITHLCNUMERICSETTONEEDED\"\nThis macro invokes the supplied statement or block within the context of a\n\"STORELCNUMERICSETTONEEDED\" .. \"RESTORELCNUMERIC\" pair if required, so eg:\n\nWITHLCNUMERICSETTONEEDED(\nSNPRINTFG(fv, ebuf, sizeof(ebuf), precis)\n);\n\nis equivalent to:\n\n{\n#ifdef USELOCALENUMERIC\nDECLARATIONFORLCNUMERICMANIPULATION;\nSTORELCNUMERICSETTONEEDED();\n#endif\nSNPRINTFG(fv, ebuf, sizeof(ebuf), precis);\n#ifdef USELOCALENUMERIC\nRESTORELCNUMERIC();\n#endif\n}\n\nvoid WITHLCNUMERICSETTONEEDED(block)\n\n\"WITHLCNUMERICSETTONEEDEDIN\"\nSame as \"WITHLCNUMERICSETTONEEDED\" with inlcnumeric provided as the precalculated\nvalue of INLC(LCNUMERIC). It is the caller's responsibility to ensure that the status\nof \"PLcompiling\" and \"PLhints\" cannot have changed since the precalculation.\n\nvoid WITHLCNUMERICSETTONEEDEDIN(bool inlcnumeric, block)\n", "subsections": [] }, "Magic": { "content": "\"Magic\" is special data attached to SV structures in order to give them \"magical\" properties.\nWhen any Perl code tries to read from, or assign to, an SV marked as magical, it calls the\n'get' or 'set' function associated with that SV's magic. A get is called prior to reading an\nSV, in order to give it a chance to update its internal value (get on $. writes the line\nnumber of the last read filehandle into the SV's IV slot), while set is called after an SV\nhas been written to, in order to allow it to make use of its changed value (set on $/ copies\nthe SV's new value to the PLrs global variable).\n\nMagic is implemented as a linked list of MAGIC structures attached to the SV. Each MAGIC\nstruct holds the type of the magic, a pointer to an array of functions that implement the\nget(), set(), length() etc functions, plus space for some flags and pointers. For example, a\ntied variable has a MAGIC structure that contains a pointer to the object associated with the\ntie.\n\n\"mgclear\"\nClear something magical that the SV represents. See \"svmagic\".\n\nint mgclear(SV *sv)\n\n\"mgcopy\"\nCopies the magic from one SV to another. See \"svmagic\".\n\nint mgcopy(SV *sv, SV *nsv, const char *key, I32 klen)\n\n\"MGfCOPY\"\n\"MGfDUP\"\n\"MGfLOCAL\"\nDescribed in perlguts.\n\n\"mgfind\"\nFinds the magic pointer for \"type\" matching the SV. See \"svmagic\".\n\nMAGIC * mgfind(const SV *sv, int type)\n\n\"mgfindext\"\nFinds the magic pointer of \"type\" with the given \"vtbl\" for the \"SV\". See \"svmagicext\".\n\nMAGIC * mgfindext(const SV *sv, int type, const MGVTBL *vtbl)\n\n\"mgfree\"\nFree any magic storage used by the SV. See \"svmagic\".\n\nint mgfree(SV *sv)\n\n\"mgfreeext\"\nRemove any magic of type \"how\" using virtual table \"vtbl\" from the SV \"sv\". See\n\"svmagic\".\n\n\"mgfreeext(sv, how, NULL)\" is equivalent to \"mgfreetype(sv, how)\".\n\nvoid mgfreeext(SV *sv, int how, const MGVTBL *vtbl)\n\n\"mgfreetype\"\nRemove any magic of type \"how\" from the SV \"sv\". See \"svmagic\".\n\nvoid mgfreetype(SV *sv, int how)\n\n\"mgget\"\nDo magic before a value is retrieved from the SV. The type of SV must be >= \"SVtPVMG\".\nSee \"svmagic\".\n\nint mgget(SV *sv)\n\n\"mgmagical\"\nTurns on the magical status of an SV. See \"svmagic\".\n\nvoid mgmagical(SV *sv)\n\n\"mgset\"\nDo magic after a value is assigned to the SV. See \"svmagic\".\n\nint mgset(SV *sv)\n\n\"MGVTBL\"\nDescribed in perlguts.\n\n\"PERLMAGICarylen\"\n\"PERLMAGICarylenp\"\n\"PERLMAGICbackref\"\n\"PERLMAGICbm\"\n\"PERLMAGICcheckcall\"\n\"PERLMAGICcollxfrm\"\n\"PERLMAGICdbfile\"\n\"PERLMAGICdbline\"\n\"PERLMAGICdebugvar\"\n\"PERLMAGICdefelem\"\n\"PERLMAGICdestruct\"\n\"PERLMAGICenv\"\n\"PERLMAGICenvelem\"\n\"PERLMAGICext\"\n\"PERLMAGICextvalue\"\n\"PERLMAGICfm\"\n\"PERLMAGIChints\"\n\"PERLMAGIChintselem\"\n\"PERLMAGIChook\"\n\"PERLMAGIChookelem\"\n\"PERLMAGICisa\"\n\"PERLMAGICisaelem\"\n\"PERLMAGIClvref\"\n\"PERLMAGICnkeys\"\n\"PERLMAGICnonelem\"\n\"PERLMAGICoverloadtable\"\n\"PERLMAGICpos\"\n\"PERLMAGICqr\"\n\"PERLMAGICregdata\"\n\"PERLMAGICregdatum\"\n\"PERLMAGICregexglobal\"\n\"PERLMAGICrhash\"\n\"PERLMAGICshared\"\n\"PERLMAGICsharedscalar\"\n\"PERLMAGICsig\"\n\"PERLMAGICsigelem\"\n\"PERLMAGICsubstr\"\n\"PERLMAGICsv\"\n\"PERLMAGICsymtab\"\n\"PERLMAGICtaint\"\n\"PERLMAGICtied\"\n\"PERLMAGICtiedelem\"\n\"PERLMAGICtiedscalar\"\n\"PERLMAGICutf8\"\n\"PERLMAGICuvar\"\n\"PERLMAGICuvarelem\"\n\"PERLMAGICvec\"\n\"PERLMAGICvstring\"\nDescribed in perlguts.\n\n\"SvTIEDobj\"\nDescribed in perlinterp.\n\nSvTIEDobj(SV *sv, MAGIC *mg)\n", "subsections": [] }, "Memory Management": { "content": "\"dumpmstats\"\nWhen enabled by compiling with \"-DDEBUGGINGMSTATS\", print out statistics about malloc as\ntwo lines of numbers, one showing the length of the free list for each size category, the\nsecond showing the number of mallocs - frees for each size category.\n\n\"s\", if not NULL, is used as a phrase to include in the output, such as\n\"after compilation\".\n\nvoid dumpmstats(const char *s)\n\n\"HASATTRIBUTEMALLOC\"\nCan we handle \"GCC\" attribute for malloc-style functions.\n\n\"HASMALLOCGOODSIZE\"\nThis symbol, if defined, indicates that the \"mallocgoodsize\" routine is available for\nuse.\n\n\"HASMALLOCSIZE\"\nThis symbol, if defined, indicates that the \"mallocsize\" routine is available for use.\n\n\"IMALLOCMALLOC\"\nThis symbol, if defined, indicates to the C program that it should include\nmalloc/malloc.h.\n\n#ifdef IMALLOCMALLOC\n#include \n#endif\n\n\"MYMALLOC\"\nThis symbol, if defined, indicates that we're using our own malloc.\n\n\"Newx\"\n\"safemalloc\"\nThe XSUB-writer's interface to the C \"malloc\" function.\n\nMemory obtained by this should ONLY be freed with \"Safefree\".\n\nIn 5.9.3, Newx() and friends replace the older New() API, and drops the first parameter,\nx, a debug aid which allowed callers to identify themselves. This aid has been\nsuperseded by a new build option, PERLMEMLOG (see \"PERLMEMLOG\" in perlhacktips). The\nolder API is still there for use in XS modules supporting older perls.\n\nvoid Newx (void* ptr, int nitems, type)\nvoid* safemalloc(sizet size)\n\n\"Newxc\"\nThe XSUB-writer's interface to the C \"malloc\" function, with cast. See also \"Newx\".\n\nMemory obtained by this should ONLY be freed with \"Safefree\".\n\nvoid Newxc(void* ptr, int nitems, type, cast)\n\n\"Newxz\"\n\"safecalloc\"\nThe XSUB-writer's interface to the C \"malloc\" function. The allocated memory is zeroed\nwith \"memzero\". See also \"Newx\".\n\nMemory obtained by this should ONLY be freed with \"Safefree\".\n\nvoid Newxz (void* ptr, int nitems, type)\nvoid* safecalloc(sizet nitems, sizet itemsize)\n\n\"PERLMALLOCWRAP\"\nThis symbol, if defined, indicates that we'd like malloc wrap checks.\n\n\"Renew\"\n\"saferealloc\"\nThe XSUB-writer's interface to the C \"realloc\" function.\n\nMemory obtained by this should ONLY be freed with \"Safefree\".\n\nvoid Renew (void* ptr, int nitems, type)\nvoid* saferealloc(void *ptr, sizet size)\n\n\"Renewc\"\nThe XSUB-writer's interface to the C \"realloc\" function, with cast.\n\nMemory obtained by this should ONLY be freed with \"Safefree\".\n\nvoid Renewc(void* ptr, int nitems, type, cast)\n\n\"Safefree\"\nThe XSUB-writer's interface to the C \"free\" function.\n\nThis should ONLY be used on memory obtained using \"Newx\" and friends.\n\nvoid Safefree(void* ptr)\n\n\"safesyscalloc\"\nSafe version of system's calloc()\n\nMalloct safesyscalloc(MEMSIZE elements, MEMSIZE size)\n\n\"safesysfree\"\nSafe version of system's free()\n\nFreet safesysfree(Malloct where)\n\n\"safesysmalloc\"\nParanoid version of system's malloc()\n\nMalloct safesysmalloc(MEMSIZE nbytes)\n\n\"safesysrealloc\"\nParanoid version of system's realloc()\n\nMalloct safesysrealloc(Malloct where, MEMSIZE nbytes)\n", "subsections": [] }, "MRO": { "content": "These functions are related to the method resolution order of perl classes Also see\nperlmroapi.\n\n\"HvMROMETA\"\nDescribed in perlmroapi.\n\nstruct mrometa * HvMROMETA(HV *hv)\n\n\"mrogetfromname\"\nReturns the previously registered mro with the given \"name\", or NULL if not registered.\nSee \"\"mroregister\"\".\n\nNOTE: \"mrogetfromname\" must be explicitly called as \"Perlmrogetfromname\" with an\n\"aTHX\" parameter.\n\nconst struct mroalg * Perlmrogetfromname(pTHX SV *name)\n\n\"mrogetlinearisa\"\nReturns the mro linearisation for the given stash. By default, this will be whatever\n\"mrogetlinearisadfs\" returns unless some other MRO is in effect for the stash. The\nreturn value is a read-only AV* whose values are string SVs giving class names.\n\nYou are responsible for SvREFCNTinc() on the return value if you plan to store it\nanywhere semi-permanently (otherwise it might be deleted out from under you the next time\nthe cache is invalidated).\n\nAV * mrogetlinearisa(HV *stash)\n\n\"MROGETPRIVATEDATA\"\nDescribed in perlmroapi.\n\nSV* MROGETPRIVATEDATA(struct mrometa *const smeta,\nconst struct mroalg *const which)\n\n\"mromethodchangedin\"\nInvalidates method caching on any child classes of the given stash, so that they might\nnotice the changes in this one.\n\nIdeally, all instances of \"PLsubgeneration++\" in perl source outside of mro.c should be\nreplaced by calls to this.\n\nPerl automatically handles most of the common ways a method might be redefined. However,\nthere are a few ways you could change a method in a stash without the cache code\nnoticing, in which case you need to call this method afterwards:\n\n1) Directly manipulating the stash HV entries from XS code.\n\n2) Assigning a reference to a readonly scalar constant into a stash entry in order to\ncreate a constant subroutine (like constant.pm does).\n\nThis same method is available from pure perl via, mro::methodchangedin(classname).\n\nvoid mromethodchangedin(HV *stash)\n\n\"mroregister\"\nRegisters a custom mro plugin. See perlmroapi for details on this and other mro\nfunctions.\n\nNOTE: \"mroregister\" must be explicitly called as \"Perlmroregister\" with an \"aTHX\"\nparameter.\n\nvoid Perlmroregister(pTHX const struct mroalg *mro)\n\n\"mrosetmro\"\nSet \"meta\" to the value contained in the registered mro plugin whose name is \"name\".\n\nCroaks if \"name\" hasn't been registered\n\nNOTE: \"mrosetmro\" must be explicitly called as \"Perlmrosetmro\" with an \"aTHX\"\nparameter.\n\nvoid Perlmrosetmro(pTHX struct mrometa * const meta,\nSV * const name)\n\n\"mrosetprivatedata\"\nDescribed in perlmroapi.\n\nNOTE: \"mrosetprivatedata\" must be explicitly called as \"Perlmrosetprivatedata\"\nwith an \"aTHX\" parameter.\n\nSV * Perlmrosetprivatedata(pTHX\nstruct mrometa * const smeta,\nconst struct mroalg * const which,\nSV * const data)\n", "subsections": [] }, "Multicall Functions": { "content": "\"dMULTICALL\"\nDeclare local variables for a multicall. See \"LIGHTWEIGHT CALLBACKS\" in perlcall.\n\ndMULTICALL;\n\n\"MULTICALL\"\nMake a lightweight callback. See \"LIGHTWEIGHT CALLBACKS\" in perlcall.\n\nMULTICALL;\n\n\"POPMULTICALL\"\nClosing bracket for a lightweight callback. See \"LIGHTWEIGHT CALLBACKS\" in perlcall.\n\nPOPMULTICALL;\n\n\"PUSHMULTICALL\"\nOpening bracket for a lightweight callback. See \"LIGHTWEIGHT CALLBACKS\" in perlcall.\n\nPUSHMULTICALL(CV* thecv);\n", "subsections": [] }, "Numeric Functions": { "content": "\"Atol\"\n\"DEPRECATED!\" It is planned to remove \"Atol\" from a future release of Perl. Do not use\nit for new code; remove it from existing code.\n\nDescribed in perlhacktips.\n\nAtol(const char * nptr)\n\n\"Atoul\"\n\"DEPRECATED!\" It is planned to remove \"Atoul\" from a future release of Perl. Do not use\nit for new code; remove it from existing code.\n\nDescribed in perlhacktips.\n\nAtoul(const char * nptr)\n\n\"Drand01\"\nThis macro is to be used to generate uniformly distributed random numbers over the range\n[0., 1.[. You may have to supply an 'extern double drand48();' in your program since\nSunOS 4.1.3 doesn't provide you with anything relevant in its headers. See\n\"HASDRAND48PROTO\".\n\ndouble Drand01()\n\n\"Gconvert\"\nThis preprocessor macro is defined to convert a floating point number to a string without\na trailing decimal point. This emulates the behavior of sprintf(\"%g\"), but is sometimes\nmuch more efficient. If gconvert() is not available, but gcvt() drops the trailing\ndecimal point, then gcvt() is used. If all else fails, a macro using sprintf(\"%g\") is\nused. Arguments for the Gconvert macro are: value, number of digits, whether trailing\nzeros should be retained, and the output buffer. The usual values are:\n\ndGconvert='gconvert((x),(n),(t),(b))'\ndGconvert='gcvt((x),(n),(b))'\ndGconvert='sprintf((b),\"%.*g\",(n),(x))'\n\nThe last two assume trailing zeros should not be kept.\n\nchar * Gconvert(double x, Sizet n, bool t, char * b)\n\n\"grokatoUV\"\nparse a string, looking for a decimal unsigned integer.\n\nOn entry, \"pv\" points to the beginning of the string; \"valptr\" points to a UV that will\nreceive the converted value, if found; \"endptr\" is either NULL or points to a variable\nthat points to one byte beyond the point in \"pv\" that this routine should examine. If\n\"endptr\" is NULL, \"pv\" is assumed to be NUL-terminated.\n\nReturns FALSE if \"pv\" doesn't represent a valid unsigned integer value (with no leading\nzeros). Otherwise it returns TRUE, and sets *valptr to that value.\n\nIf you constrain the portion of \"pv\" that is looked at by this function (by passing a\nnon-NULL \"endptr\"), and if the initial bytes of that portion form a valid value, it will\nreturn TRUE, setting *endptr to the byte following the final digit of the value. But if\nthere is no constraint at what's looked at, all of \"pv\" must be valid in order for TRUE\nto be returned. *endptr is unchanged from its value on input if FALSE is returned;\n\nThe only characters this accepts are the decimal digits '0'..'9'.\n\nAs opposed to atoi(3) or strtol(3), \"grokatoUV\" does NOT allow optional leading\nwhitespace, nor negative inputs. If such features are required, the calling code needs\nto explicitly implement those.\n\nNote that this function returns FALSE for inputs that would overflow a UV, or have\nleading zeros. Thus a single 0 is accepted, but not 00 nor 01, 002, etc.\n\nBackground: \"atoi\" has severe problems with illegal inputs, it cannot be used for\nincremental parsing, and therefore should be avoided \"atoi\" and \"strtol\" are also\naffected by locale settings, which can also be seen as a bug (global state controlled by\nuser environment).\n\nbool grokatoUV(const char *pv, UV *valptr, const char endptr)\n\n\"grokbin\"\nconverts a string representing a binary number to numeric form.\n\nOn entry \"start\" and *lenp give the string to scan, *flags gives conversion flags, and\n\"result\" should be \"NULL\" or a pointer to an NV. The scan stops at the end of the\nstring, or at just before the first invalid character. Unless\n\"PERLSCANSILENTILLDIGIT\" is set in *flags, encountering an invalid character (except\nNUL) will also trigger a warning. On return *lenp is set to the length of the scanned\nstring, and *flags gives output flags.\n\nIf the value is <= \"UVMAX\" it is returned as a UV, the output flags are clear, and\nnothing is written to *result. If the value is > \"UVMAX\", \"grokbin\" returns \"UVMAX\",\nsets \"PERLSCANGREATERTHANUVMAX\" in the output flags, and writes an approximation of\nthe correct value into *result (which is an NV; or the approximation is discarded if\n\"result\" is NULL).\n\nThe binary number may optionally be prefixed with \"0b\" or \"b\" unless\n\"PERLSCANDISALLOWPREFIX\" is set in *flags on entry.\n\nIf \"PERLSCANALLOWUNDERSCORES\" is set in *flags then any or all pairs of digits may be\nseparated from each other by a single underscore; also a single leading underscore is\naccepted.\n\nUV grokbin(const char *start, STRLEN *lenp, I32 *flags,\nNV *result)\n\n\"grokhex\"\nconverts a string representing a hex number to numeric form.\n\nOn entry \"start\" and *lenp give the string to scan, *flags gives conversion flags, and\n\"result\" should be \"NULL\" or a pointer to an NV. The scan stops at the end of the\nstring, or at just before the first invalid character. Unless\n\"PERLSCANSILENTILLDIGIT\" is set in *flags, encountering an invalid character (except\nNUL) will also trigger a warning. On return *lenp is set to the length of the scanned\nstring, and *flags gives output flags.\n\nIf the value is <= \"UVMAX\" it is returned as a UV, the output flags are clear, and\nnothing is written to *result. If the value is > \"UVMAX\", \"grokhex\" returns \"UVMAX\",\nsets \"PERLSCANGREATERTHANUVMAX\" in the output flags, and writes an approximation of\nthe correct value into *result (which is an NV; or the approximation is discarded if\n\"result\" is NULL).\n\nThe hex number may optionally be prefixed with \"0x\" or \"x\" unless\n\"PERLSCANDISALLOWPREFIX\" is set in *flags on entry.\n\nIf \"PERLSCANALLOWUNDERSCORES\" is set in *flags then any or all pairs of digits may be\nseparated from each other by a single underscore; also a single leading underscore is\naccepted.\n\nUV grokhex(const char *start, STRLEN *lenp, I32 *flags,\nNV *result)\n\n\"grokinfnan\"\nHelper for groknumber(), accepts various ways of spelling \"infinity\" or \"not a number\",\nand returns one of the following flag combinations:\n\nISNUMBERINFINITY\nISNUMBERNAN\nISNUMBERINFINITY | ISNUMBERNEG\nISNUMBERNAN | ISNUMBERNEG\n0\n\npossibly |-ed with \"ISNUMBERTRAILING\".\n\nIf an infinity or a not-a-number is recognized, *sp will point to one byte past the end\nof the recognized string. If the recognition fails, zero is returned, and *sp will not\nmove.\n\nint grokinfnan(const char sp, const char *send)\n\n\"groknumber\"\nIdentical to groknumberflags() with \"flags\" set to zero.\n\nint groknumber(const char *pv, STRLEN len, UV *valuep)\n\n\"groknumberflags\"\nRecognise (or not) a number. The type of the number is returned (0 if unrecognised),\notherwise it is a bit-ORed combination of \"ISNUMBERINUV\",\n\"ISNUMBERGREATERTHANUVMAX\", \"ISNUMBERNOTINT\", \"ISNUMBERNEG\",\n\"ISNUMBERINFINITY\", \"ISNUMBERNAN\" (defined in perl.h).\n\nIf the value of the number can fit in a UV, it is returned in *valuep. \"ISNUMBERINUV\"\nwill be set to indicate that *valuep is valid, \"ISNUMBERINUV\" will never be set unless\n*valuep is valid, but *valuep may have been assigned to during processing even though\n\"ISNUMBERINUV\" is not set on return. If \"valuep\" is \"NULL\", \"ISNUMBERINUV\" will be\nset for the same cases as when \"valuep\" is non-\"NULL\", but no actual assignment (or SEGV)\nwill occur.\n\n\"ISNUMBERNOTINT\" will be set with \"ISNUMBERINUV\" if trailing decimals were seen (in\nwhich case *valuep gives the true value truncated to an integer), and \"ISNUMBERNEG\" if\nthe number is negative (in which case *valuep holds the absolute value).\n\"ISNUMBERINUV\" is not set if \"e\" notation was used or the number is larger than a UV.\n\n\"flags\" allows only \"PERLSCANTRAILING\", which allows for trailing non-numeric text on\nan otherwise successful grok, setting \"ISNUMBERTRAILING\" on the result.\n\nint groknumberflags(const char *pv, STRLEN len, UV *valuep,\nU32 flags)\n\n\"GROKNUMERICRADIX\"\nA synonym for \"groknumericradix\"\n\nbool GROKNUMERICRADIX(NN const char sp, NN const char *send)\n\n\"groknumericradix\"\nScan and skip for a numeric decimal separator (radix).\n\nbool groknumericradix(const char sp, const char *send)\n\n\"grokoct\"\nconverts a string representing an octal number to numeric form.\n\nOn entry \"start\" and *lenp give the string to scan, *flags gives conversion flags, and\n\"result\" should be \"NULL\" or a pointer to an NV. The scan stops at the end of the\nstring, or at just before the first invalid character. Unless\n\"PERLSCANSILENTILLDIGIT\" is set in *flags, encountering an invalid character (except\nNUL) will also trigger a warning. On return *lenp is set to the length of the scanned\nstring, and *flags gives output flags.\n\nIf the value is <= \"UVMAX\" it is returned as a UV, the output flags are clear, and\nnothing is written to *result. If the value is > \"UVMAX\", \"grokoct\" returns \"UVMAX\",\nsets \"PERLSCANGREATERTHANUVMAX\" in the output flags, and writes an approximation of\nthe correct value into *result (which is an NV; or the approximation is discarded if\n\"result\" is NULL).\n\nIf \"PERLSCANALLOWUNDERSCORES\" is set in *flags then any or all pairs of digits may be\nseparated from each other by a single underscore; also a single leading underscore is\naccepted.\n\nThe \"PERLSCANDISALLOWPREFIX\" flag is always treated as being set for this function.\n\nUV grokoct(const char *start, STRLEN *lenp, I32 *flags,\nNV *result)\n\n\"isinfnan\"\nPerlisinfnan() is a utility function that returns true if the NV argument is either an\ninfinity or a \"NaN\", false otherwise. To test in more detail, use Perlisinf() and\nPerlisnan().\n\nThis is also the logical inverse of Perlisfinite().\n\nbool isinfnan(NV nv)\n\n\"myatof\"\n\"atof\"(3), but properly works with Perl locale handling, accepting a dot radix character\nalways, but also the current locale's radix character if and only if called from within\nthe lexical scope of a Perl \"use locale\" statement.\n\nN.B. \"s\" must be NUL terminated.\n\nNV myatof(const char *s)\n\n\"mystrtod\"\nThis function is equivalent to the libc strtod() function, and is available even on\nplatforms that lack plain strtod(). Its return value is the best available precision\ndepending on platform capabilities and Configure options.\n\nIt properly handles the locale radix character, meaning it expects a dot except when\ncalled from within the scope of \"use locale\", in which case the radix character should be\nthat specified by the current locale.\n\nThe synonym Strtod() may be used instead.\n\nNV mystrtod(const char * const s, char e)\n\n\"PERLABS\"\nTypeless \"abs\" or \"fabs\", etc. (The usage below indicates it is for integers, but it\nworks for any type.) Use instead of these, since the C library ones force their argument\nto be what it is expecting, potentially leading to disaster. But also beware that this\nevaluates its argument twice, so no \"x++\".\n\nint PERLABS(int x)\n\n\"Perlacos\"\n\"Perlasin\"\n\"Perlatan\"\n\"Perlatan2\"\n\"Perlceil\"\n\"Perlcos\"\n\"Perlcosh\"\n\"Perlexp\"\n\"Perlfloor\"\n\"Perlfmod\"\n\"Perlfrexp\"\n\"Perlisfinite\"\n\"Perlisinf\"\n\"Perlisnan\"\n\"Perlldexp\"\n\"Perllog\"\n\"Perllog10\"\n\"Perlmodf\"\n\"Perlpow\"\n\"Perlsin\"\n\"Perlsinh\"\n\"Perlsqrt\"\n\"Perltan\"\n\"Perltanh\"\nThese perform the corresponding mathematical operation on the operand(s), using the libc\nfunction designed for the task that has just enough precision for an NV on this platform.\nIf no such function with sufficient precision exists, the highest precision one available\nis used.\n\nNV Perlacos (NV x)\nNV Perlasin (NV x)\nNV Perlatan (NV x)\nNV Perlatan2 (NV x, NV y)\nNV Perlceil (NV x)\nNV Perlcos (NV x)\nNV Perlcosh (NV x)\nNV Perlexp (NV x)\nNV Perlfloor (NV x)\nNV Perlfmod (NV x, NV y)\nNV Perlfrexp (NV x, int *exp)\nIV Perlisfinite(NV x)\nIV Perlisinf (NV x)\nIV Perlisnan (NV x)\nNV Perlldexp (NV x, int exp)\nNV Perllog (NV x)\nNV Perllog10 (NV x)\nNV Perlmodf (NV x, NV *iptr)\nNV Perlpow (NV x, NV y)\nNV Perlsin (NV x)\nNV Perlsinh (NV x)\nNV Perlsqrt (NV x)\nNV Perltan (NV x)\nNV Perltanh (NV x)\n\n\"Perlsignbit\"\nNOTE: \"Perlsignbit\" is experimental and may change or be removed without notice.\n\nReturn a non-zero integer if the sign bit on an NV is set, and 0 if it is not.\n\nIf Configure detects this system has a signbit() that will work with our NVs, then we\njust use it via the \"#define\" in perl.h. Otherwise, fall back on this implementation.\nThe main use of this function is catching -0.0.\n\n\"Configure\" notes: This function is called 'Perlsignbit' instead of a plain 'signbit'\nbecause it is easy to imagine a system having a signbit() function or macro that doesn't\nhappen to work with our particular choice of NVs. We shouldn't just re-\"#define\"\n\"signbit\" as \"Perlsignbit\" and expect the standard system headers to be happy. Also,\nthis is a no-context function (no \"pTHX\") because Perlsignbit() is usually\nre-\"#defined\" in perl.h as a simple macro call to the system's signbit(). Users should\njust always call Perlsignbit().\n\nint Perlsignbit(NV f)\n\n\"PLhexdigit\"\nThis array, indexed by an integer, converts that value into the character that represents\nit. For example, if the input is 8, the return will be a string whose first character is\n'8'. What is actually returned is a pointer into a string. All you are interested in is\nthe first character of that string. To get uppercase letters (for the values 10..15),\nadd 16 to the index. Hence, \"PLhexdigit[11]\" is 'b', and \"PLhexdigit[11+16]\" is 'B'.\nAdding 16 to an index whose representation is '0'..'9' yields the same as not adding 16.\nIndices outside the range 0..31 result in (bad) undedefined behavior.\n\n\"READXDIGIT\"\nReturns the value of an ASCII-range hex digit and advances the string pointer. Behaviour\nis only well defined when isXDIGIT(*str) is true.\n\nU8 READXDIGIT(char str*)\n\n\"scanbin\"\nFor backwards compatibility. Use \"grokbin\" instead.\n\nNV scanbin(const char *start, STRLEN len, STRLEN *retlen)\n\n\"scanhex\"\nFor backwards compatibility. Use \"grokhex\" instead.\n\nNV scanhex(const char *start, STRLEN len, STRLEN *retlen)\n\n\"scanoct\"\nFor backwards compatibility. Use \"grokoct\" instead.\n\nNV scanoct(const char *start, STRLEN len, STRLEN *retlen)\n\n\"seedDrand01\"\nThis symbol defines the macro to be used in seeding the random number generator (see\n\"Drand01\").\n\nvoid seedDrand01(Randseedt x)\n\n\"Strtod\"\nThis is a synonym for \"mystrtod\".\n\nNV Strtod(NN const char * const s, NULLOK char e)\n\n\"Strtol\"\nPlatform and configuration independent \"strtol\". This expands to the appropriate\n\"strotol\"-like function based on the platform and Configure options>. For example it\ncould expand to \"strtoll\" or \"strtoq\" instead of \"strtol\".\n\nNV Strtol(NN const char * const s, NULLOK char e, int base)\n\n\"Strtoul\"\nPlatform and configuration independent \"strtoul\". This expands to the appropriate\n\"strotoul\"-like function based on the platform and Configure options>. For example it\ncould expand to \"strtoull\" or \"strtouq\" instead of \"strtoul\".\n\nNV Strtoul(NN const char * const s, NULLOK char e, int base)\n", "subsections": [] }, "Optrees": { "content": "\"alloccopstash\"\nNOTE: \"alloccopstash\" is experimental and may change or be removed without notice.\n\nAvailable only under threaded builds, this function allocates an entry in \"PLstashpad\"\nfor the stash passed to it.\n\nPADOFFSET alloccopstash(HV *hv)\n\n\"BINOP\"\nDescribed in perlguts.\n\n\"blockend\"\nHandles compile-time scope exit. \"floor\" is the savestack index returned by\n\"blockstart\", and \"seq\" is the body of the block. Returns the block, possibly modified.\n\nOP * blockend(I32 floor, OP *seq)\n\n\"blockstart\"\nHandles compile-time scope entry. Arranges for hints to be restored on block exit and\nalso handles pad sequence numbers to make lexical variables scope right. Returns a\nsavestack index for use with \"blockend\".\n\nint blockstart(int full)\n\n\"ckentersubargslist\"\nPerforms the default fixup of the arguments part of an \"entersub\" op tree. This consists\nof applying list context to each of the argument ops. This is the standard treatment\nused on a call marked with \"&\", or a method call, or a call through a subroutine\nreference, or any other call where the callee can't be identified at compile time, or a\ncall where the callee has no prototype.\n\nOP * ckentersubargslist(OP *entersubop)\n\n\"ckentersubargsproto\"\nPerforms the fixup of the arguments part of an \"entersub\" op tree based on a subroutine\nprototype. This makes various modifications to the argument ops, from applying context\nup to inserting \"refgen\" ops, and checking the number and syntactic types of arguments,\nas directed by the prototype. This is the standard treatment used on a subroutine call,\nnot marked with \"&\", where the callee can be identified at compile time and has a\nprototype.\n\n\"protosv\" supplies the subroutine prototype to be applied to the call. It may be a\nnormal defined scalar, of which the string value will be used. Alternatively, for\nconvenience, it may be a subroutine object (a \"CV*\" that has been cast to \"SV*\") which\nhas a prototype. The prototype supplied, in whichever form, does not need to match the\nactual callee referenced by the op tree.\n\nIf the argument ops disagree with the prototype, for example by having an unacceptable\nnumber of arguments, a valid op tree is returned anyway. The error is reflected in the\nparser state, normally resulting in a single exception at the top level of parsing which\ncovers all the compilation errors that occurred. In the error message, the callee is\nreferred to by the name defined by the \"namegv\" parameter.\n\nOP * ckentersubargsproto(OP *entersubop, GV *namegv,\nSV *protosv)\n\n\"ckentersubargsprotoorlist\"\nPerforms the fixup of the arguments part of an \"entersub\" op tree either based on a\nsubroutine prototype or using default list-context processing. This is the standard\ntreatment used on a subroutine call, not marked with \"&\", where the callee can be\nidentified at compile time.\n\n\"protosv\" supplies the subroutine prototype to be applied to the call, or indicates that\nthere is no prototype. It may be a normal scalar, in which case if it is defined then\nthe string value will be used as a prototype, and if it is undefined then there is no\nprototype. Alternatively, for convenience, it may be a subroutine object (a \"CV*\" that\nhas been cast to \"SV*\"), of which the prototype will be used if it has one. The\nprototype (or lack thereof) supplied, in whichever form, does not need to match the\nactual callee referenced by the op tree.\n\nIf the argument ops disagree with the prototype, for example by having an unacceptable\nnumber of arguments, a valid op tree is returned anyway. The error is reflected in the\nparser state, normally resulting in a single exception at the top level of parsing which\ncovers all the compilation errors that occurred. In the error message, the callee is\nreferred to by the name defined by the \"namegv\" parameter.\n\nOP * ckentersubargsprotoorlist(OP *entersubop, GV *namegv,\nSV *protosv)\n\n\"cvconstsv\"\nIf \"cv\" is a constant sub eligible for inlining, returns the constant value returned by\nthe sub. Otherwise, returns \"NULL\".\n\nConstant subs can be created with \"newCONSTSUB\" or as described in \"Constant Functions\"\nin perlsub.\n\nSV * cvconstsv(const CV * const cv)\n\n\"cvgetcallchecker\"\nThe original form of \"cvgetcallcheckerflags\", which does not return checker flags.\nWhen using a checker function returned by this function, it is only safe to call it with\na genuine GV as its \"namegv\" argument.\n\nvoid cvgetcallchecker(CV *cv, Perlcallchecker *ckfunp,\nSV ckobjp)\n\n\"cvgetcallcheckerflags\"\nRetrieves the function that will be used to fix up a call to \"cv\". Specifically, the\nfunction is applied to an \"entersub\" op tree for a subroutine call, not marked with \"&\",\nwhere the callee can be identified at compile time as \"cv\".\n\nThe C-level function pointer is returned in *ckfunp, an SV argument for it is returned\nin *ckobjp, and control flags are returned in *ckflagsp. The function is intended to\nbe called in this manner:\n\nentersubop = (*ckfunp)(aTHX entersubop, namegv, (*ckobjp));\n\nIn this call, \"entersubop\" is a pointer to the \"entersub\" op, which may be replaced by\nthe check function, and \"namegv\" supplies the name that should be used by the check\nfunction to refer to the callee of the \"entersub\" op if it needs to emit any diagnostics.\nIt is permitted to apply the check function in non-standard situations, such as to a call\nto a different subroutine or to a method call.\n\n\"namegv\" may not actually be a GV. If the \"CALLCHECKERREQUIREGV\" bit is clear in\n*ckflagsp, it is permitted to pass a CV or other SV instead, anything that can be used\nas the first argument to \"cvname\". If the \"CALLCHECKERREQUIREGV\" bit is set in\n*ckflagsp then the check function requires \"namegv\" to be a genuine GV.\n\nBy default, the check function is Perlckentersubargsprotoorlist, the SV parameter\nis \"cv\" itself, and the \"CALLCHECKERREQUIREGV\" flag is clear. This implements\nstandard prototype processing. It can be changed, for a particular subroutine, by\n\"cvsetcallcheckerflags\".\n\nIf the \"CALLCHECKERREQUIREGV\" bit is set in \"gflags\" then it indicates that the caller\nonly knows about the genuine GV version of \"namegv\", and accordingly the corresponding\nbit will always be set in *ckflagsp, regardless of the check function's recorded\nrequirements. If the \"CALLCHECKERREQUIREGV\" bit is clear in \"gflags\" then it\nindicates the caller knows about the possibility of passing something other than a GV as\n\"namegv\", and accordingly the corresponding bit may be either set or clear in *ckflagsp,\nindicating the check function's recorded requirements.\n\n\"gflags\" is a bitset passed into \"cvgetcallcheckerflags\", in which only the\n\"CALLCHECKERREQUIREGV\" bit currently has a defined meaning (for which see above). All\nother bits should be clear.\n\nvoid cvgetcallcheckerflags(CV *cv, U32 gflags,\nPerlcallchecker *ckfunp,\nSV ckobjp, U32 *ckflagsp)\n\n\"cvsetcallchecker\"\nThe original form of \"cvsetcallcheckerflags\", which passes it the\n\"CALLCHECKERREQUIREGV\" flag for backward-compatibility. The effect of that flag\nsetting is that the check function is guaranteed to get a genuine GV as its \"namegv\"\nargument.\n\nvoid cvsetcallchecker(CV *cv, Perlcallchecker ckfun,\nSV *ckobj)\n\n\"cvsetcallcheckerflags\"\nSets the function that will be used to fix up a call to \"cv\". Specifically, the function\nis applied to an \"entersub\" op tree for a subroutine call, not marked with \"&\", where the\ncallee can be identified at compile time as \"cv\".\n\nThe C-level function pointer is supplied in \"ckfun\", an SV argument for it is supplied in\n\"ckobj\", and control flags are supplied in \"ckflags\". The function should be defined\nlike this:\n\nSTATIC OP * ckfun(pTHX OP *op, GV *namegv, SV *ckobj)\n\nIt is intended to be called in this manner:\n\nentersubop = ckfun(aTHX entersubop, namegv, ckobj);\n\nIn this call, \"entersubop\" is a pointer to the \"entersub\" op, which may be replaced by\nthe check function, and \"namegv\" supplies the name that should be used by the check\nfunction to refer to the callee of the \"entersub\" op if it needs to emit any diagnostics.\nIt is permitted to apply the check function in non-standard situations, such as to a call\nto a different subroutine or to a method call.\n\n\"namegv\" may not actually be a GV. For efficiency, perl may pass a CV or other SV\ninstead. Whatever is passed can be used as the first argument to \"cvname\". You can\nforce perl to pass a GV by including \"CALLCHECKERREQUIREGV\" in the \"ckflags\".\n\n\"ckflags\" is a bitset, in which only the \"CALLCHECKERREQUIREGV\" bit currently has a\ndefined meaning (for which see above). All other bits should be clear.\n\nThe current setting for a particular CV can be retrieved by \"cvgetcallcheckerflags\".\n\nvoid cvsetcallcheckerflags(CV *cv, Perlcallchecker ckfun,\nSV *ckobj, U32 ckflags)\n\n\"finalizeoptree\"\nThis function finalizes the optree. Should be called directly after the complete optree\nis built. It does some additional checking which can't be done in the normal \"ck\"xxx\nfunctions and makes the tree thread-safe.\n\nvoid finalizeoptree(OP *o)\n\n\"forbidoutofblockops\"\nNOTE: \"forbidoutofblockops\" is experimental and may change or be removed without\nnotice.\n\nChecks an optree that implements a block, to ensure there are no control-flow ops that\nattempt to leave the block. Any \"OPRETURN\" is forbidden, as is any \"OPGOTO\". Loops are\nanalysed, so any LOOPEX op (\"OPNEXT\", \"OPLAST\" or \"OPREDO\") that affects a loop that\ncontains it within the block are permitted, but those that do not are forbidden.\n\nIf any of these forbidden constructions are detected, an exception is thrown by using the\nop name and the blockname argument to construct a suitable message.\n\nThis function alone is not sufficient to ensure the optree does not perform any of these\nforbidden activities during runtime, as it might call a different function that performs\na non-local LOOPEX, or a string-eval() that performs a \"goto\", or various other things.\nIt is intended purely as a compile-time check for those that could be detected\nstatically. Additional runtime checks may be required depending on the circumstance it is\nused for.\n\nNote currently that all \"OPGOTO\" ops are forbidden, even in cases where they might\notherwise be safe to execute. This may be permitted in a later version.\n\nvoid forbidoutofblockops(OP *o, const char *blockname)\n\n\"LINKLIST\"\nGiven the root of an optree, link the tree in execution order using the \"opnext\"\npointers and return the first op executed. If this has already been done, it will not be\nredone, and \"o->opnext\" will be returned. If \"o->opnext\" is not already set, \"o\"\nshould be at least an \"UNOP\".\n\nOP* LINKLIST(OP *o)\n\n\"LISTOP\"\nDescribed in perlguts.\n\n\"LOGOP\"\nDescribed in perlguts.\n\n\"LOOP\"\nDescribed in perlguts.\n\n\"newARGDEFELEMOP\"\nConstructs and returns a new \"OPARGDEFELEM\" op which provides a defaulting expression\ngiven by \"expr\" for the signature parameter at the index given by \"argindex\". The\nexpression optree is consumed by this function and becomes part of the returned optree.\n\nOP * newARGDEFELEMOP(I32 flags, OP *expr, I32 argindex)\n\n\"newASSIGNOP\"\nConstructs, checks, and returns an assignment op. \"left\" and \"right\" supply the\nparameters of the assignment; they are consumed by this function and become part of the\nconstructed op tree.\n\nIf \"optype\" is \"OPANDASSIGN\", \"OPORASSIGN\", or \"OPDORASSIGN\", then a suitable\nconditional optree is constructed. If \"optype\" is the opcode of a binary operator, such\nas \"OPBITOR\", then an op is constructed that performs the binary operation and assigns\nthe result to the left argument. Either way, if \"optype\" is non-zero then \"flags\" has no\neffect.\n\nIf \"optype\" is zero, then a plain scalar or list assignment is constructed. Which type\nof assignment it is is automatically determined. \"flags\" gives the eight bits of\n\"opflags\", except that \"OPfKIDS\" will be set automatically, and, shifted up eight bits,\nthe eight bits of \"opprivate\", except that the bit with value 1 or 2 is automatically\nset as required.\n\nOP * newASSIGNOP(I32 flags, OP *left, I32 optype, OP *right)\n\n\"newATTRSUB\"\nConstruct a Perl subroutine, also performing some surrounding jobs.\n\nThis is the same as \"\"newATTRSUBx\"\" in perlintern with its \"oisgv\" parameter set to\nFALSE. This means that if \"o\" is null, the new sub will be anonymous; otherwise the name\nwill be derived from \"o\" in the way described (as with all other details) in\n\"\"newATTRSUBx\"\" in perlintern.\n\nCV * newATTRSUB(I32 floor, OP *o, OP *proto, OP *attrs,\nOP *block)\n\n\"newBINOP\"\nConstructs, checks, and returns an op of any binary type. \"type\" is the opcode. \"flags\"\ngives the eight bits of \"opflags\", except that \"OPfKIDS\" will be set automatically,\nand, shifted up eight bits, the eight bits of \"opprivate\", except that the bit with\nvalue 1 or 2 is automatically set as required. \"first\" and \"last\" supply up to two ops\nto be the direct children of the binary op; they are consumed by this function and become\npart of the constructed op tree.\n\nOP * newBINOP(I32 type, I32 flags, OP *first, OP *last)\n\n\"newCONDOP\"\nConstructs, checks, and returns a conditional-expression (\"condexpr\") op. \"flags\" gives\nthe eight bits of \"opflags\", except that \"OPfKIDS\" will be set automatically, and,\nshifted up eight bits, the eight bits of \"opprivate\", except that the bit with value 1\nis automatically set. \"first\" supplies the expression selecting between the two\nbranches, and \"trueop\" and \"falseop\" supply the branches; they are consumed by this\nfunction and become part of the constructed op tree.\n\nOP * newCONDOP(I32 flags, OP *first, OP *trueop, OP *falseop)\n\n\"newCONSTSUB\"\nBehaves like \"newCONSTSUBflags\", except that \"name\" is nul-terminated rather than of\ncounted length, and no flags are set. (This means that \"name\" is always interpreted as\nLatin-1.)\n\nCV * newCONSTSUB(HV *stash, const char *name, SV *sv)\n\n\"newCONSTSUBflags\"\nConstruct a constant subroutine, also performing some surrounding jobs. A scalar\nconstant-valued subroutine is eligible for inlining at compile-time, and in Perl code can\nbe created by \"sub FOO () { 123 }\". Other kinds of constant subroutine have other\ntreatment.\n\nThe subroutine will have an empty prototype and will ignore any arguments when called.\nIts constant behaviour is determined by \"sv\". If \"sv\" is null, the subroutine will yield\nan empty list. If \"sv\" points to a scalar, the subroutine will always yield that scalar.\nIf \"sv\" points to an array, the subroutine will always yield a list of the elements of\nthat array in list context, or the number of elements in the array in scalar context.\nThis function takes ownership of one counted reference to the scalar or array, and will\narrange for the object to live as long as the subroutine does. If \"sv\" points to a\nscalar then the inlining assumes that the value of the scalar will never change, so the\ncaller must ensure that the scalar is not subsequently written to. If \"sv\" points to an\narray then no such assumption is made, so it is ostensibly safe to mutate the array or\nits elements, but whether this is really supported has not been determined.\n\nThe subroutine will have \"CvFILE\" set according to \"PLcurcop\". Other aspects of the\nsubroutine will be left in their default state. The caller is free to mutate the\nsubroutine beyond its initial state after this function has returned.\n\nIf \"name\" is null then the subroutine will be anonymous, with its \"CvGV\" referring to an\n\"ANON\" glob. If \"name\" is non-null then the subroutine will be named accordingly,\nreferenced by the appropriate glob. \"name\" is a string of length \"len\" bytes giving a\nsigilless symbol name, in UTF-8 if \"flags\" has the \"SVfUTF8\" bit set and in Latin-1\notherwise. The name may be either qualified or unqualified. If the name is unqualified\nthen it defaults to being in the stash specified by \"stash\" if that is non-null, or to\n\"PLcurstash\" if \"stash\" is null. The symbol is always added to the stash if necessary,\nwith \"GVADDMULTI\" semantics.\n\n\"flags\" should not have bits set other than \"SVfUTF8\".\n\nIf there is already a subroutine of the specified name, then the new sub will replace the\nexisting one in the glob. A warning may be generated about the redefinition.\n\nIf the subroutine has one of a few special names, such as \"BEGIN\" or \"END\", then it will\nbe claimed by the appropriate queue for automatic running of phase-related subroutines.\nIn this case the relevant glob will be left not containing any subroutine, even if it did\ncontain one before. Execution of the subroutine will likely be a no-op, unless \"sv\" was\na tied array or the caller modified the subroutine in some interesting way before it was\nexecuted. In the case of \"BEGIN\", the treatment is buggy: the sub will be executed when\nonly half built, and may be deleted prematurely, possibly causing a crash.\n\nThe function returns a pointer to the constructed subroutine. If the sub is anonymous\nthen ownership of one counted reference to the subroutine is transferred to the caller.\nIf the sub is named then the caller does not get ownership of a reference. In most such\ncases, where the sub has a non-phase name, the sub will be alive at the point it is\nreturned by virtue of being contained in the glob that names it. A phase-named\nsubroutine will usually be alive by virtue of the reference owned by the phase's\nautomatic run queue. A \"BEGIN\" subroutine may have been destroyed already by the time\nthis function returns, but currently bugs occur in that case before the caller gets\ncontrol. It is the caller's responsibility to ensure that it knows which of these\nsituations applies.\n\nCV * newCONSTSUBflags(HV *stash, const char *name, STRLEN len,\nU32 flags, SV *sv)\n\n\"newDEFEROP\"\nNOTE: \"newDEFEROP\" is experimental and may change or be removed without notice.\n\nConstructs and returns a deferred-block statement that implements the \"defer\" semantics.\nThe \"block\" optree is consumed by this function and becomes part of the returned optree.\n\nThe \"flags\" argument carries additional flags to set on the returned op, including the\n\"opprivate\" field.\n\nOP * newDEFEROP(I32 flags, OP *block)\n\n\"newDEFSVOP\"\nConstructs and returns an op to access $.\n\nOP * newDEFSVOP()\n\n\"newFOROP\"\nConstructs, checks, and returns an op tree expressing a \"foreach\" loop (iteration through\na list of values). This is a heavyweight loop, with structure that allows exiting the\nloop by \"last\" and suchlike.\n\n\"sv\" optionally supplies the variable(s) that will be aliased to each item in turn; if\nnull, it defaults to $. \"expr\" supplies the list of values to iterate over. \"block\"\nsupplies the main body of the loop, and \"cont\" optionally supplies a \"continue\" block\nthat operates as a second half of the body. All of these optree inputs are consumed by\nthis function and become part of the constructed op tree.\n\n\"flags\" gives the eight bits of \"opflags\" for the \"leaveloop\" op and, shifted up eight\nbits, the eight bits of \"opprivate\" for the \"leaveloop\" op, except that (in both cases)\nsome bits will be set automatically.\n\nOP * newFOROP(I32 flags, OP *sv, OP *expr, OP *block, OP *cont)\n\n\"newGIVENOP\"\nConstructs, checks, and returns an op tree expressing a \"given\" block. \"cond\" supplies\nthe expression to whose value $ will be locally aliased, and \"block\" supplies the body\nof the \"given\" construct; they are consumed by this function and become part of the\nconstructed op tree. \"defsvoff\" must be zero (it used to identity the pad slot of\nlexical $).\n\nOP * newGIVENOP(OP *cond, OP *block, PADOFFSET defsvoff)\n\n\"newGVOP\"\nConstructs, checks, and returns an op of any type that involves an embedded reference to\na GV. \"type\" is the opcode. \"flags\" gives the eight bits of \"opflags\". \"gv\"\nidentifies the GV that the op should reference; calling this function does not transfer\nownership of any reference to it.\n\nOP * newGVOP(I32 type, I32 flags, GV *gv)\n\n\"newLISTOP\"\nConstructs, checks, and returns an op of any list type. \"type\" is the opcode. \"flags\"\ngives the eight bits of \"opflags\", except that \"OPfKIDS\" will be set automatically if\nrequired. \"first\" and \"last\" supply up to two ops to be direct children of the list op;\nthey are consumed by this function and become part of the constructed op tree.\n\nFor most list operators, the check function expects all the kid ops to be present\nalready, so calling \"newLISTOP(OPJOIN, ...)\" (e.g.) is not appropriate. What you want\nto do in that case is create an op of type \"OPLIST\", append more children to it, and\nthen call \"opconvertlist\". See \"opconvertlist\" for more information.\n\nOP * newLISTOP(I32 type, I32 flags, OP *first, OP *last)\n\n\"newLOGOP\"\nConstructs, checks, and returns a logical (flow control) op. \"type\" is the opcode.\n\"flags\" gives the eight bits of \"opflags\", except that \"OPfKIDS\" will be set\nautomatically, and, shifted up eight bits, the eight bits of \"opprivate\", except that\nthe bit with value 1 is automatically set. \"first\" supplies the expression controlling\nthe flow, and \"other\" supplies the side (alternate) chain of ops; they are consumed by\nthis function and become part of the constructed op tree.\n\nOP * newLOGOP(I32 optype, I32 flags, OP *first, OP *other)\n\n\"newLOOPEX\"\nConstructs, checks, and returns a loop-exiting op (such as \"goto\" or \"last\"). \"type\" is\nthe opcode. \"label\" supplies the parameter determining the target of the op; it is\nconsumed by this function and becomes part of the constructed op tree.\n\nOP * newLOOPEX(I32 type, OP *label)\n\n\"newLOOPOP\"\nConstructs, checks, and returns an op tree expressing a loop. This is only a loop in the\ncontrol flow through the op tree; it does not have the heavyweight loop structure that\nallows exiting the loop by \"last\" and suchlike. \"flags\" gives the eight bits of\n\"opflags\" for the top-level op, except that some bits will be set automatically as\nrequired. \"expr\" supplies the expression controlling loop iteration, and \"block\"\nsupplies the body of the loop; they are consumed by this function and become part of the\nconstructed op tree. \"debuggable\" is currently unused and should always be 1.\n\nOP * newLOOPOP(I32 flags, I32 debuggable, OP *expr, OP *block)\n\n\"newMETHOP\"\nConstructs, checks, and returns an op of method type with a method name evaluated at\nruntime. \"type\" is the opcode. \"flags\" gives the eight bits of \"opflags\", except that\n\"OPfKIDS\" will be set automatically, and, shifted up eight bits, the eight bits of\n\"opprivate\", except that the bit with value 1 is automatically set. \"dynamicmeth\"\nsupplies an op which evaluates method name; it is consumed by this function and become\npart of the constructed op tree. Supported optypes: \"OPMETHOD\".\n\nOP * newMETHOP(I32 type, I32 flags, OP *dynamicmeth)\n\n\"newMETHOPnamed\"\nConstructs, checks, and returns an op of method type with a constant method name. \"type\"\nis the opcode. \"flags\" gives the eight bits of \"opflags\", and, shifted up eight bits,\nthe eight bits of \"opprivate\". \"constmeth\" supplies a constant method name; it must be\na shared COW string. Supported optypes: \"OPMETHODNAMED\".\n\nOP * newMETHOPnamed(I32 type, I32 flags, SV * constmeth)\n\n\"newNULLLIST\"\nConstructs, checks, and returns a new \"stub\" op, which represents an empty list\nexpression.\n\nOP * newNULLLIST()\n\n\"newOP\"\nConstructs, checks, and returns an op of any base type (any type that has no extra\nfields). \"type\" is the opcode. \"flags\" gives the eight bits of \"opflags\", and, shifted\nup eight bits, the eight bits of \"opprivate\".\n\nOP * newOP(I32 optype, I32 flags)\n\n\"newPADOP\"\nConstructs, checks, and returns an op of any type that involves a reference to a pad\nelement. \"type\" is the opcode. \"flags\" gives the eight bits of \"opflags\". A pad slot\nis automatically allocated, and is populated with \"sv\"; this function takes ownership of\none reference to it.\n\nThis function only exists if Perl has been compiled to use ithreads.\n\nOP * newPADOP(I32 type, I32 flags, SV *sv)\n\n\"newPMOP\"\nConstructs, checks, and returns an op of any pattern matching type. \"type\" is the\nopcode. \"flags\" gives the eight bits of \"opflags\" and, shifted up eight bits, the eight\nbits of \"opprivate\".\n\nOP * newPMOP(I32 type, I32 flags)\n\n\"newPVOP\"\nConstructs, checks, and returns an op of any type that involves an embedded C-level\npointer (PV). \"type\" is the opcode. \"flags\" gives the eight bits of \"opflags\". \"pv\"\nsupplies the C-level pointer. Depending on the op type, the memory referenced by \"pv\"\nmay be freed when the op is destroyed. If the op is of a freeing type, \"pv\" must have\nbeen allocated using \"PerlMemSharedmalloc\".\n\nOP * newPVOP(I32 type, I32 flags, char *pv)\n\n\"newRANGE\"\nConstructs and returns a \"range\" op, with subordinate \"flip\" and \"flop\" ops. \"flags\"\ngives the eight bits of \"opflags\" for the \"flip\" op and, shifted up eight bits, the\neight bits of \"opprivate\" for both the \"flip\" and \"range\" ops, except that the bit with\nvalue 1 is automatically set. \"left\" and \"right\" supply the expressions controlling the\nendpoints of the range; they are consumed by this function and become part of the\nconstructed op tree.\n\nOP * newRANGE(I32 flags, OP *left, OP *right)\n\n\"newSLICEOP\"\nConstructs, checks, and returns an \"lslice\" (list slice) op. \"flags\" gives the eight\nbits of \"opflags\", except that \"OPfKIDS\" will be set automatically, and, shifted up\neight bits, the eight bits of \"opprivate\", except that the bit with value 1 or 2 is\nautomatically set as required. \"listval\" and \"subscript\" supply the parameters of the\nslice; they are consumed by this function and become part of the constructed op tree.\n\nOP * newSLICEOP(I32 flags, OP *subscript, OP *listop)\n\n\"newSTATEOP\"\nConstructs a state op (COP). The state op is normally a \"nextstate\" op, but will be a\n\"dbstate\" op if debugging is enabled for currently-compiled code. The state op is\npopulated from \"PLcurcop\" (or \"PLcompiling\"). If \"label\" is non-null, it supplies the\nname of a label to attach to the state op; this function takes ownership of the memory\npointed at by \"label\", and will free it. \"flags\" gives the eight bits of \"opflags\" for\nthe state op.\n\nIf \"o\" is null, the state op is returned. Otherwise the state op is combined with \"o\"\ninto a \"lineseq\" list op, which is returned. \"o\" is consumed by this function and\nbecomes part of the returned op tree.\n\nOP * newSTATEOP(I32 flags, char *label, OP *o)\n\n\"newSUB\"\nLike \"newATTRSUB\", but without attributes.\n\nCV * newSUB(I32 floor, OP *o, OP *proto, OP *block)\n\n\"newSVOP\"\nConstructs, checks, and returns an op of any type that involves an embedded SV. \"type\"\nis the opcode. \"flags\" gives the eight bits of \"opflags\". \"sv\" gives the SV to embed\nin the op; this function takes ownership of one reference to it.\n\nOP * newSVOP(I32 type, I32 flags, SV *sv)\n\n\"newTRYCATCHOP\"\nNOTE: \"newTRYCATCHOP\" is experimental and may change or be removed without notice.\n\nConstructs and returns a conditional execution statement that implements the\n\"try\"/\"catch\" semantics. First the op tree in \"tryblock\" is executed, inside a context\nthat traps exceptions. If an exception occurs then the optree in \"catchblock\" is\nexecuted, with the trapped exception set into the lexical variable given by \"catchvar\"\n(which must be an op of type \"OPPADSV\"). All the optrees are consumed by this function\nand become part of the returned op tree.\n\nThe \"flags\" argument is currently ignored.\n\nOP * newTRYCATCHOP(I32 flags, OP *tryblock, OP *catchvar,\nOP *catchblock)\n\n\"newUNOP\"\nConstructs, checks, and returns an op of any unary type. \"type\" is the opcode. \"flags\"\ngives the eight bits of \"opflags\", except that \"OPfKIDS\" will be set automatically if\nrequired, and, shifted up eight bits, the eight bits of \"opprivate\", except that the bit\nwith value 1 is automatically set. \"first\" supplies an optional op to be the direct\nchild of the unary op; it is consumed by this function and become part of the constructed\nop tree.\n\nOP * newUNOP(I32 type, I32 flags, OP *first)\n\n\"newUNOPAUX\"\nSimilar to \"newUNOP\", but creates an \"UNOPAUX\" struct instead, with \"opaux\" initialised\nto \"aux\"\n\nOP * newUNOPAUX(I32 type, I32 flags, OP *first,\nUNOPAUXitem *aux)\n\n\"newWHENOP\"\nConstructs, checks, and returns an op tree expressing a \"when\" block. \"cond\" supplies\nthe test expression, and \"block\" supplies the block that will be executed if the test\nevaluates to true; they are consumed by this function and become part of the constructed\nop tree. \"cond\" will be interpreted DWIMically, often as a comparison against $, and\nmay be null to generate a \"default\" block.\n\nOP * newWHENOP(OP *cond, OP *block)\n\n\"newWHILEOP\"\nConstructs, checks, and returns an op tree expressing a \"while\" loop. This is a\nheavyweight loop, with structure that allows exiting the loop by \"last\" and suchlike.\n\n\"loop\" is an optional preconstructed \"enterloop\" op to use in the loop; if it is null\nthen a suitable op will be constructed automatically. \"expr\" supplies the loop's\ncontrolling expression. \"block\" supplies the main body of the loop, and \"cont\"\noptionally supplies a \"continue\" block that operates as a second half of the body. All\nof these optree inputs are consumed by this function and become part of the constructed\nop tree.\n\n\"flags\" gives the eight bits of \"opflags\" for the \"leaveloop\" op and, shifted up eight\nbits, the eight bits of \"opprivate\" for the \"leaveloop\" op, except that (in both cases)\nsome bits will be set automatically. \"debuggable\" is currently unused and should always\nbe 1. \"hasmy\" can be supplied as true to force the loop body to be enclosed in its own\nscope.\n\nOP * newWHILEOP(I32 flags, I32 debuggable, LOOP *loop, OP *expr,\nOP *block, OP *cont, I32 hasmy)\n\n\"newXS\"\nUsed by \"xsubpp\" to hook up XSUBs as Perl subs. \"filename\" needs to be static storage,\nas it is used directly as CvFILE(), without a copy being made.\n\n\"OABASEOP\"\n\"OABINOP\"\n\"OACOP\"\n\"OALISTOP\"\n\"OALOGOP\"\n\"OALOOP\"\n\"OAPADOP\"\n\"OAPMOP\"\n\"OAPVOPORSVOP\"\n\"OASVOP\"\n\"OAUNOP\"\nDescribed in perlguts.\n\n\"OP\"\nDescribed in perlguts.\n\n\"opappendelem\"\nAppend an item to the list of ops contained directly within a list-type op, returning the\nlengthened list. \"first\" is the list-type op, and \"last\" is the op to append to the\nlist. \"optype\" specifies the intended opcode for the list. If \"first\" is not already a\nlist of the right type, it will be upgraded into one. If either \"first\" or \"last\" is\nnull, the other is returned unchanged.\n\nOP * opappendelem(I32 optype, OP *first, OP *last)\n\n\"opappendlist\"\nConcatenate the lists of ops contained directly within two list-type ops, returning the\ncombined list. \"first\" and \"last\" are the list-type ops to concatenate. \"optype\"\nspecifies the intended opcode for the list. If either \"first\" or \"last\" is not already a\nlist of the right type, it will be upgraded into one. If either \"first\" or \"last\" is\nnull, the other is returned unchanged.\n\nOP * opappendlist(I32 optype, OP *first, OP *last)\n\n\"OPCLASS\"\nReturn the class of the provided OP: that is, which of the *OP structures it uses. For\ncore ops this currently gets the information out of \"PLopargs\", which does not always\naccurately reflect the type used; in v5.26 onwards, see also the function \"opclass\"\nwhich can do a better job of determining the used type.\n\nFor custom ops the type is returned from the registration, and it is up to the registree\nto ensure it is accurate. The value returned will be one of the \"OA\"* constants from\nop.h.\n\nU32 OPCLASS(OP *o)\n\n\"opcontextualize\"\nApplies a syntactic context to an op tree representing an expression. \"o\" is the op\ntree, and \"context\" must be \"GSCALAR\", \"GLIST\", or \"GVOID\" to specify the context to\napply. The modified op tree is returned.\n\nOP * opcontextualize(OP *o, I32 context)\n\n\"opconvertlist\"\nConverts \"o\" into a list op if it is not one already, and then converts it into the\nspecified \"type\", calling its check function, allocating a target if it needs one, and\nfolding constants.\n\nA list-type op is usually constructed one kid at a time via \"newLISTOP\",\n\"opprependelem\" and \"opappendelem\". Then finally it is passed to \"opconvertlist\"\nto make it the right type.\n\nOP * opconvertlist(I32 optype, I32 flags, OP *o)\n\n\"OPDESC\"\nReturn a short description of the provided OP.\n\nconst char * OPDESC(OP *o)\n\n\"opforcelist\"\nPromotes o and any siblings to be an \"OPLIST\" if it is not already. If a new \"OPLIST\"\nop was created, its first child will be \"OPPUSHMARK\". The returned node itself will be\nnulled, leaving only its children.\n\nThis is often what you want to do before putting the optree into list context; as\n\no = opcontextualize(opforcelist(o), GLIST);\n\nOP * opforcelist(OP *o)\n\n\"opfree\"\nFree an op and its children. Only use this when an op is no longer linked to from any\noptree.\n\nRemember that any op with \"OPfKIDS\" set is expected to have a valid \"opfirst\" pointer.\nIf you are attempting to free an op but preserve its child op, make sure to clear that\nflag before calling opfree(). For example:\n\nOP *kid = o->opfirst; o->opfirst = NULL;\no->opflags &= ~OPfKIDS;\nopfree(o);\n\nvoid opfree(OP *arg)\n\n\"OpHASSIBLING\"\nReturns true if \"o\" has a sibling\n\nbool OpHASSIBLING(OP *o)\n\n\"OpLASTSIBset\"\nMarks \"o\" as having no further siblings and marks o as having the specified parent. See\nalso \"OpMORESIBset\" and \"OpMAYBESIBset\". For a higher-level interface, see\n\"opsiblingsplice\".\n\nvoid OpLASTSIBset(OP *o, OP *parent)\n\n\"oplinklist\"\nThis function is the implementation of the \"LINKLIST\" macro. It should not be called\ndirectly.\n\nOP * oplinklist(OP *o)\n\n\"oplvalue\"\nNOTE: \"oplvalue\" is experimental and may change or be removed without notice.\n\nPropagate lvalue (\"modifiable\") context to an op and its children. \"type\" represents the\ncontext type, roughly based on the type of op that would do the modifying, although\nlocal() is represented by \"OPNULL\", because it has no op type of its own (it is\nsignalled by a flag on the lvalue op).\n\nThis function detects things that can't be modified, such as \"$x+1\", and generates errors\nfor them. For example, \"$x+1 = 2\" would cause it to be called with an op of type\n\"OPADD\" and a \"type\" argument of \"OPSASSIGN\".\n\nIt also flags things that need to behave specially in an lvalue context, such as \"$$x =\n5\" which might have to vivify a reference in $x.\n\nOP * oplvalue(OP *o, I32 type)\n\n\"OpMAYBESIBset\"\nConditionally does \"OpMORESIBset\" or \"OpLASTSIBset\" depending on whether \"sib\" is non-\nnull. For a higher-level interface, see \"opsiblingsplice\".\n\nvoid OpMAYBESIBset(OP *o, OP *sib, OP *parent)\n\n\"OpMORESIBset\"\nSets the sibling of \"o\" to the non-zero value \"sib\". See also \"OpLASTSIBset\" and\n\"OpMAYBESIBset\". For a higher-level interface, see \"opsiblingsplice\".\n\nvoid OpMORESIBset(OP *o, OP *sib)\n\n\"OPNAME\"\nReturn the name of the provided OP. For core ops this looks up the name from the\noptype; for custom ops from the opppaddr.\n\nconst char * OPNAME(OP *o)\n\n\"opnull\"\nNeutralizes an op when it is no longer needed, but is still linked to from other ops.\n\nvoid opnull(OP *o)\n\n\"opparent\"\nReturns the parent OP of \"o\", if it has a parent. Returns \"NULL\" otherwise.\n\nOP * opparent(OP *o)\n\n\"opprependelem\"\nPrepend an item to the list of ops contained directly within a list-type op, returning\nthe lengthened list. \"first\" is the op to prepend to the list, and \"last\" is the list-\ntype op. \"optype\" specifies the intended opcode for the list. If \"last\" is not already\na list of the right type, it will be upgraded into one. If either \"first\" or \"last\" is\nnull, the other is returned unchanged.\n\nOP * opprependelem(I32 optype, OP *first, OP *last)\n\n\"opscope\"\nNOTE: \"opscope\" is experimental and may change or be removed without notice.\n\nWraps up an op tree with some additional ops so that at runtime a dynamic scope will be\ncreated. The original ops run in the new dynamic scope, and then, provided that they\nexit normally, the scope will be unwound. The additional ops used to create and unwind\nthe dynamic scope will normally be an \"enter\"/\"leave\" pair, but a \"scope\" op may be used\ninstead if the ops are simple enough to not need the full dynamic scope structure.\n\nOP * opscope(OP *o)\n\n\"OpSIBLING\"\nReturns the sibling of \"o\", or \"NULL\" if there is no sibling\n\nOP* OpSIBLING(OP *o)\n\n\"opsiblingsplice\"\nA general function for editing the structure of an existing chain of opsibling nodes.\nBy analogy with the perl-level splice() function, allows you to delete zero or more\nsequential nodes, replacing them with zero or more different nodes. Performs the\nnecessary opfirst/oplast housekeeping on the parent node and opsibling manipulation on\nthe children. The last deleted node will be marked as the last node by updating the\nopsibling/opsibparent or opmoresib field as appropriate.\n\nNote that opnext is not manipulated, and nodes are not freed; that is the responsibility\nof the caller. It also won't create a new list op for an empty list etc; use higher-\nlevel functions like opappendelem() for that.\n\n\"parent\" is the parent node of the sibling chain. It may passed as \"NULL\" if the splicing\ndoesn't affect the first or last op in the chain.\n\n\"start\" is the node preceding the first node to be spliced. Node(s) following it will be\ndeleted, and ops will be inserted after it. If it is \"NULL\", the first node onwards is\ndeleted, and nodes are inserted at the beginning.\n\n\"delcount\" is the number of nodes to delete. If zero, no nodes are deleted. If -1 or\ngreater than or equal to the number of remaining kids, all remaining kids are deleted.\n\n\"insert\" is the first of a chain of nodes to be inserted in place of the nodes. If\n\"NULL\", no nodes are inserted.\n\nThe head of the chain of deleted ops is returned, or \"NULL\" if no ops were deleted.\n\nFor example:\n\naction before after returns\n------ ----- ----- -------\n\nP P\nsplice(P, A, 2, X-Y-Z) | | B-C\nA-B-C-D A-X-Y-Z-D\n\nP P\nsplice(P, NULL, 1, X-Y) | | A\nA-B-C-D X-Y-B-C-D\n\nP P\nsplice(P, NULL, 3, NULL) | | A-B-C\nA-B-C-D D\n\nP P\nsplice(P, B, 0, X-Y) | | NULL\nA-B-C-D A-B-X-Y-C-D\n\nFor lower-level direct manipulation of \"opsibparent\" and \"opmoresib\", see\n\"OpMORESIBset\", \"OpLASTSIBset\", \"OpMAYBESIBset\".\n\nOP * opsiblingsplice(OP *parent, OP *start, int delcount,\nOP *insert)\n\n\"optimizeoptree\"\nThis function applies some optimisations to the optree in top-down order. It is called\nbefore the peephole optimizer, which processes ops in execution order. Note that\nfinalizeoptree() also does a top-down scan, but is called *after* the peephole\noptimizer.\n\nvoid optimizeoptree(OP *o)\n\n\"OPTYPEIS\"\nReturns true if the given OP is not a \"NULL\" pointer and if it is of the given type.\n\nThe negation of this macro, \"OPTYPEISNT\" is also available as well as \"OPTYPEISNN\"\nand \"OPTYPEISNTNN\" which elide the NULL pointer check.\n\nbool OPTYPEIS(OP *o, Optype type)\n\n\"OPTYPEISORWAS\"\nReturns true if the given OP is not a NULL pointer and if it is of the given type or used\nto be before being replaced by an OP of type OPNULL.\n\nThe negation of this macro, \"OPTYPEISNTANDWASNT\" is also available as well as\n\"OPTYPEISORWASNN\" and \"OPTYPEISNTANDWASNTNN\" which elide the \"NULL\" pointer\ncheck.\n\nbool OPTYPEISORWAS(OP *o, Optype type)\n\n\"opwrapfinally\"\nNOTE: \"opwrapfinally\" is experimental and may change or be removed without notice.\n\nWraps the given \"block\" optree fragment in its own scoped block, arranging for the\n\"finally\" optree fragment to be invoked when leaving that block for any reason. Both\noptree fragments are consumed and the combined result is returned.\n\nOP * opwrapfinally(OP *block, OP *finally)\n\n\"peept\"\nDescribed in perlguts.\n\n\"Perlcpeept\"\nDescribed in perlguts.\n\n\"PLopfreehook\"\nWhen non-\"NULL\", the function pointed by this variable will be called each time an OP is\nfreed with the corresponding OP as the argument. This allows extensions to free any\nextra attribute they have locally attached to an OP. It is also assured to first fire\nfor the parent OP and then for its kids.\n\nWhen you replace this variable, it is considered a good practice to store the possibly\npreviously installed hook and that you recall it inside your own.\n\nOn threaded perls, each thread has an independent copy of this variable; each initialized\nat creation time with the current value of the creating thread's copy.\n\nPerlophookt PLopfreehook\n\n\"PLpeepp\"\nPointer to the per-subroutine peephole optimiser. This is a function that gets called at\nthe end of compilation of a Perl subroutine (or equivalently independent piece of Perl\ncode) to perform fixups of some ops and to perform small-scale optimisations. The\nfunction is called once for each subroutine that is compiled, and is passed, as sole\nparameter, a pointer to the op that is the entry point to the subroutine. It modifies\nthe op tree in place.\n\nThe peephole optimiser should never be completely replaced. Rather, add code to it by\nwrapping the existing optimiser. The basic way to do this can be seen in \"Compile pass\n3: peephole optimization\" in perlguts. If the new code wishes to operate on ops\nthroughout the subroutine's structure, rather than just at the top level, it is likely to\nbe more convenient to wrap the \"PLrpeepp\" hook.\n\nOn threaded perls, each thread has an independent copy of this variable; each initialized\nat creation time with the current value of the creating thread's copy.\n\npeept PLpeepp\n\n\"PLrpeepp\"\nPointer to the recursive peephole optimiser. This is a function that gets called at the\nend of compilation of a Perl subroutine (or equivalently independent piece of Perl code)\nto perform fixups of some ops and to perform small-scale optimisations. The function is\ncalled once for each chain of ops linked through their \"opnext\" fields; it is\nrecursively called to handle each side chain. It is passed, as sole parameter, a pointer\nto the op that is at the head of the chain. It modifies the op tree in place.\n\nThe peephole optimiser should never be completely replaced. Rather, add code to it by\nwrapping the existing optimiser. The basic way to do this can be seen in \"Compile pass\n3: peephole optimization\" in perlguts. If the new code wishes to operate only on ops at\na subroutine's top level, rather than throughout the structure, it is likely to be more\nconvenient to wrap the \"PLpeepp\" hook.\n\nOn threaded perls, each thread has an independent copy of this variable; each initialized\nat creation time with the current value of the creating thread's copy.\n\npeept PLrpeepp\n\n\"PMOP\"\nDescribed in perlguts.\n\n\"rv2cvopcv\"\nExamines an op, which is expected to identify a subroutine at runtime, and attempts to\ndetermine at compile time which subroutine it identifies. This is normally used during\nPerl compilation to determine whether a prototype can be applied to a function call.\n\"cvop\" is the op being considered, normally an \"rv2cv\" op. A pointer to the identified\nsubroutine is returned, if it could be determined statically, and a null pointer is\nreturned if it was not possible to determine statically.\n\nCurrently, the subroutine can be identified statically if the RV that the \"rv2cv\" is to\noperate on is provided by a suitable \"gv\" or \"const\" op. A \"gv\" op is suitable if the\nGV's CV slot is populated. A \"const\" op is suitable if the constant value must be an RV\npointing to a CV. Details of this process may change in future versions of Perl. If the\n\"rv2cv\" op has the \"OPpENTERSUBAMPER\" flag set then no attempt is made to identify the\nsubroutine statically: this flag is used to suppress compile-time magic on a subroutine\ncall, forcing it to use default runtime behaviour.\n\nIf \"flags\" has the bit \"RV2CVOPCVMARKEARLY\" set, then the handling of a GV reference is\nmodified. If a GV was examined and its CV slot was found to be empty, then the \"gv\" op\nhas the \"OPpEARLYCV\" flag set. If the op is not optimised away, and the CV slot is\nlater populated with a subroutine having a prototype, that flag eventually triggers the\nwarning \"called too early to check prototype\".\n\nIf \"flags\" has the bit \"RV2CVOPCVRETURNNAMEGV\" set, then instead of returning a\npointer to the subroutine it returns a pointer to the GV giving the most appropriate name\nfor the subroutine in this context. Normally this is just the \"CvGV\" of the subroutine,\nbut for an anonymous (\"CvANON\") subroutine that is referenced through a GV it will be the\nreferencing GV. The resulting \"GV*\" is cast to \"CV*\" to be returned. A null pointer is\nreturned as usual if there is no statically-determinable subroutine.\n\nCV * rv2cvopcv(OP *cvop, U32 flags)\n\n\"UNOP\"\nDescribed in perlguts.\n\n\"XOP\"\nDescribed in perlguts.\n\nPack and Unpack\n\"packlist\"\nThe engine implementing pack() Perl function.\n\nvoid packlist(SV *cat, const char *pat, const char *patend,\nSV beglist, SV endlist)\n\n\"unpackstring\"\nThe engine implementing the unpack() Perl function.\n\nUsing the template \"pat..patend\", this function unpacks the string \"s..strend\" into a\nnumber of mortal SVs, which it pushes onto the perl argument (@) stack (so you will need\nto issue a \"PUTBACK\" before and \"SPAGAIN\" after the call to this function). It returns\nthe number of pushed elements.\n\nThe \"strend\" and \"patend\" pointers should point to the byte following the last character\nof each string.\n\nAlthough this function returns its values on the perl argument stack, it doesn't take any\nparameters from that stack (and thus in particular there's no need to do a \"PUSHMARK\"\nbefore calling it, unlike \"callpv\" for example).\n\nSSizet unpackstring(const char *pat, const char *patend,\nconst char *s, const char *strend,\nU32 flags)\n", "subsections": [] }, "Pad Data Structures": { "content": "\"CvPADLIST\"\nNOTE: \"CvPADLIST\" is experimental and may change or be removed without notice.\n\nCV's can have CvPADLIST(cv) set to point to a PADLIST. This is the CV's scratchpad,\nwhich stores lexical variables and opcode temporary and per-thread values.\n\nFor these purposes \"formats\" are a kind-of CV; eval\"\"s are too (except they're not\ncallable at will and are always thrown away after the eval\"\" is done executing).\nRequire'd files are simply evals without any outer lexical scope.\n\nXSUBs do not have a \"CvPADLIST\". \"dXSTARG\" fetches values from \"PLcurpad\", but that is\nreally the callers pad (a slot of which is allocated by every entersub). Do not get or\nset \"CvPADLIST\" if a CV is an XSUB (as determined by CvISXSUB()), \"CvPADLIST\" slot is\nreused for a different internal purpose in XSUBs.\n\nThe PADLIST has a C array where pads are stored.\n\nThe 0th entry of the PADLIST is a PADNAMELIST which represents the \"names\" or rather the\n\"static type information\" for lexicals. The individual elements of a PADNAMELIST are\nPADNAMEs. Future refactorings might stop the PADNAMELIST from being stored in the\nPADLIST's array, so don't rely on it. See \"PadlistNAMES\".\n\nThe CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the stack frame at that depth\nof recursion into the CV. The 0th slot of a frame AV is an AV which is @. Other\nentries are storage for variables and op targets.\n\nIterating over the PADNAMELIST iterates over all possible pad items. Pad slots for\ntargets (\"SVsPADTMP\") and GVs end up having &PLpadnameundef \"names\", while slots for\nconstants have &PLpadnameconst \"names\" (see \"padalloc\"). That &PLpadnameundef and\n&PLpadnameconst are used is an implementation detail subject to change. To test for\nthem, use \"!PadnamePV(name)\" and \"PadnamePV(name) && !PadnameLEN(name)\", respectively.\n\nOnly \"my\"/\"our\" variable slots get valid names. The rest are op targets/GVs/constants\nwhich are statically allocated or resolved at compile time. These don't have names by\nwhich they can be looked up from Perl code at run time through eval\"\" the way \"my\"/\"our\"\nvariables can be. Since they can't be looked up by \"name\" but only by their index\nallocated at compile time (which is usually in \"PLop->optarg\"), wasting a name SV for\nthem doesn't make sense.\n\nThe pad names in the PADNAMELIST have their PV holding the name of the variable. The\n\"COPSEQRANGELOW\" and \"HIGH\" fields form a range (low+1..high inclusive) of copseq\nnumbers for which the name is valid. During compilation, these fields may hold the\nspecial value PERLPADSEQINTRO to indicate various stages:\n\nCOPSEQRANGELOW HIGH\n----------------- -----\nPERLPADSEQINTRO 0 variable not yet introduced:\n{ my ($x\nvalid-seq# PERLPADSEQINTRO variable in scope:\n{ my ($x);\nvalid-seq# valid-seq# compilation of scope complete:\n{ my ($x); .... }\n\nWhen a lexical var hasn't yet been introduced, it already exists from the perspective of\nduplicate declarations, but not for variable lookups, e.g.\n\nmy ($x, $x); # '\"my\" variable $x masks earlier declaration'\nmy $x = $x; # equal to my $x = $::x;\n\nFor typed lexicals \"PadnameTYPE\" points at the type stash. For \"our\" lexicals,\n\"PadnameOURSTASH\" points at the stash of the associated global (so that duplicate \"our\"\ndeclarations in the same package can be detected). \"PadnameGEN\" is sometimes used to\nstore the generation number during compilation.\n\nIf \"PadnameOUTER\" is set on the pad name, then that slot in the frame AV is a REFCNT'ed\nreference to a lexical from \"outside\". Such entries are sometimes referred to as 'fake'.\nIn this case, the name does not use 'low' and 'high' to store a copseq range, since it\nis in scope throughout. Instead 'high' stores some flags containing info about the real\nlexical (is it declared in an anon, and is it capable of being instantiated multiple\ntimes?), and for fake ANONs, 'low' contains the index within the parent's pad where the\nlexical's value is stored, to make cloning quicker.\n\nIf the 'name' is \"&\" the corresponding entry in the PAD is a CV representing a possible\nclosure.\n\nNote that formats are treated as anon subs, and are cloned each time write is called (if\nnecessary).\n\nThe flag \"SVsPADSTALE\" is cleared on lexicals each time the my() is executed, and set on\nscope exit. This allows the \"Variable $x is not available\" warning to be generated in\nevals, such as\n\n{ my $x = 1; sub f { eval '$x'} } f();\n\nFor state vars, \"SVsPADSTALE\" is overloaded to mean 'not yet initialised', but this\ninternal state is stored in a separate pad entry.\n\nPADLIST * CvPADLIST(CV *cv)\n\n\"padaddnamepvs\"\nExactly like \"padaddnamepvn\", but takes a literal string instead of a string/length\npair.\n\nPADOFFSET padaddnamepvs(\"name\", U32 flags, HV *typestash,\nHV *ourstash)\n\n\"PadARRAY\"\nNOTE: \"PadARRAY\" is experimental and may change or be removed without notice.\n\nThe C array of pad entries.\n\nSV PadARRAY(PAD * pad)\n\n\"padfindmypvs\"\nExactly like \"padfindmypvn\", but takes a literal string instead of a string/length\npair.\n\nPADOFFSET padfindmypvs(\"name\", U32 flags)\n\n\"PadlistARRAY\"\nNOTE: \"PadlistARRAY\" is experimental and may change or be removed without notice.\n\nThe C array of a padlist, containing the pads. Only subscript it with numbers >= 1, as\nthe 0th entry is not guaranteed to remain usable.\n\nPAD PadlistARRAY(PADLIST * padlist)\n\n\"PadlistMAX\"\nNOTE: \"PadlistMAX\" is experimental and may change or be removed without notice.\n\nThe index of the last allocated space in the padlist. Note that the last pad may be in\nan earlier slot. Any entries following it will be \"NULL\" in that case.\n\nSSizet PadlistMAX(PADLIST * padlist)\n\n\"PadlistNAMES\"\nNOTE: \"PadlistNAMES\" is experimental and may change or be removed without notice.\n\nThe names associated with pad entries.\n\nPADNAMELIST * PadlistNAMES(PADLIST * padlist)\n\n\"PadlistNAMESARRAY\"\nNOTE: \"PadlistNAMESARRAY\" is experimental and may change or be removed without notice.\n\nThe C array of pad names.\n\nPADNAME PadlistNAMESARRAY(PADLIST * padlist)\n\n\"PadlistNAMESMAX\"\nNOTE: \"PadlistNAMESMAX\" is experimental and may change or be removed without notice.\n\nThe index of the last pad name.\n\nSSizet PadlistNAMESMAX(PADLIST * padlist)\n\n\"PadlistREFCNT\"\nNOTE: \"PadlistREFCNT\" is experimental and may change or be removed without notice.\n\nThe reference count of the padlist. Currently this is always 1.\n\nU32 PadlistREFCNT(PADLIST * padlist)\n\n\"PadMAX\"\nNOTE: \"PadMAX\" is experimental and may change or be removed without notice.\n\nThe index of the last pad entry.\n\nSSizet PadMAX(PAD * pad)\n\n\"PadnameLEN\"\nNOTE: \"PadnameLEN\" is experimental and may change or be removed without notice.\n\nThe length of the name.\n\nSTRLEN PadnameLEN(PADNAME * pn)\n\n\"PadnamelistARRAY\"\nNOTE: \"PadnamelistARRAY\" is experimental and may change or be removed without notice.\n\nThe C array of pad names.\n\nPADNAME PadnamelistARRAY(PADNAMELIST * pnl)\n\n\"PadnamelistMAX\"\nNOTE: \"PadnamelistMAX\" is experimental and may change or be removed without notice.\n\nThe index of the last pad name.\n\nSSizet PadnamelistMAX(PADNAMELIST * pnl)\n\n\"PadnamelistREFCNT\"\nNOTE: \"PadnamelistREFCNT\" is experimental and may change or be removed without notice.\n\nThe reference count of the pad name list.\n\nSSizet PadnamelistREFCNT(PADNAMELIST * pnl)\n\n\"PadnamelistREFCNTdec\"\nNOTE: \"PadnamelistREFCNTdec\" is experimental and may change or be removed without\nnotice.\n\nLowers the reference count of the pad name list.\n\nvoid PadnamelistREFCNTdec(PADNAMELIST * pnl)\n\n\"PadnamePV\"\nNOTE: \"PadnamePV\" is experimental and may change or be removed without notice.\n\nThe name stored in the pad name struct. This returns \"NULL\" for a target slot.\n\nchar * PadnamePV(PADNAME * pn)\n\n\"PadnameREFCNT\"\nNOTE: \"PadnameREFCNT\" is experimental and may change or be removed without notice.\n\nThe reference count of the pad name.\n\nSSizet PadnameREFCNT(PADNAME * pn)\n\n\"PadnameREFCNTdec\"\nNOTE: \"PadnameREFCNTdec\" is experimental and may change or be removed without notice.\n\nLowers the reference count of the pad name.\n\nvoid PadnameREFCNTdec(PADNAME * pn)\n\n\"PadnameREFCNTinc\"\nNOTE: \"PadnameREFCNTinc\" is experimental and may change or be removed without notice.\n\nIncreases the reference count of the pad name. Returns the pad name itself.\n\nPADNAME * PadnameREFCNTinc(PADNAME * pn)\n\n\"PadnameSV\"\nNOTE: \"PadnameSV\" is experimental and may change or be removed without notice.\n\nReturns the pad name as a mortal SV.\n\nSV * PadnameSV(PADNAME * pn)\n\n\"PadnameUTF8\"\nNOTE: \"PadnameUTF8\" is experimental and may change or be removed without notice.\n\nWhether PadnamePV is in UTF-8. Currently, this is always true.\n\nbool PadnameUTF8(PADNAME * pn)\n\n\"padnew\"\nCreate a new padlist, updating the global variables for the currently-compiling padlist\nto point to the new padlist. The following flags can be OR'ed together:\n\npadnewCLONE this pad is for a cloned CV\npadnewSAVE save old globals on the save stack\npadnewSAVESUB also save extra stuff for start of sub\n\nPADLIST * padnew(int flags)\n\n\"PLcomppad\"\nNOTE: \"PLcomppad\" is experimental and may change or be removed without notice.\n\nDuring compilation, this points to the array containing the values part of the pad for\nthe currently-compiling code. (At runtime a CV may have many such value arrays; at\ncompile time just one is constructed.) At runtime, this points to the array containing\nthe currently-relevant values for the pad for the currently-executing code.\n\n\"PLcomppadname\"\nNOTE: \"PLcomppadname\" is experimental and may change or be removed without notice.\n\nDuring compilation, this points to the array containing the names part of the pad for the\ncurrently-compiling code.\n\n\"PLcurpad\"\nNOTE: \"PLcurpad\" is experimental and may change or be removed without notice.\n\nPoints directly to the body of the \"PLcomppad\" array. (I.e., this is\nPadARRAY(PLcomppad).)\n\n\"SVsPADMY\"\n\"DEPRECATED!\" It is planned to remove \"SVsPADMY\" from a future release of Perl. Do not\nuse it for new code; remove it from existing code.\n\nDescribed in perlguts.\n\n\"SVsPADTMP\"\nDescribed in perlguts.\n", "subsections": [] }, "Password and Group access": { "content": "\"GRPASSWD\"\nThis symbol, if defined, indicates to the C program that \"struct group\" in grp.h contains\n\"grpasswd\".\n\n\"HASENDGRENT\"\nThis symbol, if defined, indicates that the getgrent routine is available for finalizing\nsequential access of the group database.\n\n\"HASENDGRENTR\"\nThis symbol, if defined, indicates that the \"endgrentr\" routine is available to endgrent\nre-entrantly.\n\n\"HASENDPWENT\"\nThis symbol, if defined, indicates that the \"endpwent\" routine is available for\nfinalizing sequential access of the passwd database.\n\n\"HASENDPWENTR\"\nThis symbol, if defined, indicates that the \"endpwentr\" routine is available to endpwent\nre-entrantly.\n\n\"HASGETGRENT\"\nThis symbol, if defined, indicates that the \"getgrent\" routine is available for\nsequential access of the group database.\n\n\"HASGETGRENTR\"\nThis symbol, if defined, indicates that the \"getgrentr\" routine is available to getgrent\nre-entrantly.\n\n\"HASGETPWENT\"\nThis symbol, if defined, indicates that the \"getpwent\" routine is available for\nsequential access of the passwd database. If this is not available, the older getpw()\nfunction may be available.\n\n\"HASGETPWENTR\"\nThis symbol, if defined, indicates that the \"getpwentr\" routine is available to getpwent\nre-entrantly.\n\n\"HASSETGRENT\"\nThis symbol, if defined, indicates that the \"setgrent\" routine is available for\ninitializing sequential access of the group database.\n\n\"HASSETGRENTR\"\nThis symbol, if defined, indicates that the \"setgrentr\" routine is available to setgrent\nre-entrantly.\n\n\"HASSETPWENT\"\nThis symbol, if defined, indicates that the \"setpwent\" routine is available for\ninitializing sequential access of the passwd database.\n\n\"HASSETPWENTR\"\nThis symbol, if defined, indicates that the \"setpwentr\" routine is available to setpwent\nre-entrantly.\n\n\"PWAGE\"\nThis symbol, if defined, indicates to the C program that \"struct passwd\" contains\n\"pwage\".\n\n\"PWCHANGE\"\nThis symbol, if defined, indicates to the C program that \"struct passwd\" contains\n\"pwchange\".\n\n\"PWCLASS\"\nThis symbol, if defined, indicates to the C program that \"struct passwd\" contains\n\"pwclass\".\n\n\"PWCOMMENT\"\nThis symbol, if defined, indicates to the C program that \"struct passwd\" contains\n\"pwcomment\".\n\n\"PWEXPIRE\"\nThis symbol, if defined, indicates to the C program that \"struct passwd\" contains\n\"pwexpire\".\n\n\"PWGECOS\"\nThis symbol, if defined, indicates to the C program that \"struct passwd\" contains\n\"pwgecos\".\n\n\"PWPASSWD\"\nThis symbol, if defined, indicates to the C program that \"struct passwd\" contains\n\"pwpasswd\".\n\n\"PWQUOTA\"\nThis symbol, if defined, indicates to the C program that \"struct passwd\" contains\n\"pwquota\".\n", "subsections": [] }, "Paths to system commands": { "content": "\"CSH\"\nThis symbol, if defined, contains the full pathname of csh.\n\n\"LOCSED\"\nThis symbol holds the complete pathname to the sed program.\n\n\"SHPATH\"\nThis symbol contains the full pathname to the shell used on this on this system to\nexecute Bourne shell scripts. Usually, this will be /bin/sh, though it's possible that\nsome systems will have /bin/ksh, /bin/pdksh, /bin/ash, /bin/bash, or even something such\nas D:/bin/sh.exe.\n", "subsections": [] }, "Prototype information": { "content": "\"CRYPTRPROTO\"\nThis symbol encodes the prototype of \"cryptr\". It is zero if \"dcryptr\" is undef, and\none of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dcryptr\" is defined.\n\n\"CTERMIDRPROTO\"\nThis symbol encodes the prototype of \"ctermidr\". It is zero if \"dctermidr\" is undef,\nand one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dctermidr\" is defined.\n\n\"DRAND48RPROTO\"\nThis symbol encodes the prototype of \"drand48r\". It is zero if \"ddrand48r\" is undef,\nand one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"ddrand48r\" is defined.\n\n\"ENDGRENTRPROTO\"\nThis symbol encodes the prototype of \"endgrentr\". It is zero if \"dendgrentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dendgrentr\" is\ndefined.\n\n\"ENDHOSTENTRPROTO\"\nThis symbol encodes the prototype of \"endhostentr\". It is zero if \"dendhostentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dendhostentr\" is\ndefined.\n\n\"ENDNETENTRPROTO\"\nThis symbol encodes the prototype of \"endnetentr\". It is zero if \"dendnetentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dendnetentr\" is\ndefined.\n\n\"ENDPROTOENTRPROTO\"\nThis symbol encodes the prototype of \"endprotoentr\". It is zero if \"dendprotoentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dendprotoentr\" is\ndefined.\n\n\"ENDPWENTRPROTO\"\nThis symbol encodes the prototype of \"endpwentr\". It is zero if \"dendpwentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dendpwentr\" is\ndefined.\n\n\"ENDSERVENTRPROTO\"\nThis symbol encodes the prototype of \"endserventr\". It is zero if \"dendserventr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dendserventr\" is\ndefined.\n\n\"GDBMNDBMHUSESPROTOTYPES\"\nThis symbol, if defined, indicates that gdbm/ndbm.h uses real \"ANSI\" C prototypes instead\nof K&R style function declarations without any parameter information. While \"ANSI\" C\nprototypes are supported in C++, K&R style function declarations will yield errors.\n\n\"GDBMNDBMHUSESPROTOTYPES\"\nThis symbol, if defined, indicates that uses real \"ANSI\" C prototypes\ninstead of K&R style function declarations without any parameter information. While\n\"ANSI\" C prototypes are supported in C++, K&R style function declarations will yield\nerrors.\n\n\"GETGRENTRPROTO\"\nThis symbol encodes the prototype of \"getgrentr\". It is zero if \"dgetgrentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetgrentr\" is\ndefined.\n\n\"GETGRGIDRPROTO\"\nThis symbol encodes the prototype of \"getgrgidr\". It is zero if \"dgetgrgidr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetgrgidr\" is\ndefined.\n\n\"GETGRNAMRPROTO\"\nThis symbol encodes the prototype of \"getgrnamr\". It is zero if \"dgetgrnamr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetgrnamr\" is\ndefined.\n\n\"GETHOSTBYADDRRPROTO\"\nThis symbol encodes the prototype of \"gethostbyaddrr\". It is zero if\n\"dgethostbyaddrr\" is undef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h\nif \"dgethostbyaddrr\" is defined.\n\n\"GETHOSTBYNAMERPROTO\"\nThis symbol encodes the prototype of \"gethostbynamer\". It is zero if\n\"dgethostbynamer\" is undef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h\nif \"dgethostbynamer\" is defined.\n\n\"GETHOSTENTRPROTO\"\nThis symbol encodes the prototype of \"gethostentr\". It is zero if \"dgethostentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgethostentr\" is\ndefined.\n\n\"GETLOGINRPROTO\"\nThis symbol encodes the prototype of \"getloginr\". It is zero if \"dgetloginr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetloginr\" is\ndefined.\n\n\"GETNETBYADDRRPROTO\"\nThis symbol encodes the prototype of \"getnetbyaddrr\". It is zero if \"dgetnetbyaddrr\"\nis undef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetnetbyaddrr\"\nis defined.\n\n\"GETNETBYNAMERPROTO\"\nThis symbol encodes the prototype of \"getnetbynamer\". It is zero if \"dgetnetbynamer\"\nis undef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetnetbynamer\"\nis defined.\n\n\"GETNETENTRPROTO\"\nThis symbol encodes the prototype of \"getnetentr\". It is zero if \"dgetnetentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetnetentr\" is\ndefined.\n\n\"GETPROTOBYNAMERPROTO\"\nThis symbol encodes the prototype of \"getprotobynamer\". It is zero if\n\"dgetprotobynamer\" is undef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h\nif \"dgetprotobynamer\" is defined.\n\n\"GETPROTOBYNUMBERRPROTO\"\nThis symbol encodes the prototype of \"getprotobynumberr\". It is zero if\n\"dgetprotobynumberr\" is undef, and one of the \"REENTRANTPROTOTABC\" macros of\nreentr.h if \"dgetprotobynumberr\" is defined.\n\n\"GETPROTOENTRPROTO\"\nThis symbol encodes the prototype of \"getprotoentr\". It is zero if \"dgetprotoentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetprotoentr\" is\ndefined.\n\n\"GETPWENTRPROTO\"\nThis symbol encodes the prototype of \"getpwentr\". It is zero if \"dgetpwentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetpwentr\" is\ndefined.\n\n\"GETPWNAMRPROTO\"\nThis symbol encodes the prototype of \"getpwnamr\". It is zero if \"dgetpwnamr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetpwnamr\" is\ndefined.\n\n\"GETPWUIDRPROTO\"\nThis symbol encodes the prototype of \"getpwuidr\". It is zero if \"dgetpwuidr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetpwuidr\" is\ndefined.\n\n\"GETSERVBYNAMERPROTO\"\nThis symbol encodes the prototype of \"getservbynamer\". It is zero if\n\"dgetservbynamer\" is undef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h\nif \"dgetservbynamer\" is defined.\n\n\"GETSERVBYPORTRPROTO\"\nThis symbol encodes the prototype of \"getservbyportr\". It is zero if\n\"dgetservbyportr\" is undef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h\nif \"dgetservbyportr\" is defined.\n\n\"GETSERVENTRPROTO\"\nThis symbol encodes the prototype of \"getserventr\". It is zero if \"dgetserventr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetserventr\" is\ndefined.\n\n\"GETSPNAMRPROTO\"\nThis symbol encodes the prototype of \"getspnamr\". It is zero if \"dgetspnamr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgetspnamr\" is\ndefined.\n\n\"HASDBMINITPROTO\"\nThis symbol, if defined, indicates that the system provides a prototype for the dbminit()\nfunction. Otherwise, it is up to the program to supply one. A good guess is\n\nextern int dbminit(char *);\n\n\"HASDRAND48PROTO\"\nThis symbol, if defined, indicates that the system provides a prototype for the drand48()\nfunction. Otherwise, it is up to the program to supply one. A good guess is\n\nextern double drand48(void);\n\n\"HASFLOCKPROTO\"\nThis symbol, if defined, indicates that the system provides a prototype for the flock()\nfunction. Otherwise, it is up to the program to supply one. A good guess is\n\nextern int flock(int, int);\n\n\"HASGETHOSTPROTOS\"\nThis symbol, if defined, indicates that netdb.h includes prototypes for gethostent(),\ngethostbyname(), and gethostbyaddr(). Otherwise, it is up to the program to guess them.\nSee netdbtype.U (part of metaconfig) for probing for various \"Netdbxxxt\" types.\n\n\"HASGETNETPROTOS\"\nThis symbol, if defined, indicates that netdb.h includes prototypes for getnetent(),\ngetnetbyname(), and getnetbyaddr(). Otherwise, it is up to the program to guess them.\nSee netdbtype.U (part of metaconfig) for probing for various \"Netdbxxxt\" types.\n\n\"HASGETPROTOPROTOS\"\nThis symbol, if defined, indicates that netdb.h includes prototypes for getprotoent(),\ngetprotobyname(), and getprotobyaddr(). Otherwise, it is up to the program to guess\nthem. See netdbtype.U (part of metaconfig) for probing for various \"Netdbxxxt\" types.\n\n\"HASGETSERVPROTOS\"\nThis symbol, if defined, indicates that netdb.h includes prototypes for getservent(),\ngetservbyname(), and getservbyaddr(). Otherwise, it is up to the program to guess them.\nSee netdbtype.U (part of metaconfig) for probing for various \"Netdbxxxt\" types.\n\n\"HASMODFLPROTO\"\nThis symbol, if defined, indicates that the system provides a prototype for the modfl()\nfunction. Otherwise, it is up to the program to supply one.\n\n\"HASSBRKPROTO\"\nThis symbol, if defined, indicates that the system provides a prototype for the sbrk()\nfunction. Otherwise, it is up to the program to supply one. Good guesses are\n\nextern void* sbrk(int);\nextern void* sbrk(sizet);\n\n\"HASSETRESGIDPROTO\"\nThis symbol, if defined, indicates that the system provides a prototype for the\nsetresgid() function. Otherwise, it is up to the program to supply one. Good guesses\nare\n\nextern int setresgid(uidt ruid, uidt euid, uidt suid);\n\n\"HASSETRESUIDPROTO\"\nThis symbol, if defined, indicates that the system provides a prototype for the\nsetresuid() function. Otherwise, it is up to the program to supply one. Good guesses\nare\n\nextern int setresuid(uidt ruid, uidt euid, uidt suid);\n\n\"HASSHMATPROTOTYPE\"\nThis symbol, if defined, indicates that the sys/shm.h includes a prototype for shmat().\nOtherwise, it is up to the program to guess one. \"Shmatt\" \"shmat(int, Shmatt, int)\" is\na good guess, but not always right so it should be emitted by the program only when\n\"HASSHMATPROTOTYPE\" is not defined to avoid conflicting defs.\n\n\"HASSOCKATMARKPROTO\"\nThis symbol, if defined, indicates that the system provides a prototype for the\nsockatmark() function. Otherwise, it is up to the program to supply one. A good guess\nis\n\nextern int sockatmark(int);\n\n\"HASSYSCALLPROTO\"\nThis symbol, if defined, indicates that the system provides a prototype for the syscall()\nfunction. Otherwise, it is up to the program to supply one. Good guesses are\n\nextern int syscall(int, ...);\nextern int syscall(long, ...);\n\n\"HASTELLDIRPROTO\"\nThis symbol, if defined, indicates that the system provides a prototype for the telldir()\nfunction. Otherwise, it is up to the program to supply one. A good guess is\n\nextern long telldir(DIR*);\n\n\"NDBMHUSESPROTOTYPES\"\nThis symbol, if defined, indicates that ndbm.h uses real \"ANSI\" C prototypes instead of\nK&R style function declarations without any parameter information. While \"ANSI\" C\nprototypes are supported in C++, K&R style function declarations will yield errors.\n\n\"RANDOMRPROTO\"\nThis symbol encodes the prototype of \"randomr\". It is zero if \"drandomr\" is undef,\nand one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"drandomr\" is defined.\n\n\"READDIRRPROTO\"\nThis symbol encodes the prototype of \"readdirr\". It is zero if \"dreaddirr\" is undef,\nand one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dreaddirr\" is defined.\n\n\"SETGRENTRPROTO\"\nThis symbol encodes the prototype of \"setgrentr\". It is zero if \"dsetgrentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dsetgrentr\" is\ndefined.\n\n\"SETHOSTENTRPROTO\"\nThis symbol encodes the prototype of \"sethostentr\". It is zero if \"dsethostentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dsethostentr\" is\ndefined.\n\n\"SETLOCALERPROTO\"\nThis symbol encodes the prototype of \"setlocaler\". It is zero if \"dsetlocaler\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dsetlocaler\" is\ndefined.\n\n\"SETNETENTRPROTO\"\nThis symbol encodes the prototype of \"setnetentr\". It is zero if \"dsetnetentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dsetnetentr\" is\ndefined.\n\n\"SETPROTOENTRPROTO\"\nThis symbol encodes the prototype of \"setprotoentr\". It is zero if \"dsetprotoentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dsetprotoentr\" is\ndefined.\n\n\"SETPWENTRPROTO\"\nThis symbol encodes the prototype of \"setpwentr\". It is zero if \"dsetpwentr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dsetpwentr\" is\ndefined.\n\n\"SETSERVENTRPROTO\"\nThis symbol encodes the prototype of \"setserventr\". It is zero if \"dsetserventr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dsetserventr\" is\ndefined.\n\n\"SRANDOMRPROTO\"\nThis symbol encodes the prototype of \"srandomr\". It is zero if \"dsrandomr\" is undef,\nand one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dsrandomr\" is defined.\n\n\"SRAND48RPROTO\"\nThis symbol encodes the prototype of \"srand48r\". It is zero if \"dsrand48r\" is undef,\nand one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dsrand48r\" is defined.\n\n\"STRERRORRPROTO\"\nThis symbol encodes the prototype of \"strerrorr\". It is zero if \"dstrerrorr\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dstrerrorr\" is\ndefined.\n\n\"TMPNAMRPROTO\"\nThis symbol encodes the prototype of \"tmpnamr\". It is zero if \"dtmpnamr\" is undef,\nand one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dtmpnamr\" is defined.\n\n\"TTYNAMERPROTO\"\nThis symbol encodes the prototype of \"ttynamer\". It is zero if \"dttynamer\" is undef,\nand one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dttynamer\" is defined.\n\nREGEXP Functions\n\"pregcomp\"\nDescribed in perlreguts.\n\nREGEXP * pregcomp(SV * const pattern, const U32 flags)\n\n\"pregexec\"\nDescribed in perlreguts.\n\nI32 pregexec(REGEXP * const prog, char *stringarg, char *strend,\nchar *strbeg, SSizet minend, SV *screamer,\nU32 nosave)\n\n\"recompile\"\nCompile the regular expression pattern \"pattern\", returning a pointer to the compiled\nobject for later matching with the internal regex engine.\n\nThis function is typically used by a custom regexp engine \".comp()\" function to hand off\nto the core regexp engine those patterns it doesn't want to handle itself (typically\npassing through the same flags it was called with). In almost all other cases, a regexp\nshould be compiled by calling \"\"pregcomp\"\" to compile using the currently active regexp\nengine.\n\nIf \"pattern\" is already a \"REGEXP\", this function does nothing but return a pointer to\nthe input. Otherwise the PV is extracted and treated like a string representing a\npattern. See perlre.\n\nThe possible flags for \"rxflags\" are documented in perlreapi. Their names all begin\nwith \"RXf\".\n\nREGEXP * recompile(SV * const pattern, U32 origrxflags)\n\n\"redupguts\"\nDuplicate a regexp.\n\nThis routine is expected to clone a given regexp structure. It is only compiled under\nUSEITHREADS.\n\nAfter all of the core data stored in struct regexp is duplicated the \"regexpengine.dupe\"\nmethod is used to copy any private data stored in the *pprivate pointer. This allows\nextensions to handle any duplication they need to do.\n\nvoid redupguts(const REGEXP *sstr, REGEXP *dstr,\nCLONEPARAMS *param)\n\n\"REGEXLOCALECHARSET\"\nDescribed in perlreapi.\n\n\"REGEXP\"\nDescribed in perlreapi.\n\n\"regexpengine\"\nWhen a regexp is compiled, its \"engine\" field is then set to point at the appropriate\nstructure, so that when it needs to be used Perl can find the right routines to do so.\n\nIn order to install a new regexp handler, $^H{regcomp} is set to an integer which (when\ncasted appropriately) resolves to one of these structures. When compiling, the \"comp\"\nmethod is executed, and the resulting \"regexp\" structure's engine field is expected to\npoint back at the same structure.\n\nThe pTHX symbol in the definition is a macro used by Perl under threading to provide an\nextra argument to the routine holding a pointer back to the interpreter that is executing\nthe regexp. So under threading all routines get an extra argument.\n\n\"regexpparenpair\"\nDescribed in perlreapi.\n\n\"regmatchinfo\"\nSome basic information about the current match that is created by Perlregexecflags and\nthen passed to regtry(), regmatch() etc. It is allocated as a local var on the stack, so\nnothing should be stored in it that needs preserving or clearing up on croak(). For\nthat, see the auxinfo and auxinfoeval members of the regmatchstate union.\n\n\"REXECCOPYSKIPPOST\"\n\"REXECCOPYSKIPPRE\"\n\"REXECCOPYSTR\"\nDescribed in perlreapi.\n\n\"RXapifALL\"\n\"RXapifCLEAR\"\n\"RXapifDELETE\"\n\"RXapifEXISTS\"\n\"RXapifFETCH\"\n\"RXapifFIRSTKEY\"\n\"RXapifNEXTKEY\"\n\"RXapifONE\"\n\"RXapifREGNAME\"\n\"RXapifREGNAMES\"\n\"RXapifREGNAMESCOUNT\"\n\"RXapifSCALAR\"\n\"RXapifSTORE\"\nDescribed in perlreapi.\n\n\"RXBUFFIDXCARETFULLMATCH\"\n\"RXBUFFIDXCARETPOSTMATCH\"\n\"RXBUFFIDXCARETPREMATCH\"\n\"RXBUFFIDXFULLMATCH\"\n\"RXBUFFIDXPOSTMATCH\"\n\"RXBUFFIDXPREMATCH\"\nDescribed in perlreapi.\n\n\"RXfNOINPLACESUBST\"\n\"RXfNULL\"\n\"RXfSKIPWHITE\"\n\"RXfSPLIT\"\n\"RXfSTARTONLY\"\n\"RXfWHITE\"\nDescribed in perlreapi.\n\n\"RXfPMfEXTENDED\"\n\"RXfPMfFOLD\"\n\"RXfPMfKEEPCOPY\"\n\"RXfPMfMULTILINE\"\n\"RXfPMfSINGLELINE\"\nDescribed in perlreapi.\n\n\"RXMATCHCOPIED\"\nDescribed in perlreapi.\n\nRXMATCHCOPIED(const REGEXP * rx)\n\n\"RXOFFS\"\nDescribed in perlreapi.\n\nRXOFFS(const REGEXP * rxsv)\n\n\"SvRX\"\nConvenience macro to get the REGEXP from a SV. This is approximately equivalent to the\nfollowing snippet:\n\nif (SvMAGICAL(sv))\nmgget(sv);\nif (SvROK(sv))\nsv = MUTABLESV(SvRV(sv));\nif (SvTYPE(sv) == SVtREGEXP)\nreturn (REGEXP*) sv;\n\n\"NULL\" will be returned if a REGEXP* is not found.\n\nREGEXP * SvRX(SV *sv)\n\n\"SvRXOK\"\nReturns a boolean indicating whether the SV (or the one it references) is a REGEXP.\n\nIf you want to do something with the REGEXP* later use SvRX instead and check for NULL.\n\nbool SvRXOK(SV* sv)\n\n\"SVSAVEDCOPY\"\nDescribed in perlreapi.\n", "subsections": [] }, "Reports and Formats": { "content": "These are used in the simple report generation feature of Perl. See perlform.\n\n\"IoBOTTOMGV\"\nDescribed in perlguts.\n\nGV * IoBOTTOMGV(IO *io)\n\n\"IoBOTTOMNAME\"\nDescribed in perlguts.\n\nchar * IoBOTTOMNAME(IO *io)\n\n\"IoFMTGV\"\nDescribed in perlguts.\n\nGV * IoFMTGV(IO *io)\n\n\"IoFMTNAME\"\nDescribed in perlguts.\n\nchar * IoFMTNAME(IO *io)\n\n\"IoLINES\"\nDescribed in perlguts.\n\nIV IoLINES(IO *io)\n\n\"IoLINESLEFT\"\nDescribed in perlguts.\n\nIV IoLINESLEFT(IO *io)\n\n\"IoPAGE\"\nDescribed in perlguts.\n\nIV IoPAGE(IO *io)\n\n\"IoPAGELEN\"\nDescribed in perlguts.\n\nIV IoPAGELEN(IO *io)\n\n\"IoTOPGV\"\nDescribed in perlguts.\n\nGV * IoTOPGV(IO *io)\n\n\"IoTOPNAME\"\nDescribed in perlguts.\n\nchar * IoTOPNAME(IO *io)\n", "subsections": [] }, "Signals": { "content": "\"HASSIGINFOSIADDR\"\nThis symbol, if defined, indicates that \"siginfot\" has the \"siaddr\" member\n\n\"HASSIGINFOSIBAND\"\nThis symbol, if defined, indicates that \"siginfot\" has the \"siband\" member\n\n\"HASSIGINFOSIERRNO\"\nThis symbol, if defined, indicates that \"siginfot\" has the \"sierrno\" member\n\n\"HASSIGINFOSIPID\"\nThis symbol, if defined, indicates that \"siginfot\" has the \"sipid\" member\n\n\"HASSIGINFOSISTATUS\"\nThis symbol, if defined, indicates that \"siginfot\" has the \"sistatus\" member\n\n\"HASSIGINFOSIUID\"\nThis symbol, if defined, indicates that \"siginfot\" has the \"siuid\" member\n\n\"HASSIGINFOSIVALUE\"\nThis symbol, if defined, indicates that \"siginfot\" has the \"sivalue\" member\n\n\"PERLSIGNALSUNSAFEFLAG\"\nIf this bit in \"PLsignals\" is set, the system is uing the pre-Perl 5.8 unsafe signals.\nSee \"PERLSIGNALS\" in perlrun and \"Deferred Signals (Safe Signals)\" in perlipc.\n\nU32 PERLSIGNALSUNSAFEFLAG\n\n\"rsignal\"\nA wrapper for the C library functions sigaction(2) or signal(2). Use this instead of\nthose libc functions, as the Perl version gives the safest available implementation, and\nknows things that interact with the rest of the perl interpreter.\n\nSighandlert rsignal(int i, Sighandlert t)\n\n\"rsignalstate\"\nReturns a the current signal handler for signal \"signo\". See \"\"rsignal\"\".\n\nSighandlert rsignalstate(int i)\n\n\"Sigjmpbuf\"\nThis is the buffer type to be used with Sigsetjmp and Siglongjmp.\n\n\"Siglongjmp\"\nThis macro is used in the same way as siglongjmp(), but will invoke traditional longjmp()\nif siglongjmp isn't available. See \"HASSIGSETJMP\".\n\nvoid Siglongjmp(jmpbuf env, int val)\n\n\"SIGNAME\"\nThis symbol contains a list of signal names in order of signal number. This is intended\nto be used as a static array initialization, like this:\n\nchar *signame[] = { SIGNAME };\n\nThe signals in the list are separated with commas, and each signal is surrounded by\ndouble quotes. There is no leading \"SIG\" in the signal name, i.e. \"SIGQUIT\" is known as\n\"\"QUIT\"\". Gaps in the signal numbers (up to \"NSIG\") are filled in with \"NUMnn\", etc.,\nwhere nn is the actual signal number (e.g. \"NUM37\"). The signal number for \"signame[i]\"\nis stored in \"signum[i]\". The last element is 0 to terminate the list with a \"NULL\".\nThis corresponds to the 0 at the end of the \"signameinit\" list. Note that this\nvariable is initialized from the \"signameinit\", not from \"signame\" (which is unused).\n\n\"SIGNUM\"\nThis symbol contains a list of signal numbers, in the same order as the \"SIGNAME\" list.\nIt is suitable for static array initialization, as in:\n\nint signum[] = { SIGNUM };\n\nThe signals in the list are separated with commas, and the indices within that list and\nthe \"SIGNAME\" list match, so it's easy to compute the signal name from a number or vice\nversa at the price of a small dynamic linear lookup. Duplicates are allowed, but are\nmoved to the end of the list. The signal number corresponding to \"signame[i]\" is\n\"signumber[i]\". if (i < \"NSIG\") then \"signumber[i]\" == i. The last element is 0,\ncorresponding to the 0 at the end of the \"signameinit\" list. Note that this variable\nis initialized from the \"signuminit\", not from \"signum\" (which is unused).\n\n\"Sigsetjmp\"\nThis macro is used in the same way as sigsetjmp(), but will invoke traditional setjmp()\nif sigsetjmp isn't available. See \"HASSIGSETJMP\".\n\nint Sigsetjmp(jmpbuf env, int savesigs)\n\n\"SIGSIZE\"\nThis variable contains the number of elements of the \"SIGNAME\" and \"SIGNUM\" arrays,\nexcluding the final \"NULL\" entry.\n\n\"whichsig\"\n\"whichsigpv\"\n\"whichsigpvn\"\n\"whichsigsv\"\nThese all convert a signal name into its corresponding signal number; returning -1 if no\ncorresponding number was found.\n\nThey differ only in the source of the signal name:\n\n\"whichsigpv\" takes the name from the \"NUL\"-terminated string starting at \"sig\".\n\n\"whichsig\" is merely a different spelling, a synonym, of \"whichsigpv\".\n\n\"whichsigpvn\" takes the name from the string starting at \"sig\", with length \"len\" bytes.\n\n\"whichsigsv\" takes the name from the PV stored in the SV \"sigsv\".\n\nI32 whichsig (const char *sig)\nI32 whichsigpv (const char *sig)\nI32 whichsigpvn(const char *sig, STRLEN len)\nI32 whichsigsv (SV *sigsv)\n", "subsections": [] }, "Site configuration": { "content": "These variables give details as to where various libraries, installation destinations, etc.,\ngo, as well as what various installation options were selected\n\n\"ARCHLIB\"\nThis variable, if defined, holds the name of the directory in which the user wants to put\narchitecture-dependent public library files for perl5. It is most often a local\ndirectory such as /usr/local/lib. Programs using this variable must be prepared to deal\nwith filename expansion. If \"ARCHLIB\" is the same as \"PRIVLIB\", it is not defined, since\npresumably the program already searches \"PRIVLIB\".\n\n\"ARCHLIBEXP\"\nThis symbol contains the ~name expanded version of \"ARCHLIB\", to be used in programs that\nare not prepared to deal with ~ expansion at run-time.\n\n\"ARCHNAME\"\nThis symbol holds a string representing the architecture name. It may be used to\nconstruct an architecture-dependant pathname where library files may be held under a\nprivate library, for instance.\n\n\"BIN\"\nThis symbol holds the path of the bin directory where the package will be installed.\nProgram must be prepared to deal with ~name substitution.\n\n\"BINEXP\"\nThis symbol is the filename expanded version of the \"BIN\" symbol, for programs that do\nnot want to deal with that at run-time.\n\n\"INSTALLUSRBINPERL\"\nThis symbol, if defined, indicates that Perl is to be installed also as /usr/bin/perl.\n\n\"MULTIARCH\"\nThis symbol, if defined, signifies that the build process will produce some binary files\nthat are going to be used in a cross-platform environment. This is the case for example\nwith the NeXT \"fat\" binaries that contain executables for several \"CPUs\".\n\n\"PERLINCVERSIONLIST\"\nThis variable specifies the list of subdirectories in over which perl.c:incpush() and\nlib/lib.pm will automatically search when adding directories to @\"INC\", in a format\nsuitable for a C initialization string. See the \"incversionlist\" entry in\nPorting/Glossary for more details.\n\n\"PERLOTHERLIBDIRS\"\nThis variable contains a colon-separated set of paths for the perl binary to search for\nadditional library files or modules. These directories will be tacked to the end of\n@\"INC\". Perl will automatically search below each path for version- and architecture-\nspecific directories. See \"PERLINCVERSIONLIST\" for more details.\n\n\"PERLRELOCATABLEINC\"\nThis symbol, if defined, indicates that we'd like to relocate entries in @\"INC\" at run\ntime based on the location of the perl binary.\n\n\"PERLTARGETARCH\"\nThis symbol, if defined, indicates the target architecture Perl has been cross-compiled\nto. Undefined if not a cross-compile.\n\n\"PERLUSEDEVEL\"\nThis symbol, if defined, indicates that Perl was configured with \"-Dusedevel\", to enable\ndevelopment features. This should not be done for production builds.\n\n\"PERLVENDORARCH\"\nIf defined, this symbol contains the name of a private library. The library is private\nin the sense that it needn't be in anyone's execution path, but it should be accessible\nby the world. It may have a ~ on the front. The standard distribution will put nothing\nin this directory. Vendors who distribute perl may wish to place their own architecture-\ndependent modules and extensions in this directory with\n\nMakeMaker Makefile.PL INSTALLDIRS=vendor\n\nor equivalent. See \"INSTALL\" for details.\n\n\"PERLVENDORARCHEXP\"\nThis symbol contains the ~name expanded version of \"PERLVENDORARCH\", to be used in\nprograms that are not prepared to deal with ~ expansion at run-time.\n\n\"PERLVENDORLIBEXP\"\nThis symbol contains the ~name expanded version of \"VENDORLIB\", to be used in programs\nthat are not prepared to deal with ~ expansion at run-time.\n\n\"PERLVENDORLIBSTEM\"\nThis define is \"PERLVENDORLIBEXP\" with any trailing version-specific component removed.\nThe elements in \"incversionlist\" (\"incversionlist\".U (part of metaconfig)) can be\ntacked onto this variable to generate a list of directories to search.\n\n\"PRIVLIB\"\nThis symbol contains the name of the private library for this package. The library is\nprivate in the sense that it needn't be in anyone's execution path, but it should be\naccessible by the world. The program should be prepared to do ~ expansion.\n\n\"PRIVLIBEXP\"\nThis symbol contains the ~name expanded version of \"PRIVLIB\", to be used in programs that\nare not prepared to deal with ~ expansion at run-time.\n\n\"SITEARCH\"\nThis symbol contains the name of the private library for this package. The library is\nprivate in the sense that it needn't be in anyone's execution path, but it should be\naccessible by the world. The program should be prepared to do ~ expansion. The standard\ndistribution will put nothing in this directory. After perl has been installed, users\nmay install their own local architecture-dependent modules in this directory with\n\nMakeMaker Makefile.PL\n\nor equivalent. See \"INSTALL\" for details.\n\n\"SITEARCHEXP\"\nThis symbol contains the ~name expanded version of \"SITEARCH\", to be used in programs\nthat are not prepared to deal with ~ expansion at run-time.\n\n\"SITELIB\"\nThis symbol contains the name of the private library for this package. The library is\nprivate in the sense that it needn't be in anyone's execution path, but it should be\naccessible by the world. The program should be prepared to do ~ expansion. The standard\ndistribution will put nothing in this directory. After perl has been installed, users\nmay install their own local architecture-independent modules in this directory with\n\nMakeMaker Makefile.PL\n\nor equivalent. See \"INSTALL\" for details.\n\n\"SITELIBEXP\"\nThis symbol contains the ~name expanded version of \"SITELIB\", to be used in programs that\nare not prepared to deal with ~ expansion at run-time.\n\n\"SITELIBSTEM\"\nThis define is \"SITELIBEXP\" with any trailing version-specific component removed. The\nelements in \"incversionlist\" (\"incversionlist\".U (part of metaconfig)) can be tacked\nonto this variable to generate a list of directories to search.\n\n\"STARTPERL\"\nThis variable contains the string to put in front of a perl script to make sure (one\nhopes) that it runs with perl and not some shell.\n\n\"USE64BITALL\"\nThis symbol, if defined, indicates that 64-bit integers should be used when available.\nIf not defined, the native integers will be used (be they 32 or 64 bits). The maximal\npossible 64-bitness is employed: LP64 or \"ILP64\", meaning that you will be able to use\nmore than 2 gigabytes of memory. This mode is even more binary incompatible than\n\"USE64BITINT\". You may not be able to run the resulting executable in a 32-bit \"CPU\"\nat all or you may need at least to reboot your OS to 64-bit mode.\n\n\"USE64BITINT\"\nThis symbol, if defined, indicates that 64-bit integers should be used when available.\nIf not defined, the native integers will be employed (be they 32 or 64 bits). The\nminimal possible 64-bitness is used, just enough to get 64-bit integers into Perl. This\nmay mean using for example \"long longs\", while your memory may still be limited to 2\ngigabytes.\n\n\"USEBSDGETPGRP\"\nThis symbol, if defined, indicates that getpgrp needs one arguments whereas \"USG\" one\nneeds none.\n\n\"USEBSDSETPGRP\"\nThis symbol, if defined, indicates that setpgrp needs two arguments whereas \"USG\" one\nneeds none. See also \"HASSETPGID\" for a \"POSIX\" interface.\n\n\"USECBACKTRACE\"\nThis symbol, if defined, indicates that Perl should be built with support for backtrace.\n\n\"USECPLUSPLUS\"\nThis symbol, if defined, indicates that a C++ compiler was used to compiled Perl and will\nbe used to compile extensions.\n\n\"USECROSSCOMPILE\"\nThis symbol, if defined, indicates that Perl is being cross-compiled.\n\n\"USEDTRACE\"\nThis symbol, if defined, indicates that Perl should be built with support for DTrace.\n\n\"USEDYNAMICLOADING\"\nThis symbol, if defined, indicates that dynamic loading of some sort is available.\n\n\"USEFASTSTDIO\"\nThis symbol, if defined, indicates that Perl should be built to use 'fast stdio'.\nDefaults to define in Perls 5.8 and earlier, to undef later.\n\n\"USEITHREADS\"\nThis symbol, if defined, indicates that Perl should be built to use the interpreter-based\nthreading implementation.\n\n\"USEKERNPROCPATHNAME\"\nThis symbol, if defined, indicates that we can use sysctl with \"KERNPROCPATHNAME\" to\nget a full path for the executable, and hence convert $^X to an absolute path.\n\n\"USELARGEFILES\"\nThis symbol, if defined, indicates that large file support should be used when available.\n\n\"USELONGDOUBLE\"\nThis symbol, if defined, indicates that long doubles should be used when available.\n\n\"USEMOREBITS\"\nThis symbol, if defined, indicates that 64-bit interfaces and long doubles should be used\nwhen available.\n\n\"USENSGETEXECUTABLEPATH\"\nThis symbol, if defined, indicates that we can use \"NSGetExecutablePath\" and realpath to\nget a full path for the executable, and hence convert $^X to an absolute path.\n\n\"USEPERLIO\"\nThis symbol, if defined, indicates that the PerlIO abstraction should be used throughout.\nIf not defined, stdio should be used in a fully backward compatible manner.\n\n\"USEQUADMATH\"\nThis symbol, if defined, indicates that the quadmath library should be used when\navailable.\n\n\"USEREENTRANTAPI\"\nThis symbol, if defined, indicates that Perl should try to use the various \"r\" versions\nof library functions. This is extremely experimental.\n\n\"USESEMCTLSEMIDDS\"\nThis symbol, if defined, indicates that \"struct semidds\" * is used for semctl\n\"IPCSTAT\".\n\n\"USESEMCTLSEMUN\"\nThis symbol, if defined, indicates that \"union semun\" is used for semctl \"IPCSTAT\".\n\n\"USESITECUSTOMIZE\"\nThis symbol, if defined, indicates that sitecustomize should be used.\n\n\"USESOCKS\"\nThis symbol, if defined, indicates that Perl should be built to use socks.\n\n\"USESTATBLOCKS\"\nThis symbol is defined if this system has a stat structure declaring \"stblksize\" and\n\"stblocks\".\n\n\"USESTDIOBASE\"\nThis symbol is defined if the \"base\" field (or similar) of the stdio \"FILE\" structure\ncan be used to access the stdio buffer for a file handle. If this is defined, then the\nFILEbase(fp) macro will also be defined and should be used to access this field. Also,\nthe FILEbufsiz(fp) macro will be defined and should be used to determine the number of\nbytes in the buffer. \"USESTDIOBASE\" will never be defined unless \"USESTDIOPTR\" is.\n\n\"USESTDIOPTR\"\nThis symbol is defined if the \"ptr\" and \"cnt\" fields (or similar) of the stdio \"FILE\"\nstructure can be used to access the stdio buffer for a file handle. If this is defined,\nthen the FILEptr(fp) and FILEcnt(fp) macros will also be defined and should be used to\naccess these fields.\n\n\"USESTRICTBYDEFAULT\"\nThis symbol, if defined, enables additional defaults. At this time it only enables\nimplicit strict by default.\n\n\"USETHREADS\"\nThis symbol, if defined, indicates that Perl should be built to use threads. At present,\nit is a synonym for and \"USEITHREADS\", but eventually the source ought to be changed to\nuse this to mean \"any\" threading implementation.\n", "subsections": [] }, "Sockets configuration values": { "content": "\"HASSOCKADDRIN6\"\nThis symbol, if defined, indicates the availability of \"struct sockaddrin6\";\n\n\"HASSOCKADDRSALEN\"\nThis symbol, if defined, indicates that the \"struct sockaddr\" structure has a member\ncalled \"salen\", indicating the length of the structure.\n\n\"HASSOCKADDRSTORAGE\"\nThis symbol, if defined, indicates the availability of \"struct sockaddrstorage\";\n\n\"HASSOCKATMARK\"\nThis symbol, if defined, indicates that the \"sockatmark\" routine is available to test\nwhether a socket is at the out-of-band mark.\n\n\"HASSOCKET\"\nThis symbol, if defined, indicates that the \"BSD\" \"socket\" interface is supported.\n\n\"HASSOCKETPAIR\"\nThis symbol, if defined, indicates that the \"BSD\" socketpair() call is supported.\n\n\"HASSOCKS5INIT\"\nThis symbol, if defined, indicates that the \"socks5init\" routine is available to\ninitialize \"SOCKS\" 5.\n\n\"ISOCKS\"\nThis symbol, if defined, indicates that socks.h exists and should be included.\n\n#ifdef ISOCKS\n#include \n#endif\n\n\"ISYSSOCKIO\"\nThis symbol, if defined, indicates the sys/sockio.h should be included to get socket\nioctl options, like \"SIOCATMARK\".\n\n#ifdef ISYSSOCKIO\n#include \n#endif\n", "subsections": [] }, "Source Filters": { "content": "\"applybuiltincvattributes\"\nGiven an OPLIST containing attribute definitions, filter it for known builtin attributes\nto apply to the cv, returning a possibly-smaller list containing just the remaining ones.\n\nOP * applybuiltincvattributes(CV *cv, OP *attrlist)\n\n\"filteradd\"\nDescribed in perlfilter.\n\nSV * filteradd(filtert funcp, SV *datasv)\n\n\"filterdel\"\nDelete most recently added instance of the filter function argument\n\nvoid filterdel(filtert funcp)\n\n\"filterread\"\nDescribed in perlfilter.\n\nI32 filterread(int idx, SV *bufsv, int maxlen)\n\n\"scanvstring\"\nReturns a pointer to the next character after the parsed vstring, as well as updating the\npassed in sv.\n\nFunction must be called like\n\nsv = sv2mortal(newSV(5));\ns = scanvstring(s,e,sv);\n\nwhere s and e are the start and end of the string. The sv should already be large enough\nto store the vstring passed in, for performance reasons.\n\nThis function may croak if fatal warnings are enabled in the calling scope, hence the\nsv2mortal in the example (to prevent a leak). Make sure to do SvREFCNTinc afterwards\nif you use sv2mortal.\n\nchar * scanvstring(const char *s, const char * const e, SV *sv)\n\n\"startsubparse\"\nSet things up for parsing a subroutine.\n\nIf \"isformat\" is non-zero, the input is to be considered a format sub (a specialised sub\nused to implement perl's \"format\" feature); else a normal \"sub\".\n\n\"flags\" are added to the flags for \"PLcompcv\". \"flags\" may include the \"CVfIsMETHOD\"\nbit, which causes the new subroutine to be a method.\n\nThis returns the value of \"PLsavestackix\" that was in effect upon entry to the\nfunction;\n\nI32 startsubparse(I32 isformat, U32 flags)\n", "subsections": [] }, "Stack Manipulation Macros": { "content": "\"dMARK\"\nDeclare a stack marker variable, \"mark\", for the XSUB. See \"MARK\" and \"dORIGMARK\".\n\ndMARK;\n\n\"dORIGMARK\"\nSaves the original stack mark for the XSUB. See \"ORIGMARK\".\n\ndORIGMARK;\n\n\"dSP\"\nDeclares a local copy of perl's stack pointer for the XSUB, available via the \"SP\" macro.\nSee \"SP\".\n\ndSP;\n\n\"dTARGET\"\nDeclare that this function uses \"TARG\", and initializes it\n\ndTARGET;\n\n\"EXTEND\"\nUsed to extend the argument stack for an XSUB's return values. Once used, guarantees\nthat there is room for at least \"nitems\" to be pushed onto the stack.\n\nvoid EXTEND(SP, SSizet nitems)\n\n\"MARK\"\nStack marker variable for the XSUB. See \"dMARK\".\n\n\"mPUSHi\"\nPush an integer onto the stack. The stack must have room for this element. Does not use\n\"TARG\". See also \"PUSHi\", \"mXPUSHi\" and \"XPUSHi\".\n\nvoid mPUSHi(IV iv)\n\n\"mPUSHn\"\nPush a double onto the stack. The stack must have room for this element. Does not use\n\"TARG\". See also \"PUSHn\", \"mXPUSHn\" and \"XPUSHn\".\n\nvoid mPUSHn(NV nv)\n\n\"mPUSHp\"\nPush a string onto the stack. The stack must have room for this element. The \"len\"\nindicates the length of the string. Does not use \"TARG\". See also \"PUSHp\", \"mXPUSHp\"\nand \"XPUSHp\".\n\nvoid mPUSHp(char* str, STRLEN len)\n\n\"mPUSHpvs\"\nA variation on \"mPUSHp\" that takes a literal string and calculates its size directly.\n\nvoid mPUSHpvs(\"literal string\")\n\n\"mPUSHs\"\nPush an SV onto the stack and mortalizes the SV. The stack must have room for this\nelement. Does not use \"TARG\". See also \"PUSHs\" and \"mXPUSHs\".\n\nvoid mPUSHs(SV* sv)\n\n\"mPUSHu\"\nPush an unsigned integer onto the stack. The stack must have room for this element.\nDoes not use \"TARG\". See also \"PUSHu\", \"mXPUSHu\" and \"XPUSHu\".\n\nvoid mPUSHu(UV uv)\n\n\"mXPUSHi\"\nPush an integer onto the stack, extending the stack if necessary. Does not use \"TARG\".\nSee also \"XPUSHi\", \"mPUSHi\" and \"PUSHi\".\n\nvoid mXPUSHi(IV iv)\n\n\"mXPUSHn\"\nPush a double onto the stack, extending the stack if necessary. Does not use \"TARG\".\nSee also \"XPUSHn\", \"mPUSHn\" and \"PUSHn\".\n\nvoid mXPUSHn(NV nv)\n\n\"mXPUSHp\"\nPush a string onto the stack, extending the stack if necessary. The \"len\" indicates the\nlength of the string. Does not use \"TARG\". See also \"XPUSHp\", \"mPUSHp\" and \"PUSHp\".\n\nvoid mXPUSHp(char* str, STRLEN len)\n\n\"mXPUSHpvs\"\nA variation on \"mXPUSHp\" that takes a literal string and calculates its size directly.\n\nvoid mXPUSHpvs(\"literal string\")\n\n\"mXPUSHs\"\nPush an SV onto the stack, extending the stack if necessary and mortalizes the SV. Does\nnot use \"TARG\". See also \"XPUSHs\" and \"mPUSHs\".\n\nvoid mXPUSHs(SV* sv)\n\n\"mXPUSHu\"\nPush an unsigned integer onto the stack, extending the stack if necessary. Does not use\n\"TARG\". See also \"XPUSHu\", \"mPUSHu\" and \"PUSHu\".\n\nvoid mXPUSHu(UV uv)\n\n\"newXSproto\"\nUsed by \"xsubpp\" to hook up XSUBs as Perl subs. Adds Perl prototypes to the subs.\n\n\"ORIGMARK\"\nThe original stack mark for the XSUB. See \"dORIGMARK\".\n\n\"PLmarkstack\"\nDescribed in perlguts.\n\n\"PLmarkstackptr\"\nDescribed in perlguts.\n\n\"PLsavestack\"\nDescribed in perlguts.\n\n\"PLsavestackix\"\nDescribed in perlguts.\n\n\"PLscopestack\"\nDescribed in perlguts.\n\n\"PLscopestackix\"\nDescribed in perlguts.\n\n\"PLscopestackname\"\nDescribed in perlguts.\n\n\"PLstackbase\"\nDescribed in perlguts.\n\n\"PLstacksp\"\nDescribed in perlguts.\n\n\"PLtmpsfloor\"\nDescribed in perlguts.\n\n\"PLtmpsix\"\nDescribed in perlguts.\n\n\"PLtmpsstack\"\nDescribed in perlguts.\n\n\"POPi\"\nPops an integer off the stack.\n\nIV POPi\n\n\"POPl\"\nPops a long off the stack.\n\nlong POPl\n\n\"POPn\"\nPops a double off the stack.\n\nNV POPn\n\n\"POPp\"\nPops a string off the stack.\n\nchar* POPp\n\n\"POPpbytex\"\nPops a string off the stack which must consist of bytes i.e. characters < 256.\n\nchar* POPpbytex\n\n\"POPpx\"\nPops a string off the stack. Identical to POPp. There are two names for historical\nreasons.\n\nchar* POPpx\n\n\"POPs\"\nPops an SV off the stack.\n\nSV* POPs\n\n\"POPu\"\nPops an unsigned integer off the stack.\n\nUV POPu\n\n\"POPul\"\nPops an unsigned long off the stack.\n\nlong POPul\n\n\"PUSHi\"\nPush an integer onto the stack. The stack must have room for this element. Handles\n'set' magic. Uses \"TARG\", so \"dTARGET\" or \"dXSTARG\" should be called to declare it. Do\nnot call multiple \"TARG\"-oriented macros to return lists from XSUB's - see \"mPUSHi\"\ninstead. See also \"XPUSHi\" and \"mXPUSHi\".\n\nvoid PUSHi(IV iv)\n\n\"PUSHMARK\"\nOpening bracket for arguments on a callback. See \"PUTBACK\" and perlcall.\n\nvoid PUSHMARK(SP)\n\n\"PUSHmortal\"\nPush a new mortal SV onto the stack. The stack must have room for this element. Does\nnot use \"TARG\". See also \"PUSHs\", \"XPUSHmortal\" and \"XPUSHs\".\n\nvoid PUSHmortal\n\n\"PUSHn\"\nPush a double onto the stack. The stack must have room for this element. Handles 'set'\nmagic. Uses \"TARG\", so \"dTARGET\" or \"dXSTARG\" should be called to declare it. Do not\ncall multiple \"TARG\"-oriented macros to return lists from XSUB's - see \"mPUSHn\" instead.\nSee also \"XPUSHn\" and \"mXPUSHn\".\n\nvoid PUSHn(NV nv)\n\n\"PUSHp\"\nPush a string onto the stack. The stack must have room for this element. The \"len\"\nindicates the length of the string. Handles 'set' magic. Uses \"TARG\", so \"dTARGET\" or\n\"dXSTARG\" should be called to declare it. Do not call multiple \"TARG\"-oriented macros to\nreturn lists from XSUB's - see \"mPUSHp\" instead. See also \"XPUSHp\" and \"mXPUSHp\".\n\nvoid PUSHp(char* str, STRLEN len)\n\n\"PUSHpvs\"\nA variation on \"PUSHp\" that takes a literal string and calculates its size directly.\n\nvoid PUSHpvs(\"literal string\")\n\n\"PUSHs\"\nPush an SV onto the stack. The stack must have room for this element. Does not handle\n'set' magic. Does not use \"TARG\". See also \"PUSHmortal\", \"XPUSHs\", and \"XPUSHmortal\".\n\nvoid PUSHs(SV* sv)\n\n\"PUSHu\"\nPush an unsigned integer onto the stack. The stack must have room for this element.\nHandles 'set' magic. Uses \"TARG\", so \"dTARGET\" or \"dXSTARG\" should be called to declare\nit. Do not call multiple \"TARG\"-oriented macros to return lists from XSUB's - see\n\"mPUSHu\" instead. See also \"XPUSHu\" and \"mXPUSHu\".\n\nvoid PUSHu(UV uv)\n\n\"PUTBACK\"\nClosing bracket for XSUB arguments. This is usually handled by \"xsubpp\". See \"PUSHMARK\"\nand perlcall for other uses.\n\nPUTBACK;\n\n\"SAVEtINT\"\nDescribed in perlguts.\n\n\"SP\"\nStack pointer. This is usually handled by \"xsubpp\". See \"dSP\" and \"SPAGAIN\".\n\n\"SPAGAIN\"\nRefetch the stack pointer. Used after a callback. See perlcall.\n\nSPAGAIN;\n\n\"SSNEW\"\n\"SSNEWa\"\n\"SSNEWat\"\n\"SSNEWt\"\nThese temporarily allocates data on the savestack, returning an SSizet index into the\nsavestack, because a pointer would get broken if the savestack is moved on reallocation.\nUse \"\"SSPTR\"\" to convert the returned index into a pointer.\n\nThe forms differ in that plain \"SSNEW\" allocates \"size\" bytes; \"SSNEWt\" and \"SSNEWat\"\nallocate \"size\" objects, each of which is type \"type\"; and and \"SSNEWat\" make\nsure to align the new data to an \"align\" boundary. The most useful value for the\nalignment is likely to be \"\"MEMALIGNBYTES\"\". The alignment will be preserved through\nsavestack reallocation only if realloc returns data aligned to a size divisible by\n\"align\"!\n\nSSizet SSNEW (Sizet size)\nSSizet SSNEWa (Sizetsize, Sizet align)\nSSizet SSNEWat(Sizetsize, type, Sizet align)\nSSizet SSNEWt (Sizet size, type)\n\n\"SSPTR\"\n\"SSPTRt\"\nThese convert the \"index\" returned by L/<\"SSNEW\"> and kin into actual pointers.\n\nThe difference is that \"SSPTR\" casts the result to \"type\", and \"SSPTRt\" casts it to a\npointer of that \"type\".\n\ntype SSPTR (SSizet index, type)\ntype * SSPTRt(SSizet index, type)\n\n\"TARG\"\n\"TARG\" is short for \"target\". It is an entry in the pad that an OPs \"optarg\" refers to.\nIt is scratchpad space, often used as a return value for the OP, but some use it for\nother purposes.\n\nTARG;\n\n\"TOPs\"\nDescribed in perlguts.\n\n\"XPUSHi\"\nPush an integer onto the stack, extending the stack if necessary. Handles 'set' magic.\nUses \"TARG\", so \"dTARGET\" or \"dXSTARG\" should be called to declare it. Do not call\nmultiple \"TARG\"-oriented macros to return lists from XSUB's - see \"mXPUSHi\" instead. See\nalso \"PUSHi\" and \"mPUSHi\".\n\nvoid XPUSHi(IV iv)\n\n\"XPUSHmortal\"\nPush a new mortal SV onto the stack, extending the stack if necessary. Does not use\n\"TARG\". See also \"XPUSHs\", \"PUSHmortal\" and \"PUSHs\".\n\nvoid XPUSHmortal\n\n\"XPUSHn\"\nPush a double onto the stack, extending the stack if necessary. Handles 'set' magic.\nUses \"TARG\", so \"dTARGET\" or \"dXSTARG\" should be called to declare it. Do not call\nmultiple \"TARG\"-oriented macros to return lists from XSUB's - see \"mXPUSHn\" instead. See\nalso \"PUSHn\" and \"mPUSHn\".\n\nvoid XPUSHn(NV nv)\n\n\"XPUSHp\"\nPush a string onto the stack, extending the stack if necessary. The \"len\" indicates the\nlength of the string. Handles 'set' magic. Uses \"TARG\", so \"dTARGET\" or \"dXSTARG\"\nshould be called to declare it. Do not call multiple \"TARG\"-oriented macros to return\nlists from XSUB's - see \"mXPUSHp\" instead. See also \"PUSHp\" and \"mPUSHp\".\n\nvoid XPUSHp(char* str, STRLEN len)\n\n\"XPUSHpvs\"\nA variation on \"XPUSHp\" that takes a literal string and calculates its size directly.\n\nvoid XPUSHpvs(\"literal string\")\n\n\"XPUSHs\"\nPush an SV onto the stack, extending the stack if necessary. Does not handle 'set'\nmagic. Does not use \"TARG\". See also \"XPUSHmortal\", \"PUSHs\" and \"PUSHmortal\".\n\nvoid XPUSHs(SV* sv)\n\n\"XPUSHu\"\nPush an unsigned integer onto the stack, extending the stack if necessary. Handles 'set'\nmagic. Uses \"TARG\", so \"dTARGET\" or \"dXSTARG\" should be called to declare it. Do not\ncall multiple \"TARG\"-oriented macros to return lists from XSUB's - see \"mXPUSHu\" instead.\nSee also \"PUSHu\" and \"mPUSHu\".\n\nvoid XPUSHu(UV uv)\n\n\"XSAPIVERSIONBOOTCHECK\"\nMacro to verify that the perl api version an XS module has been compiled against matches\nthe api version of the perl interpreter it's being loaded into.\n\nXSAPIVERSIONBOOTCHECK;\n\n\"XSRETURN\"\nReturn from XSUB, indicating number of items on the stack. This is usually handled by\n\"xsubpp\".\n\nvoid XSRETURN(int nitems)\n\n\"XSRETURNEMPTY\"\nReturn an empty list from an XSUB immediately.\n\nXSRETURNEMPTY;\n\n\"XSRETURNIV\"\nReturn an integer from an XSUB immediately. Uses \"XSTmIV\".\n\nvoid XSRETURNIV(IV iv)\n\n\"XSRETURNNO\"\nReturn &PLsvno from an XSUB immediately. Uses \"XSTmNO\".\n\nXSRETURNNO;\n\n\"XSRETURNNV\"\nReturn a double from an XSUB immediately. Uses \"XSTmNV\".\n\nvoid XSRETURNNV(NV nv)\n\n\"XSRETURNPV\"\nReturn a copy of a string from an XSUB immediately. Uses \"XSTmPV\".\n\nvoid XSRETURNPV(char* str)\n\n\"XSRETURNUNDEF\"\nReturn &PLsvundef from an XSUB immediately. Uses \"XSTmUNDEF\".\n\nXSRETURNUNDEF;\n\n\"XSRETURNUV\"\nReturn an integer from an XSUB immediately. Uses \"XSTmUV\".\n\nvoid XSRETURNUV(IV uv)\n\n\"XSRETURNYES\"\nReturn &PLsvyes from an XSUB immediately. Uses \"XSTmYES\".\n\nXSRETURNYES;\n\n\"XSTmIV\"\nPlace an integer into the specified position \"pos\" on the stack. The value is stored in\na new mortal SV.\n\nvoid XSTmIV(int pos, IV iv)\n\n\"XSTmNO\"\nPlace &PLsvno into the specified position \"pos\" on the stack.\n\nvoid XSTmNO(int pos)\n\n\"XSTmNV\"\nPlace a double into the specified position \"pos\" on the stack. The value is stored in a\nnew mortal SV.\n\nvoid XSTmNV(int pos, NV nv)\n\n\"XSTmPV\"\nPlace a copy of a string into the specified position \"pos\" on the stack. The value is\nstored in a new mortal SV.\n\nvoid XSTmPV(int pos, char* str)\n\n\"XSTmUNDEF\"\nPlace &PLsvundef into the specified position \"pos\" on the stack.\n\nvoid XSTmUNDEF(int pos)\n\n\"XSTmUV\"\nPlace an unsigned integer into the specified position \"pos\" on the stack. The value is\nstored in a new mortal SV.\n\nvoid XSTmUV(int pos, UV uv)\n\n\"XSTmYES\"\nPlace &PLsvyes into the specified position \"pos\" on the stack.\n\nvoid XSTmYES(int pos)\n\n\"XSVERSION\"\nThe version identifier for an XS module. This is usually handled automatically by\n\"ExtUtils::MakeMaker\". See \"XSVERSIONBOOTCHECK\".\n\n\"XSVERSIONBOOTCHECK\"\nMacro to verify that a PM module's $VERSION variable matches the XS module's \"XSVERSION\"\nvariable. This is usually handled automatically by \"xsubpp\". See \"The VERSIONCHECK:\nKeyword\" in perlxs.\n\nXSVERSIONBOOTCHECK;\n", "subsections": [] }, "String Handling": { "content": "See also \"Unicode Support\".\n\n\"CAT2\"\nThis macro concatenates 2 tokens together.\n\ntoken CAT2(token x, token y)\n\n\"Copy\"\n\"CopyD\"\nThe XSUB-writer's interface to the C \"memcpy\" function. The \"src\" is the source, \"dest\"\nis the destination, \"nitems\" is the number of items, and \"type\" is the type. May fail on\noverlapping copies. See also \"Move\".\n\n\"CopyD\" is like \"Copy\" but returns \"dest\". Useful for encouraging compilers to tail-call\noptimise.\n\nvoid Copy (void* src, void* dest, int nitems, type)\nvoid * CopyD(void* src, void* dest, int nitems, type)\n\n\"delimcpy\"\nCopy a source buffer to a destination buffer, stopping at (but not including) the first\noccurrence in the source of an unescaped (defined below) delimiter byte, \"delim\". The\nsource is the bytes between \"from\" and \"fromend\" - 1. Similarly, the dest is \"to\" up to\n\"toend\".\n\nThe number of bytes copied is written to *retlen.\n\nReturns the position of the first uncopied \"delim\" in the \"from\" buffer, but if there is\nno such occurrence before \"fromend\", then \"fromend\" is returned, and the entire buffer\n\"from\" .. \"fromend\" - 1 is copied.\n\nIf there is room in the destination available after the copy, an extra terminating safety\n\"NUL\" byte is appended (not included in the returned length).\n\nThe error case is if the destination buffer is not large enough to accommodate everything\nthat should be copied. In this situation, a value larger than \"toend\" - \"to\" is written\nto *retlen, and as much of the source as fits will be written to the destination. Not\nhaving room for the safety \"NUL\" is not considered an error.\n\nIn the following examples, let \"x\" be the delimiter, and 0 represent a \"NUL\" byte (NOT\nthe digit 0). Then we would have\n\nSource Destination\nabcxdef abc0\n\nprovided the destination buffer is at least 4 bytes long.\n\nAn escaped delimiter is one which is immediately preceded by a single backslash. Escaped\ndelimiters are copied, and the copy continues past the delimiter; the backslash is not\ncopied:\n\nSource Destination\nabc\\xdef abcxdef0\n\n(provided the destination buffer is at least 8 bytes long).\n\nIt's actually somewhat more complicated than that. A sequence of any odd number of\nbackslashes escapes the following delimiter, and the copy continues with exactly one of\nthe backslashes stripped.\n\nSource Destination\nabc\\xdef abcxdef0\nabc\\\\\\xdef abc\\\\xdef0\nabc\\\\\\\\\\xdef abc\\\\\\\\xdef0\n\n(as always, if the destination is large enough)\n\nAn even number of preceding backslashes does not escape the delimiter, so that the copy\nstops just before it, and includes all the backslashes (no stripping; zero is considered\neven):\n\nSource Destination\nabcxdef abc0\nabc\\\\xdef abc\\\\0\nabc\\\\\\\\xdef abc\\\\\\\\0\n\nchar * delimcpy(char *to, const char *toend, const char *from,\nconst char *fromend, const int delim,\nI32 *retlen)\n\n\"dojoin\"\nThis performs a Perl \"join\", placing the joined output into \"sv\".\n\nThe elements to join are in SVs, stored in a C array of pointers to SVs, from mark to\n\"sp - 1\". Hence *mark is a reference to the first SV. Each SV will be coerced into a\nPV if not one already.\n\n\"delim\" contains the string (or coerced into a string) that is to separate each of the\njoined elements.\n\nIf any component is in UTF-8, the result will be as well, and all non-UTF-8 components\nwill be converted to UTF-8 as necessary.\n\nMagic and tainting are handled.\n\nvoid dojoin(SV *sv, SV *delim, SV mark, SV sp)\n\n\"dosprintf\"\nThis performs a Perl \"sprintf\" placing the string output into \"sv\".\n\nThe elements to format are in SVs, stored in a C array of pointers to SVs of length\n\"len\"> and beginning at sarg. The element referenced by *sarg is the format.\n\nMagic and tainting are handled.\n\nvoid dosprintf(SV *sv, SSizet len, SV sarg)\n\n\"fbmcompile\"\nAnalyzes the string in order to make fast searches on it using fbminstr() -- the Boyer-\nMoore algorithm.\n\nvoid fbmcompile(SV *sv, U32 flags)\n\n\"fbminstr\"\nReturns the location of the SV in the string delimited by \"big\" and \"bigend\" (\"bigend\")\nis the char following the last char). It returns \"NULL\" if the string can't be found.\nThe \"sv\" does not have to be \"fbmcompiled\", but the search will not be as fast then.\n\nchar * fbminstr(unsigned char *big, unsigned char *bigend,\nSV *littlestr, U32 flags)\n\n\"foldEQ\"\nReturns true if the leading \"len\" bytes of the strings \"s1\" and \"s2\" are the same case-\ninsensitively; false otherwise. Uppercase and lowercase ASCII range bytes match\nthemselves and their opposite case counterparts. Non-cased and non-ASCII range bytes\nmatch only themselves.\n\nI32 foldEQ(const char *a, const char *b, I32 len)\n\n\"ibcmp\"\nThis is a synonym for \"(! foldEQ())\"\n\nI32 ibcmp(const char *a, const char *b, I32 len)\n\n\"ibcmplocale\"\nThis is a synonym for \"(! foldEQlocale())\"\n\nI32 ibcmplocale(const char *a, const char *b, I32 len)\n\n\"ibcmputf8\"\nThis is a synonym for \"(! foldEQutf8())\"\n\nI32 ibcmputf8(const char *s1, char pe1, UV l1, bool u1,\nconst char *s2, char pe2, UV l2, bool u2)\n\n\"instr\"\nSame as strstr(3), which finds and returns a pointer to the first occurrence of the NUL-\nterminated substring \"little\" in the NUL-terminated string \"big\", returning NULL if not\nfound. The terminating NUL bytes are not compared.\n\nchar * instr(const char *big, const char *little)\n\n\"memCHRs\"\nReturns the position of the first occurrence of the byte \"c\" in the literal string\n\"list\", or NULL if \"c\" doesn't appear in \"list\". All bytes are treated as unsigned char.\nThus this macro can be used to determine if \"c\" is in a set of particular characters.\nUnlike strchr(3), it works even if \"c\" is \"NUL\" (and the set doesn't include \"NUL\").\n\nbool memCHRs(\"list\", char c)\n\n\"memEQ\"\nTest two buffers (which may contain embedded \"NUL\" characters, to see if they are equal.\nThe \"len\" parameter indicates the number of bytes to compare. Returns true or false. It\nis undefined behavior if either of the buffers doesn't contain at least \"len\" bytes.\n\nbool memEQ(char* s1, char* s2, STRLEN len)\n\n\"memEQs\"\nLike \"memEQ\", but the second string is a literal enclosed in double quotes, \"l1\" gives\nthe number of bytes in \"s1\". Returns true or false.\n\nbool memEQs(char* s1, STRLEN l1, \"s2\")\n\n\"memNE\"\nTest two buffers (which may contain embedded \"NUL\" characters, to see if they are not\nequal. The \"len\" parameter indicates the number of bytes to compare. Returns true or\nfalse. It is undefined behavior if either of the buffers doesn't contain at least \"len\"\nbytes.\n\nbool memNE(char* s1, char* s2, STRLEN len)\n\n\"memNEs\"\nLike \"memNE\", but the second string is a literal enclosed in double quotes, \"l1\" gives\nthe number of bytes in \"s1\". Returns true or false.\n\nbool memNEs(char* s1, STRLEN l1, \"s2\")\n\n\"Move\"\n\"MoveD\"\nThe XSUB-writer's interface to the C \"memmove\" function. The \"src\" is the source, \"dest\"\nis the destination, \"nitems\" is the number of items, and \"type\" is the type. Can do\noverlapping moves. See also \"Copy\".\n\n\"MoveD\" is like \"Move\" but returns \"dest\". Useful for encouraging compilers to tail-call\noptimise.\n\nvoid Move (void* src, void* dest, int nitems, type)\nvoid * MoveD(void* src, void* dest, int nitems, type)\n\n\"mysnprintf\"\nThe C library \"snprintf\" functionality, if available and standards-compliant (uses\n\"vsnprintf\", actually). However, if the \"vsnprintf\" is not available, will unfortunately\nuse the unsafe \"vsprintf\" which can overrun the buffer (there is an overrun check, but\nthat may be too late). Consider using \"svvcatpvf\" instead, or getting \"vsnprintf\".\n\nint mysnprintf(char *buffer, const Sizet len,\nconst char *format, ...)\n\n\"mysprintf\"\n\"DEPRECATED!\" It is planned to remove \"mysprintf\" from a future release of Perl. Do\nnot use it for new code; remove it from existing code.\n\nDo NOT use this due to the possibility of overflowing \"buffer\". Instead use\nmysnprintf()\n\nint mysprintf(NN char *buffer, NN const char *pat, ...)\n\n\"mystrnlen\"\nThe C library \"strnlen\" if available, or a Perl implementation of it.\n\nmystrnlen() computes the length of the string, up to \"maxlen\" characters. It will never\nattempt to address more than \"maxlen\" characters, making it suitable for use with strings\nthat are not guaranteed to be NUL-terminated.\n\nSizet mystrnlen(const char *str, Sizet maxlen)\n\n\"myvsnprintf\"\nThe C library \"vsnprintf\" if available and standards-compliant. However, if the\n\"vsnprintf\" is not available, will unfortunately use the unsafe \"vsprintf\" which can\noverrun the buffer (there is an overrun check, but that may be too late). Consider using\n\"svvcatpvf\" instead, or getting \"vsnprintf\".\n\nint myvsnprintf(char *buffer, const Sizet len,\nconst char *format, valist ap)\n\n\"NewCopy\"\nCombines Newx() and Copy() into a single macro. Dest will be allocated using Newx() and\nthen src will be copied into it.\n\nvoid NewCopy(void* src, void* dest, int nitems, type)\n\n\"ninstr\"\nFind the first (leftmost) occurrence of a sequence of bytes within another sequence.\nThis is the Perl version of strstr(), extended to handle arbitrary sequences, potentially\ncontaining embedded \"NUL\" characters (\"NUL\" is what the initial \"n\" in the function name\nstands for; some systems have an equivalent, memmem(), but with a somewhat different\nAPI).\n\nAnother way of thinking about this function is finding a needle in a haystack. \"big\"\npoints to the first byte in the haystack. \"bigend\" points to one byte beyond the final\nbyte in the haystack. \"little\" points to the first byte in the needle. \"littleend\"\npoints to one byte beyond the final byte in the needle. All the parameters must be\nnon-\"NULL\".\n\nThe function returns \"NULL\" if there is no occurrence of \"little\" within \"big\". If\n\"little\" is the empty string, \"big\" is returned.\n\nBecause this function operates at the byte level, and because of the inherent\ncharacteristics of UTF-8 (or UTF-EBCDIC), it will work properly if both the needle and\nthe haystack are strings with the same UTF-8ness, but not if the UTF-8ness differs.\n\nchar * ninstr(const char *big, const char *bigend,\nconst char *little, const char *lend)\n\n\"Nullch\"\nNull character pointer. (No longer available when \"PERLCORE\" is defined.)\n\n\"PLna\"\nA scratch pad variable in which to store a \"STRLEN\" value. If would have been better\nnamed something like \"PLtempstrlen\".\n\nIt is is typically used with \"SvPV\" when one is actually planning to discard the returned\nlength, (hence the length is \"Not Applicable\", which is how this variable got its name).\n\nBUT BEWARE, if this is used in a situation where something that is using it is in a call\nstack with something else that is using it, this variable would get zapped, leading to\nhard-to-diagnose errors.\n\nIt is usually more efficient to either declare a local variable and use that instead, or\nto use the \"SvPVnolen\" macro.\n\nSTRLEN PLna\n\n\"rninstr\"\nLike \"ninstr\", but instead finds the final (rightmost) occurrence of a sequence of bytes\nwithin another sequence, returning \"NULL\" if there is no such occurrence.\n\nchar * rninstr(const char *big, const char *bigend,\nconst char *little, const char *lend)\n\n\"savepv\"\nPerl's version of strdup(). Returns a pointer to a newly allocated string which is a\nduplicate of \"pv\". The size of the string is determined by strlen(), which means it may\nnot contain embedded \"NUL\" characters and must have a trailing \"NUL\". To prevent memory\nleaks, the memory allocated for the new string needs to be freed when no longer needed.\nThis can be done with the \"Safefree\" function, or \"SAVEFREEPV\".\n\nOn some platforms, Windows for example, all allocated memory owned by a thread is\ndeallocated when that thread ends. So if you need that not to happen, you need to use\nthe shared memory functions, such as \"savesharedpv\".\n\nchar * savepv(const char *pv)\n\n\"savepvn\"\nPerl's version of what strndup() would be if it existed. Returns a pointer to a newly\nallocated string which is a duplicate of the first \"len\" bytes from \"pv\", plus a trailing\n\"NUL\" byte. The memory allocated for the new string can be freed with the Safefree()\nfunction.\n\nOn some platforms, Windows for example, all allocated memory owned by a thread is\ndeallocated when that thread ends. So if you need that not to happen, you need to use\nthe shared memory functions, such as \"savesharedpvn\".\n\nchar * savepvn(const char *pv, Sizet len)\n\n\"savepvs\"\nLike \"savepvn\", but takes a literal string instead of a string/length pair.\n\nchar* savepvs(\"literal string\")\n\n\"savesharedpv\"\nA version of savepv() which allocates the duplicate string in memory which is shared\nbetween threads.\n\nchar * savesharedpv(const char *pv)\n\n\"savesharedpvn\"\nA version of savepvn() which allocates the duplicate string in memory which is shared\nbetween threads. (With the specific difference that a \"NULL\" pointer is not acceptable)\n\nchar * savesharedpvn(const char * const pv, const STRLEN len)\n\n\"savesharedpvs\"\nA version of savepvs() which allocates the duplicate string in memory which is shared\nbetween threads.\n\nchar* savesharedpvs(\"literal string\")\n\n\"savesharedsvpv\"\nA version of savesharedpv() which allocates the duplicate string in memory which is\nshared between threads.\n\nchar * savesharedsvpv(SV *sv)\n\n\"savesvpv\"\nA version of savepv()/savepvn() which gets the string to duplicate from the passed in SV\nusing SvPV()\n\nOn some platforms, Windows for example, all allocated memory owned by a thread is\ndeallocated when that thread ends. So if you need that not to happen, you need to use\nthe shared memory functions, such as \"savesharedsvpv\".\n\nchar * savesvpv(SV *sv)\n\n\"strEQ\"\nTest two \"NUL\"-terminated strings to see if they are equal. Returns true or false.\n\nbool strEQ(char* s1, char* s2)\n\n\"strGE\"\nTest two \"NUL\"-terminated strings to see if the first, \"s1\", is greater than or equal to\nthe second, \"s2\". Returns true or false.\n\nbool strGE(char* s1, char* s2)\n\n\"strGT\"\nTest two \"NUL\"-terminated strings to see if the first, \"s1\", is greater than the second,\n\"s2\". Returns true or false.\n\nbool strGT(char* s1, char* s2)\n\n\"STRINGIFY\"\nThis macro surrounds its token with double quotes.\n\nstring STRINGIFY(token x)\n\n\"strLE\"\nTest two \"NUL\"-terminated strings to see if the first, \"s1\", is less than or equal to the\nsecond, \"s2\". Returns true or false.\n\nbool strLE(char* s1, char* s2)\n\n\"STRLEN\"\nDescribed in perlguts.\n\n\"strLT\"\nTest two \"NUL\"-terminated strings to see if the first, \"s1\", is less than the second,\n\"s2\". Returns true or false.\n\nbool strLT(char* s1, char* s2)\n\n\"strNE\"\nTest two \"NUL\"-terminated strings to see if they are different. Returns true or false.\n\nbool strNE(char* s1, char* s2)\n\n\"strnEQ\"\nTest two \"NUL\"-terminated strings to see if they are equal. The \"len\" parameter\nindicates the number of bytes to compare. Returns true or false. (A wrapper for\n\"strncmp\").\n\nbool strnEQ(char* s1, char* s2, STRLEN len)\n\n\"strnNE\"\nTest two \"NUL\"-terminated strings to see if they are different. The \"len\" parameter\nindicates the number of bytes to compare. Returns true or false. (A wrapper for\n\"strncmp\").\n\nbool strnNE(char* s1, char* s2, STRLEN len)\n\n\"STRWITHLEN\"\nReturns two comma separated tokens of the input literal string, and its length. This is\nconvenience macro which helps out in some API calls. Note that it can't be used as an\nargument to macros or functions that under some configurations might be macros, which\nmeans that it requires the full Perlxxx(aTHX ...) form for any API calls where it's\nused.\n\npair STRWITHLEN(\"literal string\")\n\n\"Zero\"\n\"ZeroD\"\nThe XSUB-writer's interface to the C \"memzero\" function. The \"dest\" is the destination,\n\"nitems\" is the number of items, and \"type\" is the type.\n\n\"ZeroD\" is like \"Zero\" but returns \"dest\". Useful for encouraging compilers to tail-call\noptimise.\n\nvoid Zero (void* dest, int nitems, type)\nvoid * ZeroD(void* dest, int nitems, type)\n\nSV Flags\n\"SVtIV\"\nType flag for scalars. See \"svtype\".\n\n\"SVtNULL\"\nType flag for scalars. See \"svtype\".\n\n\"SVtNV\"\nType flag for scalars. See \"svtype\".\n\n\"SVtPV\"\nType flag for scalars. See \"svtype\".\n\n\"SVtPVAV\"\nType flag for arrays. See \"svtype\".\n\n\"SVtPVCV\"\nType flag for subroutines. See \"svtype\".\n\n\"SVtPVFM\"\nType flag for formats. See \"svtype\".\n\n\"SVtPVGV\"\nType flag for typeglobs. See \"svtype\".\n\n\"SVtPVHV\"\nType flag for hashes. See \"svtype\".\n\n\"SVtPVIO\"\nType flag for I/O objects. See \"svtype\".\n\n\"SVtPVIV\"\nType flag for scalars. See \"svtype\".\n\n\"SVtPVLV\"\nType flag for scalars. See \"svtype\".\n\n\"SVtPVMG\"\nType flag for scalars. See \"svtype\".\n\n\"SVtPVNV\"\nType flag for scalars. See \"svtype\".\n\n\"SVtPVOBJ\"\nNOTE: \"SVtPVOBJ\" is experimental and may change or be removed without notice.\n\nType flag for object instances. See \"svtype\".\n\n\"SVtREGEXP\"\nType flag for regular expressions. See \"svtype\".\n\n\"svtype\"\nAn enum of flags for Perl types. These are found in the file sv.h in the \"svtype\" enum.\nTest these flags with the \"SvTYPE\" macro.\n\nThe types are:\n\nSVtNULL\nSVtIV\nSVtNV\nSVtRV\nSVtPV\nSVtPVIV\nSVtPVNV\nSVtPVMG\nSVtINVLIST\nSVtREGEXP\nSVtPVGV\nSVtPVLV\nSVtPVAV\nSVtPVHV\nSVtPVCV\nSVtPVFM\nSVtPVIO\nSVtPVOBJ\n\nThese are most easily explained from the bottom up.\n\n\"SVtPVOBJ\" is for object instances of the new `use feature 'class'` kind. \"SVtPVIO\" is\nfor I/O objects, \"SVtPVFM\" for formats, \"SVtPVCV\" for subroutines, \"SVtPVHV\" for\nhashes and \"SVtPVAV\" for arrays.\n\nAll the others are scalar types, that is, things that can be bound to a \"$\" variable.\nFor these, the internal types are mostly orthogonal to types in the Perl language.\n\nHence, checking \"SvTYPE(sv) < SVtPVAV\" is the best way to see whether something is a\nscalar.\n\n\"SVtPVGV\" represents a typeglob. If \"!SvFAKE(sv)\", then it is a real, incoercible\ntypeglob. If SvFAKE(sv), then it is a scalar to which a typeglob has been assigned.\nAssigning to it again will stop it from being a typeglob. \"SVtPVLV\" represents a scalar\nthat delegates to another scalar behind the scenes. It is used, e.g., for the return\nvalue of \"substr\" and for tied hash and array elements. It can hold any scalar value,\nincluding a typeglob. \"SVtREGEXP\" is for regular expressions. \"SVtINVLIST\" is for\nPerl core internal use only.\n\n\"SVtPVMG\" represents a \"normal\" scalar (not a typeglob, regular expression, or\ndelegate). Since most scalars do not need all the internal fields of a PVMG, we save\nmemory by allocating smaller structs when possible. All the other types are just simpler\nforms of \"SVtPVMG\", with fewer internal fields. \"SVtNULL\" can only hold undef.\n\"SVtIV\" can hold undef, an integer, or a reference. (\"SVtRV\" is an alias for \"SVtIV\",\nwhich exists for backward compatibility.) \"SVtNV\" can hold undef or a double. (In\nbuilds that support headless NVs, these could also hold a reference via a suitable\noffset, in the same way that SVtIV does, but this is not currently supported and seems\nto be a rare use case.) \"SVtPV\" can hold \"undef\", a string, or a reference. \"SVtPVIV\"\nis a superset of \"SVtPV\" and \"SVtIV\". \"SVtPVNV\" is a superset of \"SVtPV\" and\n\"SVtNV\". \"SVtPVMG\" can hold anything \"SVtPVNV\" can hold, but it may also be blessed or\nmagical.\n\nSV Handling\n\"AVFROMREF\"\n\"CVFROMREF\"\n\"HVFROMREF\"\nThe \"*VFROMREF\" macros extract the SvRV() from a given reference SV and return a\nsuitably-cast to pointer to the referenced SV. When running under \"-DDEBUGGING\",\nassertions are also applied that check that ref is definitely a reference SV that refers\nto an SV of the right type.\n\nAV * AVFROMREF(SV * ref)\nCV * CVFROMREF(SV * ref)\nHV * HVFROMREF(SV * ref)\n\n\"BOOLINTERNALSsvisbool\"\nChecks if a SvBoolFlagsOK() sv is a bool. Note that it is the caller's responsibility to\nensure that the sv is SvBoolFlagsOK() before calling this. This is only useful in\nspecialized logic like serialization code where performance is critical and the flags\nhave already been checked to be correct. Almost always you should be using svisbool(sv)\ninstead.\n\nbool BOOLINTERNALSsvisbool(SV* sv)\n\n\"BOOLINTERNALSsvisboolfalse\"\nChecks if a SvBoolFlagsOK() sv is a false bool. Note that it is the caller's\nresponsibility to ensure that the sv is SvBoolFlagsOK() before calling this. This is only\nuseful in specialized logic like serialization code where performance is critical and the\nflags have already been checked to be correct. This is NOT what you should use to check\nif an SV is \"false\", for that you should be using \"!SvTRUE(sv)\" instead.\n\nbool BOOLINTERNALSsvisboolfalse(SV* sv)\n\n\"BOOLINTERNALSsvisbooltrue\"\nChecks if a SvBoolFlagsOK() sv is a true bool. Note that it is the caller's\nresponsibility to ensure that the sv is SvBoolFlagsOK() before calling this. This is only\nuseful in specialized logic like serialization code where performance is critical and the\nflags have already been checked to be correct. This is NOT what you should use to check\nif an SV is \"true\", for that you should be using SvTRUE(sv) instead.\n\nbool BOOLINTERNALSsvisbooltrue(SV* sv)\n\n\"boolSV\"\nReturns a true SV if \"b\" is a true value, or a false SV if \"b\" is 0.\n\nSee also \"PLsvyes\" and \"PLsvno\".\n\nSV * boolSV(bool b)\n\n\"croakxsusage\"\nA specialised variant of croak() for emitting the usage message for xsubs\n\ncroakxsusage(cv, \"eeeyow\");\n\nworks out the package name and subroutine name from \"cv\", and then calls croak(). Hence\nif \"cv\" is &ouch::awk, it would call \"croak\" as:\n\nPerlcroak(aTHX \"Usage: %\" SVf \"::%\" SVf \"(%s)\", \"ouch\" \"awk\",\n\"eeeyow\");\n\nvoid croakxsusage(const CV * const cv,\nconst char * const params)\n\n\"DEFSV\"\nReturns the SV associated with $\n\nSV * DEFSV\n\n\"DEFSVset\"\nAssociate \"sv\" with $\n\nvoid DEFSVset(SV * sv)\n\n\"getsv\"\nReturns the SV of the specified Perl scalar. \"flags\" are passed to \"\"gvfetchpv\"\". If\n\"GVADD\" is set and the Perl variable does not exist then it will be created. If \"flags\"\nis zero and the variable does not exist then NULL is returned.\n\nNOTE: the perlgetsv() form is deprecated.\n\nSV * getsv(const char *name, I32 flags)\n\n\"isGVwithGP\"\nReturns a boolean as to whether or not \"sv\" is a GV with a pointer to a GP (glob\npointer).\n\nbool isGVwithGP(SV * sv)\n\n\"lookslikenumber\"\nTest if the content of an SV looks like a number (or is a number). \"Inf\" and \"Infinity\"\nare treated as numbers (so will not issue a non-numeric warning), even if your atof()\ndoesn't grok them. Get-magic is ignored.\n\nI32 lookslikenumber(SV * const sv)\n\n\"MUTABLEAV\"\n\"MUTABLECV\"\n\"MUTABLEGV\"\n\"MUTABLEHV\"\n\"MUTABLEIO\"\n\"MUTABLEPTR\"\n\"MUTABLESV\"\nThe \"MUTABLE*\"() macros cast pointers to the types shown, in such a way (compiler\npermitting) that casting away const-ness will give a warning; e.g.:\n\nconst SV *sv = ...;\nAV *av1 = (AV*)sv; <== BAD: the const has been silently\ncast away\nAV *av2 = MUTABLEAV(sv); <== GOOD: it may warn\n\n\"MUTABLEPTR\" is the base macro used to derive new casts. The other already-built-in\nones return pointers to what their names indicate.\n\nAV * MUTABLEAV (AV * p)\nCV * MUTABLECV (CV * p)\nGV * MUTABLEGV (GV * p)\nHV * MUTABLEHV (HV * p)\nIO * MUTABLEIO (IO * p)\nvoid * MUTABLEPTR(void * p)\nSV * MUTABLESV (SV * p)\n\n\"newRV\"\n\"newRVinc\"\nThese are identical. They create an RV wrapper for an SV. The reference count for the\noriginal SV is incremented.\n\nSV * newRV(SV * const sv)\n\n\"newRVnoinc\"\nCreates an RV wrapper for an SV. The reference count for the original SV is not\nincremented.\n\nSV * newRVnoinc(SV * const tmpRef)\n\n\"newSV\"\nCreates a new SV. A non-zero \"len\" parameter indicates the number of bytes of\npreallocated string space the SV should have. An extra byte for a trailing \"NUL\" is also\nreserved. (\"SvPOK\" is not set for the SV even if string space is allocated.) The\nreference count for the new SV is set to 1.\n\nIn 5.9.3, newSV() replaces the older NEWSV() API, and drops the first parameter, x, a\ndebug aid which allowed callers to identify themselves. This aid has been superseded by\na new build option, \"PERLMEMLOG\" (see \"PERLMEMLOG\" in perlhacktips). The older API\nis still there for use in XS modules supporting older perls.\n\nSV * newSV(const STRLEN len)\n\n\"newSVbool\"\nCreates a new SV boolean.\n\nSV * newSVbool(const bool boolval)\n\n\"newSVfalse\"\nCreates a new SV that is a boolean false.\n\nSV * newSVfalse()\n\n\"newSVhek\"\nCreates a new SV from the hash key structure. It will generate scalars that point to the\nshared string table where possible. Returns a new (undefined) SV if \"hek\" is NULL.\n\nSV * newSVhek(const HEK * const hek)\n\n\"newSVhekmortal\"\nCreates a new mortal SV from the hash key structure. It will generate scalars that point\nto the shared string table where possible. Returns a new (undefined) SV if \"hek\" is\nNULL.\n\nThis is more efficient than using sv2mortal(newSVhek( ... ))\n\nSV * newSVhekmortal(const HEK * const hek)\n\n\"newSViv\"\nCreates a new SV and copies an integer into it. The reference count for the SV is set to\n1.\n\nSV * newSViv(const IV i)\n\n\"newSVnv\"\nCreates a new SV and copies a floating point value into it. The reference count for the\nSV is set to 1.\n\nSV * newSVnv(const NV n)\n\n\"newSVpadname\"\nNOTE: \"newSVpadname\" is experimental and may change or be removed without notice.\n\nCreates a new SV containing the pad name.\n\nSV* newSVpadname(PADNAME *pn)\n\n\"newSVpv\"\nCreates a new SV and copies a string (which may contain \"NUL\" (\"\\0\") characters) into it.\nThe reference count for the SV is set to 1. If \"len\" is zero, Perl will compute the\nlength using strlen(), (which means if you use this option, that \"s\" can't have embedded\n\"NUL\" characters and has to have a terminating \"NUL\" byte).\n\nThis function can cause reliability issues if you are likely to pass in empty strings\nthat are not null terminated, because it will run strlen on the string and potentially\nrun past valid memory.\n\nUsing \"newSVpvn\" is a safer alternative for non \"NUL\" terminated strings. For string\nliterals use \"newSVpvs\" instead. This function will work fine for \"NUL\" terminated\nstrings, but if you want to avoid the if statement on whether to call \"strlen\" use\n\"newSVpvn\" instead (calling \"strlen\" yourself).\n\nSV * newSVpv(const char * const s, const STRLEN len)\n\n\"newSVpvf\"\nCreates a new SV and initializes it with the string formatted like \"svcatpvf\".\n\nNOTE: \"newSVpvf\" must be explicitly called as \"PerlnewSVpvf\" with an \"aTHX\" parameter.\n\nSV * PerlnewSVpvf(pTHX const char * const pat, ...)\n\n\"newSVpvfnocontext\"\nLike \"newSVpvf\" but does not take a thread context (\"aTHX\") parameter, so is used in\nsituations where the caller doesn't already have the thread context.\n\nSV * newSVpvfnocontext(const char * const pat, ...)\n\n\"newSVpvn\"\nCreates a new SV and copies a string into it, which may contain \"NUL\" characters (\"\\0\")\nand other binary data. The reference count for the SV is set to 1. Note that if \"len\"\nis zero, Perl will create a zero length (Perl) string. You are responsible for ensuring\nthat the source buffer is at least \"len\" bytes long. If the \"buffer\" argument is NULL\nthe new SV will be undefined.\n\nSV * newSVpvn(const char * const buffer, const STRLEN len)\n\n\"newSVpvnflags\"\nCreates a new SV and copies a string (which may contain \"NUL\" (\"\\0\") characters) into it.\nThe reference count for the SV is set to 1. Note that if \"len\" is zero, Perl will create\na zero length string. You are responsible for ensuring that the source string is at\nleast \"len\" bytes long. If the \"s\" argument is NULL the new SV will be undefined.\nCurrently the only flag bits accepted are \"SVfUTF8\" and \"SVsTEMP\". If \"SVsTEMP\" is\nset, then sv2mortal() is called on the result before returning. If \"SVfUTF8\" is set,\n\"s\" is considered to be in UTF-8 and the \"SVfUTF8\" flag will be set on the new SV.\nnewSVpvnutf8() is a convenience wrapper for this function, defined as\n\n#define newSVpvnutf8(s, len, u) \\\nnewSVpvnflags((s), (len), (u) ? SVfUTF8 : 0)\n\nSV * newSVpvnflags(const char * const s, const STRLEN len,\nconst U32 flags)\n\n\"newSVpvnshare\"\nCreates a new SV with its \"SvPVXconst\" pointing to a shared string in the string table.\nIf the string does not already exist in the table, it is created first. Turns on the\n\"SvIsCOW\" flag (or \"READONLY\" and \"FAKE\" in 5.16 and earlier). If the \"hash\" parameter\nis non-zero, that value is used; otherwise the hash is computed. The string's hash can\nlater be retrieved from the SV with the \"SvSHAREDHASH\" macro. The idea here is that as\nthe string table is used for shared hash keys these strings will have \"SvPVXconst ==\nHeKEY\" and hash lookup will avoid string compare.\n\nSV * newSVpvnshare(const char *s, I32 len, U32 hash)\n\n\"newSVpvnutf8\"\nCreates a new SV and copies a string (which may contain \"NUL\" (\"\\0\") characters) into it.\nIf \"utf8\" is true, calls \"SvUTF8on\" on the new SV. Implemented as a wrapper around\n\"newSVpvnflags\".\n\nSV* newSVpvnutf8(const char* s, STRLEN len, U32 utf8)\n\n\"newSVpvs\"\nLike \"newSVpvn\", but takes a literal string instead of a string/length pair.\n\nSV* newSVpvs(\"literal string\")\n\n\"newSVpvsflags\"\nLike \"newSVpvnflags\", but takes a literal string instead of a string/length pair.\n\nSV* newSVpvsflags(\"literal string\", U32 flags)\n\n\"newSVpvshare\"\nLike \"newSVpvnshare\", but takes a \"NUL\"-terminated string instead of a string/length\npair.\n\nSV * newSVpvshare(const char *s, U32 hash)\n\n\"newSVpvsshare\"\nLike \"newSVpvnshare\", but takes a literal string instead of a string/length pair and\nomits the hash parameter.\n\nSV* newSVpvsshare(\"literal string\")\n\n\"newSVrv\"\nCreates a new SV for the existing RV, \"rv\", to point to. If \"rv\" is not an RV then it\nwill be upgraded to one. If \"classname\" is non-null then the new SV will be blessed in\nthe specified package. The new SV is returned and its reference count is 1. The\nreference count 1 is owned by \"rv\". See also newRVinc() and newRVnoinc() for creating a\nnew RV properly.\n\nSV * newSVrv(SV * const rv, const char * const classname)\n\n\"newSVsv\"\n\"newSVsvflags\"\n\"newSVsvnomg\"\nThese create a new SV which is an exact duplicate of the original SV (using \"svsetsv\".)\n\nThey differ only in that \"newSVsv\" performs 'get' magic; \"newSVsvnomg\" skips any magic;\nand \"newSVsvflags\" allows you to explicitly set a \"flags\" parameter.\n\nSV * newSVsv (SV * const old)\nSV * newSVsvflags(SV * const old, I32 flags)\nSV * newSVsvnomg (SV * const old)\n\n\"newSVtrue\"\nCreates a new SV that is a boolean true.\n\nSV * newSVtrue()\n\n\"newSVtype\"\nCreates a new SV, of the type specified. The reference count for the new SV is set to 1.\n\nSV * newSVtype(const svtype type)\n\n\"newSVtypemortal\"\nCreates a new mortal SV, of the type specified. The reference count for the new SV is\nset to 1.\n\nThis is equivalent to\nSV* sv = sv2mortal(newSVtype()) and\nSV* sv = svnewmortal();\nsvupgrade(sv, ) but should be more efficient than both of them. (Unless\nsv2mortal is inlined at some point in the future.)\n\nSV * newSVtypemortal(const svtype type)\n\n\"newSVuv\"\nCreates a new SV and copies an unsigned integer into it. The reference count for the SV\nis set to 1.\n\nSV * newSVuv(const UV u)\n\n\"Nullsv\"\nNull SV pointer. (No longer available when \"PERLCORE\" is defined.)\n\n\"PLsvno\"\nThis is the \"false\" SV. It is readonly. See \"PLsvyes\". Always refer to this as\n&PLsvno.\n\nSV PLsvno\n\n\"PLsvundef\"\nThis is the \"undef\" SV. It is readonly. Always refer to this as &PLsvundef.\n\nSV PLsvundef\n\n\"PLsvyes\"\nThis is the \"true\" SV. It is readonly. See \"PLsvno\". Always refer to this as\n&PLsvyes.\n\nSV PLsvyes\n\n\"PLsvzero\"\nThis readonly SV has a zero numeric value and a \"0\" string value. It's similar to\n\"PLsvno\" except for its string value. Can be used as a cheap alternative to mXPUSHi(0)\nfor example. Always refer to this as &PLsvzero. Introduced in 5.28.\n\nSV PLsvzero\n\n\"SAVEDEFSV\"\nLocalize $. See \"Localizing changes\" in perlguts.\n\nvoid SAVEDEFSV\n\n\"sortsv\"\nIn-place sort an array of SV pointers with the given comparison routine.\n\nCurrently this always uses mergesort. See \"sortsvflags\" for a more flexible routine.\n\nvoid sortsv(SV array, sizet numelts, SVCOMPAREt cmp)\n\n\"sortsvflags\"\nIn-place sort an array of SV pointers with the given comparison routine, with various\nSORTf* flag options.\n\nvoid sortsvflags(SV array, sizet numelts, SVCOMPAREt cmp,\nU32 flags)\n\n\"SV\"\nDescribed in perlguts.\n\n\"SvAMAGIC\"\nReturns a boolean as to whether \"sv\" has overloading (active magic) enabled or not.\n\nbool SvAMAGIC(SV * sv)\n\n\"SvAMAGICoff\"\nIndicate that \"sv\" has overloading (active magic) disabled.\n\nvoid SvAMAGICoff(SV *sv)\n\n\"SvAMAGICon\"\nIndicate that \"sv\" has overloading (active magic) enabled.\n\nvoid SvAMAGICon(SV *sv)\n\n\"svbackoff\"\nRemove any string offset. You should normally use the \"SvOOKoff\" macro wrapper instead.\n\nvoid svbackoff(SV * const sv)\n\n\"svbless\"\nBlesses an SV into a specified package. The SV must be an RV. The package must be\ndesignated by its stash (see \"gvstashpv\"). The reference count of the SV is unaffected.\n\nSV * svbless(SV * const sv, HV * const stash)\n\n\"SvBoolFlagsOK\"\nReturns a bool indicating whether the SV has the right flags set such that it is safe to\ncall BOOLINTERNALSsvisbool() or BOOLINTERNALSsvisbooltrue() or\nBOOLINTERNALSsvisboolfalse(). Currently equivalent to SvIandPOK(sv) or \"SvIOK(sv) &&\nSvPOK(sv)\". Serialization may want to unroll this check. If so you are strongly\nrecommended to add code like \"assert(SvBoolFlagsOK(sv));\" before calling using any of the\nBOOLINTERNALS macros.\n\nU32 SvBoolFlagsOK(SV* sv)\n\n\"svcatpv\"\n\"svcatpvflags\"\n\"svcatpvmg\"\n\"svcatpvnomg\"\nThese concatenate the \"NUL\"-terminated string \"sstr\" onto the end of the string which is\nin the SV. If the SV has the UTF-8 status set, then the bytes appended should be valid\nUTF-8.\n\nThey differ only in how they handle magic:\n\n\"svcatpvmg\" performs both 'get' and 'set' magic.\n\n\"svcatpv\" performs only 'get' magic.\n\n\"svcatpvnomg\" skips all magic.\n\n\"svcatpvflags\" has an extra \"flags\" parameter which allows you to specify any\ncombination of magic handling (using \"SVGMAGIC\" and/or \"SVSMAGIC\"), and to also\noverride the UTF-8 handling. By supplying the \"SVCATUTF8\" flag, the appended string is\nforced to be interpreted as UTF-8; by supplying instead the \"SVCATBYTES\" flag, it will\nbe interpreted as just bytes. Either the SV or the string appended will be upgraded to\nUTF-8 if necessary.\n\nvoid svcatpv (SV * const dsv, const char *sstr)\nvoid svcatpvflags(SV *dsv, const char *sstr, const I32 flags)\nvoid svcatpvmg (SV * const dsv, const char * const sstr)\nvoid svcatpvnomg (SV * const dsv, const char *sstr)\n\n\"svcatpvf\"\n\"svcatpvfmg\"\n\"svcatpvfmgnocontext\"\n\"svcatpvfnocontext\"\nThese process their arguments like \"sprintf\", and append the formatted output to an SV.\nAs with \"svvcatpvfn\", argument reordering is not supporte when called with a non-null\nC-style variable argument list.\n\nIf the appended data contains \"wide\" characters (including, but not limited to, SVs with\na UTF-8 PV formatted with %s, and characters >255 formatted with %c), the original SV\nmight get upgraded to UTF-8.\n\nIf the original SV was UTF-8, the pattern should be valid UTF-8; if the original SV was\nbytes, the pattern should be too.\n\nAll perform 'get' magic, but only \"svcatpvfmg\" and \"svcatpvfmgnocontext\" perform\n'set' magic.\n\n\"svcatpvfnocontext\" and \"svcatpvfmgnocontext\" do not take a thread context (\"aTHX\")\nparameter, so are used in situations where the caller doesn't already have the thread\ncontext.\n\nNOTE: \"svcatpvf\" must be explicitly called as \"Perlsvcatpvf\" with an \"aTHX\"\nparameter.\n\nNOTE: \"svcatpvfmg\" must be explicitly called as \"Perlsvcatpvfmg\" with an \"aTHX\"\nparameter.\n\nvoid Perlsvcatpvf (pTHX SV * const sv,\nconst char * const pat, ...)\nvoid Perlsvcatpvfmg (pTHX SV * const sv,\nconst char * const pat, ...)\nvoid svcatpvfmgnocontext(SV * const sv,\nconst char * const pat, ...)\nvoid svcatpvfnocontext (SV * const sv,\nconst char * const pat, ...)\n\n\"svcatpvn\"\n\"svcatpvnflags\"\n\"svcatpvnmg\"\n\"svcatpvnnomg\"\nThese concatenate the \"len\" bytes of the string beginning at \"ptr\" onto the end of the\nstring which is in \"dsv\". The caller must make sure \"ptr\" contains at least \"len\" bytes.\n\nFor all but \"svcatpvnflags\", the string appended is assumed to be valid UTF-8 if the SV\nhas the UTF-8 status set, and a string of bytes otherwise.\n\nThey differ in that:\n\n\"svcatpvnmg\" performs both 'get' and 'set' magic on \"dsv\".\n\n\"svcatpvn\" performs only 'get' magic.\n\n\"svcatpvnnomg\" skips all magic.\n\n\"svcatpvnflags\" has an extra \"flags\" parameter which allows you to specify any\ncombination of magic handling (using \"SVGMAGIC\" and/or \"SVSMAGIC\") and to also override\nthe UTF-8 handling. By supplying the \"SVCATBYTES\" flag, the appended string is\ninterpreted as plain bytes; by supplying instead the \"SVCATUTF8\" flag, it will be\ninterpreted as UTF-8, and the \"dsv\" will be upgraded to UTF-8 if necessary.\n\n\"svcatpvn\", \"svcatpvnmg\", and \"svcatpvnnomg\" are implemented in terms of\n\"svcatpvnflags\".\n\nvoid svcatpvn (SV *dsv, const char *sstr, STRLEN len)\nvoid svcatpvnflags(SV * const dsv, const char *sstr,\nconst STRLEN len, const I32 flags)\nvoid svcatpvnmg (SV *dsv, const char *sstr, STRLEN len)\nvoid svcatpvnnomg (SV *dsv, const char *sstr, STRLEN len)\n\n\"svcatpvs\"\nLike \"svcatpvn\", but takes a literal string instead of a string/length pair.\n\nvoid svcatpvs(SV* sv, \"literal string\")\n\n\"svcatpvsflags\"\nLike \"svcatpvnflags\", but takes a literal string instead of a string/length pair.\n\nvoid svcatpvsflags(SV* sv, \"literal string\", I32 flags)\n\n\"svcatpvsmg\"\nLike \"svcatpvnmg\", but takes a literal string instead of a string/length pair.\n\nvoid svcatpvsmg(SV* sv, \"literal string\")\n\n\"svcatpvsnomg\"\nLike \"svcatpvnnomg\", but takes a literal string instead of a string/length pair.\n\nvoid svcatpvsnomg(SV* sv, \"literal string\")\n\n\"svcatsv\"\n\"svcatsvflags\"\n\"svcatsvmg\"\n\"svcatsvnomg\"\nThese concatenate the string from SV \"sstr\" onto the end of the string in SV \"dsv\". If\n\"sstr\" is null, these are no-ops; otherwise only \"dsv\" is modified.\n\nThey differ only in what magic they perform:\n\n\"svcatsvmg\" performs 'get' magic on both SVs before the copy, and 'set' magic on \"dsv\"\nafterwards.\n\n\"svcatsv\" performs just 'get' magic, on both SVs.\n\n\"svcatsvnomg\" skips all magic.\n\n\"svcatsvflags\" has an extra \"flags\" parameter which allows you to use \"SVGMAGIC\"\nand/or \"SVSMAGIC\" to specify any combination of magic handling (although either both or\nneither SV will have 'get' magic applied to it.)\n\n\"svcatsv\", \"svcatsvmg\", and \"svcatsvnomg\" are implemented in terms of\n\"svcatsvflags\".\n\nvoid svcatsv (SV *dsv, SV *sstr)\nvoid svcatsvflags(SV * const dsv, SV * const sstr,\nconst I32 flags)\nvoid svcatsvmg (SV *dsv, SV *sstr)\nvoid svcatsvnomg (SV *dsv, SV *sstr)\n\n\"SVCHECKTHINKFIRST\"\nRemove any encumbrances from \"sv\", that need to be taken care of before it is modifiable.\nFor example if it is Copy on Write (COW), now is the time to make that copy.\n\nIf you know that you are about to change the PV value of \"sv\", instead use\n\"\"SVCHECKTHINKFIRSTCOWDROP\"\" to avoid the write that would be immediately written\nagain.\n\nvoid SVCHECKTHINKFIRST(SV * sv)\n\n\"SVCHECKTHINKFIRSTCOWDROP\"\nCall this when you are about to replace the PV value in \"sv\", which is potentially copy-\non-write. It stops any sharing with other SVs, so that no Copy on Write (COW) actually\nhappens. This COW would be useless, as it would immediately get changed to something\nelse. This function also removes any other encumbrances that would be problematic when\nchanging \"sv\".\n\nvoid SVCHECKTHINKFIRSTCOWDROP(SV * sv)\n\n\"svchop\"\nEfficient removal of characters from the beginning of the string buffer. SvPOK(sv), or\nat least SvPOKp(sv), must be true and \"ptr\" must be a pointer to somewhere inside the\nstring buffer. \"ptr\" becomes the first character of the adjusted string. Uses the \"OOK\"\nhack. On return, only SvPOK(sv) and SvPOKp(sv) among the \"OK\" flags will be true.\n\nBeware: after this function returns, \"ptr\" and SvPVXconst(sv) may no longer refer to the\nsame chunk of data.\n\nThe unfortunate similarity of this function's name to that of Perl's \"chop\" operator is\nstrictly coincidental. This function works from the left; \"chop\" works from the right.\n\nvoid svchop(SV * const sv, const char * const ptr)\n\n\"svclear\"\nClear an SV: call any destructors, free up any memory used by the body, and free the body\nitself. The SV's head is not freed, although its type is set to all 1's so that it won't\ninadvertently be assumed to be live during global destruction etc. This function should\nonly be called when \"REFCNT\" is zero. Most of the time you'll want to call\n\"SvREFCNTdec\" instead.\n\nvoid svclear(SV * const origsv)\n\n\"svcmp\"\nCompares the strings in two SVs. Returns -1, 0, or 1 indicating whether the string in\n\"sv1\" is less than, equal to, or greater than the string in \"sv2\". Is UTF-8 and\n'use bytes' aware, handles get magic, and will coerce its args to strings if necessary.\nSee also \"svcmplocale\".\n\nI32 svcmp(SV * const sv1, SV * const sv2)\n\n\"svcmpflags\"\nCompares the strings in two SVs. Returns -1, 0, or 1 indicating whether the string in\n\"sv1\" is less than, equal to, or greater than the string in \"sv2\". Is UTF-8 and\n'use bytes' aware and will coerce its args to strings if necessary. If the flags has the\n\"SVGMAGIC\" bit set, it handles get magic. See also \"svcmplocaleflags\".\n\nI32 svcmpflags(SV * const sv1, SV * const sv2, const U32 flags)\n\n\"svcmplocale\"\nCompares the strings in two SVs in a locale-aware manner. Is UTF-8 and 'use bytes'\naware, handles get magic, and will coerce its args to strings if necessary. See also\n\"svcmp\".\n\nI32 svcmplocale(SV * const sv1, SV * const sv2)\n\n\"svcmplocaleflags\"\nCompares the strings in two SVs in a locale-aware manner. Is UTF-8 and 'use bytes' aware\nand will coerce its args to strings if necessary. If the flags contain \"SVGMAGIC\", it\nhandles get magic. See also \"svcmpflags\".\n\nI32 svcmplocaleflags(SV * const sv1, SV * const sv2,\nconst U32 flags)\n\n\"svcollxfrm\"\nThis calls \"svcollxfrmflags\" with the SVGMAGIC flag. See \"svcollxfrmflags\".\n\nchar * svcollxfrm(SV * const sv, STRLEN * const nxp)\n\n\"svcollxfrmflags\"\nAdd Collate Transform magic to an SV if it doesn't already have it. If the flags contain\n\"SVGMAGIC\", it handles get-magic.\n\nAny scalar variable may carry \"PERLMAGICcollxfrm\" magic that contains the scalar data\nof the variable, but transformed to such a format that a normal memory comparison can be\nused to compare the data according to the locale settings.\n\nchar * svcollxfrmflags(SV * const sv, STRLEN * const nxp,\nI32 const flags)\n\n\"svcopypv\"\n\"svcopypvflags\"\n\"svcopypvnomg\"\nThese copy a stringified representation of the source SV into the destination SV. They\nautomatically perform coercion of numeric values into strings. Guaranteed to preserve\nthe \"UTF8\" flag even from overloaded objects. Similar in nature to \"sv2pv[flags]\" but\nthey operate directly on an SV instead of just the string. Mostly they use\n\"\"sv2pvflags\"\" to do the work, except when that would lose the UTF-8'ness of the PV.\n\nThe three forms differ only in whether or not they perform 'get magic' on \"sv\".\n\"svcopypvnomg\" skips 'get magic'; \"svcopypv\" performs it; and \"svcopypvflags\" either\nperforms it (if the \"SVGMAGIC\" bit is set in \"flags\") or doesn't (if that bit is\ncleared).\n\nvoid svcopypv (SV * const dsv, SV * const ssv)\nvoid svcopypvflags(SV * const dsv, SV * const ssv,\nconst I32 flags)\nvoid svcopypvnomg (SV * const dsv, SV * const ssv)\n\n\"SvCUR\"\nReturns the length, in bytes, of the PV inside the SV. Note that this may not match\nPerl's \"length\"; for that, use svlenutf8(sv). See \"SvLEN\" also.\n\nSTRLEN SvCUR(SV* sv)\n\n\"SvCURset\"\nSets the current length, in bytes, of the C string which is in the SV. See \"SvCUR\" and\n\"SvIVset\">.\n\nvoid SvCURset(SV* sv, STRLEN len)\n\n\"sv2cv\"\nUsing various gambits, try to get a CV from an SV; in addition, try if possible to set\n*st and *gvp to the stash and GV associated with it. The flags in \"lref\" are passed to\n\"gvfetchsv\".\n\nCV * sv2cv(SV *sv, HV const st, GV const gvp,\nconst I32 lref)\n\n\"svdec\"\n\"svdecnomg\"\nThese auto-decrement the value in the SV, doing string to numeric conversion if\nnecessary. They both handle operator overloading.\n\nThey differ only in that:\n\n\"svdec\" handles 'get' magic; \"svdecnomg\" skips 'get' magic.\n\nvoid svdec(SV * const sv)\n\n\"svderivedfrom\"\nExactly like \"svderivedfrompv\", but doesn't take a \"flags\" parameter.\n\nbool svderivedfrom(SV *sv, const char * const name)\n\n\"svderivedfromhv\"\nExactly like \"svderivedfrompvn\", but takes the name string as the \"HvNAME\" of the\ngiven HV (which would presumably represent a stash).\n\nbool svderivedfromhv(SV *sv, HV *hv)\n\n\"svderivedfrompv\"\nExactly like \"svderivedfrompvn\", but takes a nul-terminated string instead of a\nstring/length pair.\n\nbool svderivedfrompv(SV *sv, const char * const name,\nU32 flags)\n\n\"svderivedfrompvn\"\nReturns a boolean indicating whether the SV is derived from the specified class at the C\nlevel. To check derivation at the Perl level, call isa() as a normal Perl method.\n\nCurrently, the only significant value for \"flags\" is SVfUTF8.\n\nbool svderivedfrompvn(SV *sv, const char * const name,\nconst STRLEN len, U32 flags)\n\n\"svderivedfromsv\"\nExactly like \"svderivedfrompvn\", but takes the name string in the form of an SV\ninstead of a string/length pair. This is the advised form.\n\nbool svderivedfromsv(SV *sv, SV *namesv, U32 flags)\n\n\"svdoes\"\nLike \"svdoespv\", but doesn't take a \"flags\" parameter.\n\nbool svdoes(SV *sv, const char * const name)\n\n\"svdoespv\"\nLike \"svdoessv\", but takes a nul-terminated string instead of an SV.\n\nbool svdoespv(SV *sv, const char * const name, U32 flags)\n\n\"svdoespvn\"\nLike \"svdoessv\", but takes a string/length pair instead of an SV.\n\nbool svdoespvn(SV *sv, const char * const name,\nconst STRLEN len, U32 flags)\n\n\"svdoessv\"\nReturns a boolean indicating whether the SV performs a specific, named role. The SV can\nbe a Perl object or the name of a Perl class.\n\nbool svdoessv(SV *sv, SV *namesv, U32 flags)\n\n\"SvEND\"\nReturns a pointer to the spot just after the last character in the string which is in the\nSV, where there is usually a trailing \"NUL\" character (even though Perl scalars do not\nstrictly require it). See \"SvCUR\". Access the character as \"*(SvEND(sv))\".\n\nWarning: If \"SvCUR\" is equal to \"SvLEN\", then \"SvEND\" points to unallocated memory.\n\nchar* SvEND(SV* sv)\n\n\"sveq\"\nReturns a boolean indicating whether the strings in the two SVs are identical. Is UTF-8\nand 'use bytes' aware, handles get magic, and will coerce its args to strings if\nnecessary.\n\nThis function does not handle operator overloading. For a version that does, see instead\n\"svstreq\".\n\nI32 sveq(SV *sv1, SV *sv2)\n\n\"sveqflags\"\nReturns a boolean indicating whether the strings in the two SVs are identical. Is UTF-8\nand 'use bytes' aware and coerces its args to strings if necessary. If the flags has the\n\"SVGMAGIC\" bit set, it handles get-magic, too.\n\nThis function does not handle operator overloading. For a version that does, see instead\n\"svstreqflags\".\n\nI32 sveqflags(SV *sv1, SV *sv2, const U32 flags)\n\n\"svforcenormal\"\nUndo various types of fakery on an SV: if the PV is a shared string, make a private copy;\nif we're a ref, stop refing; if we're a glob, downgrade to an \"xpvmg\". See also\n\"svforcenormalflags\".\n\nvoid svforcenormal(SV *sv)\n\n\"svforcenormalflags\"\nUndo various types of fakery on an SV, where fakery means \"more than\" a string: if the PV\nis a shared string, make a private copy; if we're a ref, stop refing; if we're a glob,\ndowngrade to an \"xpvmg\"; if we're a copy-on-write scalar, this is the on-write time when\nwe do the copy, and is also used locally; if this is a vstring, drop the vstring magic.\nIf \"SVCOWDROPPV\" is set then a copy-on-write scalar drops its PV buffer (if any) and\nbecomes \"SvPOKoff\" rather than making a copy. (Used where this scalar is about to be\nset to some other value.) In addition, the \"flags\" parameter gets passed to\nsvunrefflags() when unreffing. \"svforcenormal\" calls this function with flags set to\n0.\n\nThis function is expected to be used to signal to perl that this SV is about to be\nwritten to, and any extra book-keeping needs to be taken care of. Hence, it croaks on\nread-only values.\n\nvoid svforcenormalflags(SV * const sv, const U32 flags)\n\n\"svfree\"\nDecrement an SV's reference count, and if it drops to zero, call \"svclear\" to invoke\ndestructors and free up any memory used by the body; finally, deallocating the SV's head\nitself. Normally called via a wrapper macro \"SvREFCNTdec\".\n\nvoid svfree(SV * const sv)\n\n\"SvGAMAGIC\"\nReturns true if the SV has get magic or overloading. If either is true then the scalar\nis active data, and has the potential to return a new value every time it is accessed.\nHence you must be careful to only read it once per user logical operation and work with\nthat returned value. If neither is true then the scalar's value cannot change unless\nwritten to.\n\nU32 SvGAMAGIC(SV* sv)\n\n\"svgetbackrefs\"\nNOTE: \"svgetbackrefs\" is experimental and may change or be removed without notice.\n\nIf \"sv\" is the target of a weak reference then it returns the back references structure\nassociated with the sv; otherwise return \"NULL\".\n\nWhen returning a non-null result the type of the return is relevant. If it is an AV then\nthe elements of the AV are the weak reference RVs which point at this item. If it is any\nother type then the item itself is the weak reference.\n\nSee also Perlsvaddbackref(), Perlsvdelbackref(), Perlsvkillbackrefs()\n\nSV * svgetbackrefs(SV * const sv)\n\n\"SvGETMAGIC\"\nInvokes \"mgget\" on an SV if it has 'get' magic. For example, this will call \"FETCH\" on\na tied variable. As of 5.37.1, this function is guaranteed to evaluate its argument\nexactly once.\n\nvoid SvGETMAGIC(SV *sv)\n\n\"svgets\"\nGet a line from the filehandle and store it into the SV, optionally appending to the\ncurrently-stored string. If \"append\" is not 0, the line is appended to the SV instead of\noverwriting it. \"append\" should be set to the byte offset that the appended string\nshould start at in the SV (typically, SvCUR(sv) is a suitable choice).\n\nchar * svgets(SV * const sv, PerlIO * const fp, I32 append)\n\n\"SvGROW\"\nExpands the character buffer in the SV so that it has room for the indicated number of\nbytes (remember to reserve space for an extra trailing \"NUL\" character). Calls \"svgrow\"\nto perform the expansion if necessary. Returns a pointer to the character buffer. SV\nmust be of type >= \"SVtPV\". One alternative is to call \"svgrow\" if you are not sure of\nthe type of SV.\n\nYou might mistakenly think that \"len\" is the number of bytes to add to the existing size,\nbut instead it is the total size \"sv\" should be.\n\nchar * SvGROW(SV* sv, STRLEN len)\n\n\"SvIandPOK\"\nReturns a bool indicating whether the SV is both SvPOK() and SvIOK() at the same time.\nEquivalent to \"SvIOK(sv) && SvPOK(sv)\" but more efficient.\n\nU32 SvIandPOK(SV* sv)\n\n\"SvIandPOKoff\"\nUnsets the PV and IV status of an SV in one operation. Equivalent to \"SvIOKoff(sv);\nSvPKoff(v);\" but more efficient.\n\nvoid SvIandPOKoff(SV* sv)\n\n\"SvIandPOKon\"\nTells an SV that is a string and a number in one operation. Equivalent to \"SvIOKon(sv);\nSvPOKon(sv);\" but more efficient.\n\nvoid SvIandPOKon(SV* sv)\n\n\"svinc\"\n\"svincnomg\"\nThese auto-increment the value in the SV, doing string to numeric conversion if\nnecessary. They both handle operator overloading.\n\nThey differ only in that \"svinc\" performs 'get' magic; \"svincnomg\" skips any magic.\n\nvoid svinc(SV * const sv)\n\n\"svinsert\"\nInserts and/or replaces a string at the specified offset/length within the SV. Similar\nto the Perl substr() function, with \"littlelen\" bytes starting at \"little\" replacing\n\"len\" bytes of the string in \"bigstr\" starting at \"offset\". Handles get magic.\n\nvoid svinsert(SV * const bigstr, const STRLEN offset,\nconst STRLEN len, const char * const little,\nconst STRLEN littlelen)\n\n\"svinsertflags\"\nSame as \"svinsert\", but the extra \"flags\" are passed to the \"SvPVforceflags\" that\napplies to \"bigstr\".\n\nvoid svinsertflags(SV * const bigstr, const STRLEN offset,\nconst STRLEN len, const char *little,\nconst STRLEN littlelen, const U32 flags)\n\n\"sv2io\"\nUsing various gambits, try to get an IO from an SV: the IO slot if its a GV; or the\nrecursive result if we're an RV; or the IO slot of the symbol named after the PV if we're\na string.\n\n'Get' magic is ignored on the \"sv\" passed in, but will be called on SvRV(sv) if \"sv\" is\nan RV.\n\nIO * sv2io(SV * const sv)\n\n\"SvIOK\"\nReturns a U32 value indicating whether the SV contains an integer.\n\nU32 SvIOK(SV* sv)\n\n\"SvIOKnotUV\"\nReturns a boolean indicating whether the SV contains a signed integer.\n\nbool SvIOKnotUV(SV* sv)\n\n\"SvIOKoff\"\nUnsets the IV status of an SV.\n\nvoid SvIOKoff(SV* sv)\n\n\"SvIOKon\"\nTells an SV that it is an integer.\n\nvoid SvIOKon(SV* sv)\n\n\"SvIOKonly\"\nTells an SV that it is an integer and disables all other \"OK\" bits.\n\nvoid SvIOKonly(SV* sv)\n\n\"SvIOKonlyUV\"\nTells an SV that it is an unsigned integer and disables all other \"OK\" bits.\n\nvoid SvIOKonlyUV(SV* sv)\n\n\"SvIOKp\"\nReturns a U32 value indicating whether the SV contains an integer. Checks the private\nsetting. Use \"SvIOK\" instead.\n\nU32 SvIOKp(SV* sv)\n\n\"SvIOKUV\"\nReturns a boolean indicating whether the SV contains an integer that must be interpreted\nas unsigned. A non-negative integer whose value is within the range of both an IV and a\nUV may be flagged as either \"SvUOK\" or \"SvIOK\".\n\nbool SvIOKUV(SV* sv)\n\n\"svisa\"\nReturns a boolean indicating whether the SV is blessed into the specified class.\n\nThis does not check for subtypes or method overloading. Use \"svisasv\" to verify an\ninheritance relationship in the same way as the \"isa\" operator by respecting any isa()\nmethod overloading; or \"svderivedfromsv\" to test directly on the actual object type.\n\nint svisa(SV *sv, const char * const name)\n\n\"svisasv\"\nNOTE: \"svisasv\" is experimental and may change or be removed without notice.\n\nReturns a boolean indicating whether the SV is an object reference and is derived from\nthe specified class, respecting any isa() method overloading it may have. Returns false\nif \"sv\" is not a reference to an object, or is not derived from the specified class.\n\nThis is the function used to implement the behaviour of the \"isa\" operator.\n\nDoes not invoke magic on \"sv\".\n\nNot to be confused with the older \"svisa\" function, which does not use an overloaded\nisa() method, nor will check subclassing.\n\nbool svisasv(SV *sv, SV *namesv)\n\n\"SvIsBOOL\"\nReturns true if the SV is one of the special boolean constants (PLsvyes or PLsvno),\nor is a regular SV whose last assignment stored a copy of one.\n\nbool SvIsBOOL(SV* sv)\n\n\"SvIsCOW\"\nReturns a U32 value indicating whether the SV is Copy-On-Write (either shared hash key\nscalars, or full Copy On Write scalars if 5.9.0 is configured for COW).\n\nU32 SvIsCOW(SV* sv)\n\n\"SvIsCOWsharedhash\"\nReturns a boolean indicating whether the SV is Copy-On-Write shared hash key scalar.\n\nbool SvIsCOWsharedhash(SV* sv)\n\n\"svisobject\"\nReturns a boolean indicating whether the SV is an RV pointing to a blessed object. If\nthe SV is not an RV, or if the object is not blessed, then this will return false.\n\nint svisobject(SV *sv)\n\n\"SvIV\"\n\"SvIVnomg\"\n\"SvIVx\"\nThese each coerce the given SV to IV and return it. The returned value in many\ncircumstances will get stored in \"sv\"'s IV slot, but not in all cases. (Use \"svsetiv\"\nto make sure it does).\n\nAs of 5.37.1, all are guaranteed to evaluate \"sv\" only once.\n\n\"SvIVx\" is now identical to \"SvIV\", but prior to 5.37.1, it was the only form guaranteed\nto evaluate \"sv\" only once.\n\n\"SvIVnomg\" is the same as \"SvIV\", but does not perform 'get' magic.\n\nIV SvIV(SV *sv)\n\n\"sv2ivflags\"\nReturn the integer value of an SV, doing any necessary string conversion. If \"flags\" has\nthe \"SVGMAGIC\" bit set, does an mgget() first. Normally used via the SvIV(sv) and\nSvIVx(sv) macros.\n\nIV sv2ivflags(SV * const sv, const I32 flags)\n\n\"SvIVset\"\nSet the value of the IV pointer in sv to val. It is possible to perform the same\nfunction of this macro with an lvalue assignment to \"SvIVX\". With future Perls, however,\nit will be more efficient to use \"SvIVset\" instead of the lvalue assignment to \"SvIVX\".\n\nvoid SvIVset(SV* sv, IV val)\n\n\"SvIVX\"\nReturns the raw value in the SV's IV slot, without checks or conversions. Only use when\nyou are sure \"SvIOK\" is true. See also \"SvIV\".\n\nIV SvIVX(SV* sv)\n\n\"SvLEN\"\nReturns the size of the string buffer in the SV, not including any part attributable to\n\"SvOOK\". See \"SvCUR\".\n\nSTRLEN SvLEN(SV* sv)\n\n\"svlen\"\nReturns the length of the string in the SV. Handles magic and type coercion and sets the\nUTF8 flag appropriately. See also \"SvCUR\", which gives raw access to the \"xpvcur\" slot.\n\nSTRLEN svlen(SV * const sv)\n\n\"SvLENset\"\nSet the size of the string buffer for the SV. See \"SvLEN\".\n\nvoid SvLENset(SV* sv, STRLEN len)\n\n\"svlenutf8\"\n\"svlenutf8nomg\"\nThese return the number of characters in the string in an SV, counting wide UTF-8 bytes\nas a single character. Both handle type coercion. They differ only in that\n\"svlenutf8\" performs 'get' magic; \"svlenutf8nomg\" skips any magic.\n\nSTRLEN svlenutf8(SV * const sv)\n\n\"SvLOCK\"\nArranges for a mutual exclusion lock to be obtained on \"sv\" if a suitable module has been\nloaded.\n\nvoid SvLOCK(SV* sv)\n\n\"svmagic\"\nAdds magic to an SV. First upgrades \"sv\" to type \"SVtPVMG\" if necessary, then adds a\nnew magic item of type \"how\" to the head of the magic list.\n\nSee \"svmagicext\" (which \"svmagic\" now calls) for a description of the handling of the\n\"name\" and \"namlen\" arguments.\n\nYou need to use \"svmagicext\" to add magic to \"SvREADONLY\" SVs and also to add more than\none instance of the same \"how\".\n\nvoid svmagic(SV * const sv, SV * const obj, const int how,\nconst char * const name, const I32 namlen)\n\n\"svmagicext\"\nAdds magic to an SV, upgrading it if necessary. Applies the supplied \"vtable\" and\nreturns a pointer to the magic added.\n\nNote that \"svmagicext\" will allow things that \"svmagic\" will not. In particular, you\ncan add magic to \"SvREADONLY\" SVs, and add more than one instance of the same \"how\".\n\nIf \"namlen\" is greater than zero then a \"savepvn\" copy of \"name\" is stored, if \"namlen\"\nis zero then \"name\" is stored as-is and - as another special case - if \"(name && namlen\n== HEfSVKEY)\" then \"name\" is assumed to contain an SV* and is stored as-is with its\n\"REFCNT\" incremented.\n\n(This is now used as a subroutine by \"svmagic\".)\n\nMAGIC * svmagicext(SV * const sv, SV * const obj, const int how,\nconst MGVTBL * const vtbl,\nconst char * const name, const I32 namlen)\n\n\"SvMAGICset\"\nSet the value of the MAGIC pointer in \"sv\" to val. See \"SvIVset\".\n\nvoid SvMAGICset(SV* sv, MAGIC* val)\n\n\"sv2mortal\"\nMarks an existing SV as mortal. The SV will be destroyed \"soon\", either by an explicit\ncall to \"FREETMPS\", or by an implicit call at places such as statement boundaries.\nSvTEMP() is turned on which means that the SV's string buffer can be \"stolen\" if this SV\nis copied. See also \"svnewmortal\" and \"svmortalcopy\".\n\nSV * sv2mortal(SV * const sv)\n\n\"svmortalcopy\"\nCreates a new SV which is a copy of the original SV (using \"svsetsv\"). The new SV is\nmarked as mortal. It will be destroyed \"soon\", either by an explicit call to \"FREETMPS\",\nor by an implicit call at places such as statement boundaries. See also \"svnewmortal\"\nand \"sv2mortal\".\n\nSV * svmortalcopy(SV * const oldsv)\n\n\"svmortalcopyflags\"\nLike \"svmortalcopy\", but the extra \"flags\" are passed to the \"svsetsvflags\".\n\nSV * svmortalcopyflags(SV * const oldsv, U32 flags)\n\n\"svnewmortal\"\nCreates a new null SV which is mortal. The reference count of the SV is set to 1. It\nwill be destroyed \"soon\", either by an explicit call to \"FREETMPS\", or by an implicit\ncall at places such as statement boundaries. See also \"svmortalcopy\" and \"sv2mortal\".\n\nSV * svnewmortal()\n\n\"SvNIOK\"\nReturns a U32 value indicating whether the SV contains a number, integer or double.\n\nU32 SvNIOK(SV* sv)\n\n\"SvNIOKoff\"\nUnsets the NV/IV status of an SV.\n\nvoid SvNIOKoff(SV* sv)\n\n\"SvNIOKp\"\nReturns a U32 value indicating whether the SV contains a number, integer or double.\nChecks the private setting. Use \"SvNIOK\" instead.\n\nU32 SvNIOKp(SV* sv)\n\n\"SvNOK\"\nReturns a U32 value indicating whether the SV contains a double.\n\nU32 SvNOK(SV* sv)\n\n\"SvNOKoff\"\nUnsets the NV status of an SV.\n\nvoid SvNOKoff(SV* sv)\n\n\"SvNOKon\"\nTells an SV that it is a double.\n\nvoid SvNOKon(SV* sv)\n\n\"SvNOKonly\"\nTells an SV that it is a double and disables all other OK bits.\n\nvoid SvNOKonly(SV* sv)\n\n\"SvNOKp\"\nReturns a U32 value indicating whether the SV contains a double. Checks the private\nsetting. Use \"SvNOK\" instead.\n\nU32 SvNOKp(SV* sv)\n\n\"svnolocking\"\n\"DEPRECATED!\" It is planned to remove \"svnolocking\" from a future release of Perl. Do\nnot use it for new code; remove it from existing code.\n\nDummy routine which \"locks\" an SV when there is no locking module present. Exists to\navoid test for a \"NULL\" function pointer and because it could potentially warn under some\nlevel of strict-ness.\n\n\"Superseded\" by svnosharing().\n\nvoid svnolocking(SV *sv)\n\n\"svnounlocking\"\n\"DEPRECATED!\" It is planned to remove \"svnounlocking\" from a future release of Perl.\nDo not use it for new code; remove it from existing code.\n\nDummy routine which \"unlocks\" an SV when there is no locking module present. Exists to\navoid test for a \"NULL\" function pointer and because it could potentially warn under some\nlevel of strict-ness.\n\n\"Superseded\" by svnosharing().\n\nvoid svnounlocking(SV *sv)\n\n\"svnumeq\"\nA convenient shortcut for calling \"svnumeqflags\" with the \"SVGMAGIC\" flag. This\nfunction basically behaves like the Perl code \"$sv1 == $sv2\".\n\nbool svnumeq(SV *sv1, SV *sv2)\n\n\"svnumeqflags\"\nReturns a boolean indicating whether the numbers in the two SVs are identical. If the\nflags argument has the \"SVGMAGIC\" bit set, it handles get-magic too. Will coerce its\nargs to numbers if necessary. Treats \"NULL\" as undef.\n\nIf flags does not have the \"SVSKIPOVERLOAD\" bit set, an attempt to use \"==\" overloading\nwill be made. If such overloading does not exist or the flag is set, then regular\nnumerical comparison will be used instead.\n\nbool svnumeqflags(SV *sv1, SV *sv2, const U32 flags)\n\n\"SvNV\"\n\"SvNVnomg\"\n\"SvNVx\"\nThese each coerce the given SV to NV and return it. The returned value in many\ncircumstances will get stored in \"sv\"'s NV slot, but not in all cases. (Use \"svsetnv\"\nto make sure it does).\n\nAs of 5.37.1, all are guaranteed to evaluate \"sv\" only once.\n\n\"SvNVx\" is now identical to \"SvNV\", but prior to 5.37.1, it was the only form guaranteed\nto evaluate \"sv\" only once.\n\n\"SvNVnomg\" is the same as \"SvNV\", but does not perform 'get' magic.\n\nNV SvNV(SV *sv)\n\n\"sv2nvflags\"\nReturn the num value of an SV, doing any necessary string or integer conversion. If\n\"flags\" has the \"SVGMAGIC\" bit set, does an mgget() first. Normally used via the\nSvNV(sv) and SvNVx(sv) macros.\n\nNV sv2nvflags(SV * const sv, const I32 flags)\n\n\"SvNVset\"\nSet the value of the NV pointer in \"sv\" to val. See \"SvIVset\".\n\nvoid SvNVset(SV* sv, NV val)\n\n\"SvNVX\"\nReturns the raw value in the SV's NV slot, without checks or conversions. Only use when\nyou are sure \"SvNOK\" is true. See also \"SvNV\".\n\nNV SvNVX(SV* sv)\n\n\"SvOK\"\nReturns a U32 value indicating whether the value is defined. This is only meaningful for\nscalars.\n\nU32 SvOK(SV* sv)\n\n\"SvOOK\"\nReturns a U32 indicating whether the pointer to the string buffer is offset. This hack\nis used internally to speed up removal of characters from the beginning of a \"SvPV\".\nWhen \"SvOOK\" is true, then the start of the allocated string buffer is actually\nSvOOKoffset() bytes before \"SvPVX\". This offset used to be stored in \"SvIVX\", but is\nnow stored within the spare part of the buffer.\n\nU32 SvOOK(SV* sv)\n\n\"SvOOKoff\"\nRemove any string offset.\n\nvoid SvOOKoff(SV * sv)\n\n\"SvOOKoffset\"\nReads into \"len\" the offset from \"SvPVX\" back to the true start of the allocated buffer,\nwhich will be non-zero if \"svchop\" has been used to efficiently remove characters from\nstart of the buffer. Implemented as a macro, which takes the address of \"len\", which\nmust be of type \"STRLEN\". Evaluates \"sv\" more than once. Sets \"len\" to 0 if SvOOK(sv)\nis false.\n\nvoid SvOOKoffset(SV*sv, STRLEN len)\n\n\"SvPOK\"\nReturns a U32 value indicating whether the SV contains a character string.\n\nU32 SvPOK(SV* sv)\n\n\"SvPOKoff\"\nUnsets the PV status of an SV.\n\nvoid SvPOKoff(SV* sv)\n\n\"SvPOKon\"\nTells an SV that it is a string.\n\nvoid SvPOKon(SV* sv)\n\n\"SvPOKonly\"\nTells an SV that it is a string and disables all other \"OK\" bits. Will also turn off the\nUTF-8 status.\n\nvoid SvPOKonly(SV* sv)\n\n\"SvPOKonlyUTF8\"\nTells an SV that it is a string and disables all other \"OK\" bits, and leaves the UTF-8\nstatus as it was.\n\nvoid SvPOKonlyUTF8(SV* sv)\n\n\"SvPOKp\"\nReturns a U32 value indicating whether the SV contains a character string. Checks the\nprivate setting. Use \"SvPOK\" instead.\n\nU32 SvPOKp(SV* sv)\n\n\"svposb2u\"\nConverts the value pointed to by \"offsetp\" from a count of bytes from the start of the\nstring, to a count of the equivalent number of UTF-8 chars. Handles magic and type\ncoercion.\n\nUse \"svposb2uflags\" in preference, which correctly handles strings longer than 2Gb.\n\nvoid svposb2u(SV * const sv, I32 * const offsetp)\n\n\"svposb2uflags\"\nConverts \"offset\" from a count of bytes from the start of the string, to a count of the\nequivalent number of UTF-8 chars. Handles type coercion. \"flags\" is passed to\n\"SvPVflags\", and usually should be \"SVGMAGIC|SVCONSTRETURN\" to handle magic.\n\nSTRLEN svposb2uflags(SV * const sv, STRLEN const offset,\nU32 flags)\n\n\"svposu2b\"\nConverts the value pointed to by \"offsetp\" from a count of UTF-8 chars from the start of\nthe string, to a count of the equivalent number of bytes; if \"lenp\" is non-zero, it does\nthe same to \"lenp\", but this time starting from the offset, rather than from the start of\nthe string. Handles magic and type coercion.\n\nUse \"svposu2bflags\" in preference, which correctly handles strings longer than 2Gb.\n\nvoid svposu2b(SV * const sv, I32 * const offsetp,\nI32 * const lenp)\n\n\"svposu2bflags\"\nConverts the offset from a count of UTF-8 chars from the start of the string, to a count\nof the equivalent number of bytes; if \"lenp\" is non-zero, it does the same to \"lenp\", but\nthis time starting from \"offset\", rather than from the start of the string. Handles type\ncoercion. \"flags\" is passed to \"SvPVflags\", and usually should be\n\"SVGMAGIC|SVCONSTRETURN\" to handle magic.\n\nSTRLEN svposu2bflags(SV * const sv, STRLEN uoffset,\nSTRLEN * const lenp, U32 flags)\n\n\"SvPV\"\n\"SvPVconst\"\n\"SvPVflags\"\n\"SvPVflagsconst\"\n\"SvPVflagsmutable\"\n\"SvPVmutable\"\n\"SvPVnolen\"\n\"SvPVnolenconst\"\n\"SvPVnomg\"\n\"SvPVnomgconst\"\n\"SvPVnomgconstnolen\"\n\"SvPVnomgnolen\"\n\"SvPVbyte\"\n\"SvPVbytenolen\"\n\"SvPVbytenomg\"\n\"SvPVbyteornull\"\n\"SvPVbyteornullnomg\"\n\"SvPVbytex\"\n\"SvPVbytexnolen\"\n\"SvPVutf8\"\n\"SvPVutf8nolen\"\n\"SvPVutf8nomg\"\n\"SvPVutf8ornull\"\n\"SvPVutf8ornullnomg\"\n\"SvPVutf8x\"\n\"SvPVx\"\n\"SvPVxconst\"\n\"SvPVxnolen\"\n\"SvPVxnolenconst\"\nThese each return a pointer to the string in \"sv\", or a stringified form of \"sv\" if it\ndoes not contain a string. The SV may cache the stringified version becoming \"SvPOK\".\n\nThis is a very basic and common operation, so there are lots of slightly different\nversions of it.\n\nNote that there is no guarantee that the return value of SvPV(sv), for example, is equal\nto SvPVX(sv), or that SvPVX(sv) contains valid data, or that successive calls to SvPV(sv)\n(or another of these forms) will return the same pointer value each time. This is due to\nthe way that things like overloading and Copy-On-Write are handled. In these cases, the\nreturn value may point to a temporary buffer or similar. If you absolutely need the\n\"SvPVX\" field to be valid (for example, if you intend to write to it), then see\n\"SvPVforce\".\n\nThe differences between the forms are:\n\nThe forms with neither \"byte\" nor \"utf8\" in their names (e.g., \"SvPV\" or \"SvPVnolen\")\ncan expose the SV's internal string buffer. If that buffer consists entirely of bytes\n0-255 and includes any bytes above 127, then you MUST consult \"SvUTF8\" to determine the\nactual code points the string is meant to contain. Generally speaking, it is probably\nsafer to prefer \"SvPVbyte\", \"SvPVutf8\", and the like. See \"How do I pass a Perl string to\na C library?\" in perlguts for more details.\n\nThe forms with \"flags\" in their names allow you to use the \"flags\" parameter to specify\nto process 'get' magic (by setting the \"SVGMAGIC\" flag) or to skip 'get' magic (by\nclearing it). The other forms process 'get' magic, except for the ones with \"nomg\" in\ntheir names, which skip 'get' magic.\n\nThe forms that take a \"len\" parameter will set that variable to the byte length of the\nresultant string (these are macros, so don't use &len).\n\nThe forms with \"nolen\" in their names indicate they don't have a \"len\" parameter. They\nshould be used only when it is known that the PV is a C string, terminated by a NUL byte,\nand without intermediate NUL characters; or when you don't care about its length.\n\nThe forms with \"const\" in their names return \"const char *\" so that the compiler will\nhopefully complain if you were to try to modify the contents of the string (unless you\ncast away const yourself).\n\nThe other forms return a mutable pointer so that the string is modifiable by the caller;\nthis is emphasized for the ones with \"mutable\" in their names.\n\nAs of 5.38, all forms are guaranteed to evaluate \"sv\" exactly once. For earlier Perls,\nuse a form whose name ends with \"x\" for single evaluation.\n\n\"SvPVutf8\" is like \"SvPV\", but converts \"sv\" to UTF-8 first if not already UTF-8.\nSimilarly, the other forms with \"utf8\" in their names correspond to their respective\nforms without.\n\n\"SvPVutf8ornull\" and \"SvPVutf8ornullnomg\" don't have corresponding non-\"utf8\" forms.\nInstead they are like \"SvPVutf8nomg\", but when \"sv\" is undef, they return \"NULL\".\n\n\"SvPVbyte\" is like \"SvPV\", but converts \"sv\" to byte representation first if currently\nencoded as UTF-8. If \"sv\" cannot be downgraded from UTF-8, it croaks. Similarly, the\nother forms with \"byte\" in their names correspond to their respective forms without.\n\n\"SvPVbyteornull\" doesn't have a corresponding non-\"byte\" form. Instead it is like\n\"SvPVbyte\", but when \"sv\" is undef, it returns \"NULL\".\n\nchar* SvPV (SV* sv, STRLEN len)\nconst char* SvPVconst (SV* sv, STRLEN len)\nchar* SvPVflags (SV* sv, STRLEN len, U32 flags)\nconst char* SvPVflagsconst (SV* sv, STRLEN len, U32 flags)\nchar* SvPVflagsmutable (SV* sv, STRLEN len, U32 flags)\nchar* SvPVmutable (SV* sv, STRLEN len)\nchar* SvPVnolen (SV* sv)\nconst char* SvPVnolenconst (SV* sv)\nchar* SvPVnomg (SV* sv, STRLEN len)\nconst char* SvPVnomgconst (SV* sv, STRLEN len)\nconst char* SvPVnomgconstnolen(SV* sv)\nchar* SvPVnomgnolen (SV* sv)\nchar* SvPVbyte (SV* sv, STRLEN len)\nchar* SvPVbytenolen (SV* sv)\nchar* SvPVbytenomg (SV* sv, STRLEN len)\nchar* SvPVbyteornull (SV* sv, STRLEN len)\nchar* SvPVbyteornullnomg(SV* sv, STRLEN len)\nchar* SvPVbytex (SV* sv, STRLEN len)\nchar* SvPVbytexnolen (SV* sv)\nchar* SvPVutf8 (SV* sv, STRLEN len)\nchar* SvPVutf8nolen (SV* sv)\nchar* SvPVutf8nomg (SV* sv, STRLEN len)\nchar* SvPVutf8ornull (SV* sv, STRLEN len)\nchar* SvPVutf8ornullnomg(SV* sv, STRLEN len)\nchar* SvPVutf8x (SV* sv, STRLEN len)\nchar* SvPVx (SV* sv, STRLEN len)\nconst char* SvPVxconst (SV* sv, STRLEN len)\nchar* SvPVxnolen (SV* sv)\nconst char* SvPVxnolenconst (SV* sv)\n\n\"sv2pv\"\n\"sv2pvflags\"\nThese implement the various forms of the \"\"SvPV\"\" in perlapi macros. The macros are the\npreferred interface.\n\nThese return a pointer to the string value of an SV (coercing it to a string if\nnecessary), and set *lp to its length in bytes.\n\nThe forms differ in that plain \"sv2pvbyte\" always processes 'get' magic; and\n\"sv2pvbyteflags\" processes 'get' magic if and only if \"flags\" contains \"SVGMAGIC\".\n\nchar * sv2pv (SV *sv, STRLEN *lp)\nchar * sv2pvflags(SV * const sv, STRLEN * const lp,\nconst U32 flags)\n\n\"sv2pvbyte\"\n\"sv2pvbyteflags\"\nThese implement the various forms of the \"\"SvPVbyte\"\" in perlapi macros. The macros are\nthe preferred interface.\n\nThese return a pointer to the byte-encoded representation of the SV, and set *lp to its\nlength. If the SV is marked as being encoded as UTF-8, it will be downgraded, if\npossible, to a byte string. If the SV cannot be downgraded, they croak.\n\nThe forms differ in that plain \"sv2pvbyte\" always processes 'get' magic; and\n\"sv2pvbyteflags\" processes 'get' magic if and only if \"flags\" contains \"SVGMAGIC\".\n\nchar * sv2pvbyte (SV *sv, STRLEN * const lp)\nchar * sv2pvbyteflags(SV *sv, STRLEN * const lp,\nconst U32 flags)\n\n\"SvPVCLEAR\"\nEnsures that sv is a SVtPV and that its SvCUR is 0, and that it is properly null\nterminated. Equivalent to svsetpvs(\"\"), but more efficient.\n\nchar * SvPVCLEAR(SV* sv)\n\n\"SvPVCLEARFRESH\"\nLike SvPVCLEAR, but optimized for newly-minted SVtPV/PVIV/PVNV/PVMG that already have a\nPV buffer allocated, but no SvTHINKFIRST.\n\nchar * SvPVCLEARFRESH(SV* sv)\n\n\"SvPVforce\"\n\"SvPVforceflags\"\n\"SvPVforceflagsmutable\"\n\"SvPVforceflagsnolen\"\n\"SvPVforcemutable\"\n\"SvPVforcenolen\"\n\"SvPVforcenomg\"\n\"SvPVforcenomgnolen\"\n\"SvPVbyteforce\"\n\"SvPVbytexforce\"\n\"SvPVutf8force\"\n\"SvPVutf8xforce\"\n\"SvPVxforce\"\nThese are like \"SvPV\", returning the string in the SV, but will force the SV into\ncontaining a string (\"SvPOK\"), and only a string (\"SvPOKonly\"), by hook or by crook.\nYou need to use one of these \"force\" routines if you are going to update the \"SvPVX\"\ndirectly.\n\nNote that coercing an arbitrary scalar into a plain PV will potentially strip useful data\nfrom it. For example if the SV was \"SvROK\", then the referent will have its reference\ncount decremented, and the SV itself may be converted to an \"SvPOK\" scalar with a string\nbuffer containing a value such as \"ARRAY(0x1234)\".\n\nThe differences between the forms are:\n\nThe forms with \"flags\" in their names allow you to use the \"flags\" parameter to specify\nto perform 'get' magic (by setting the \"SVGMAGIC\" flag) or to skip 'get' magic (by\nclearing it). The other forms do perform 'get' magic, except for the ones with \"nomg\" in\ntheir names, which skip 'get' magic.\n\nThe forms that take a \"len\" parameter will set that variable to the byte length of the\nresultant string (these are macros, so don't use &len).\n\nThe forms with \"nolen\" in their names indicate they don't have a \"len\" parameter. They\nshould be used only when it is known that the PV is a C string, terminated by a NUL byte,\nand without intermediate NUL characters; or when you don't care about its length.\n\nThe forms with \"mutable\" in their names are effectively the same as those without, but\nthe name emphasizes that the string is modifiable by the caller, which it is in all the\nforms.\n\n\"SvPVutf8force\" is like \"SvPVforce\", but converts \"sv\" to UTF-8 first if not already\nUTF-8.\n\n\"SvPVutf8xforce\" is like \"SvPVutf8force\", but guarantees to evaluate \"sv\" only once;\nuse the more efficient \"SvPVutf8force\" otherwise.\n\n\"SvPVbyteforce\" is like \"SvPVforce\", but converts \"sv\" to byte representation first if\ncurrently encoded as UTF-8. If the SV cannot be downgraded from UTF-8, this croaks.\n\n\"SvPVbytexforce\" is like \"SvPVbyteforce\", but guarantees to evaluate \"sv\" only once;\nuse the more efficient \"SvPVbyteforce\" otherwise.\n\nchar* SvPVforce (SV* sv, STRLEN len)\nchar* SvPVforceflags (SV * sv, STRLEN len, U32 flags)\nchar* SvPVforceflagsmutable(SV * sv, STRLEN len, U32 flags)\nchar* SvPVforceflagsnolen (SV * sv, U32 flags)\nchar* SvPVforcemutable (SV * sv, STRLEN len)\nchar* SvPVforcenolen (SV* sv)\nchar* SvPVforcenomg (SV* sv, STRLEN len)\nchar* SvPVforcenomgnolen (SV * sv)\nchar* SvPVbyteforce (SV * sv, STRLEN len)\nchar* SvPVbytexforce (SV * sv, STRLEN len)\nchar* SvPVutf8force (SV * sv, STRLEN len)\nchar* SvPVutf8xforce (SV * sv, STRLEN len)\nchar* SvPVxforce (SV* sv, STRLEN len)\n\n\"SvPVfree\"\nFrees the PV buffer in \"sv\", leaving things in a precarious state, so should only be used\nas part of a larger operation\n\nvoid SvPVfree(SV * sv)\n\n\"svpvnforceflags\"\nGet a sensible string out of the SV somehow. If \"flags\" has the \"SVGMAGIC\" bit set,\nwill \"mgget\" on \"sv\" if appropriate, else not. \"svpvnforce\" and \"svpvnforcenomg\"\nare implemented in terms of this function. You normally want to use the various wrapper\nmacros instead: see \"SvPVforce\" and \"SvPVforcenomg\".\n\nchar * svpvnforceflags(SV * const sv, STRLEN * const lp,\nconst U32 flags)\n\n\"SvPVrenew\"\nLow level micro optimization of \"SvGROW\". It is generally better to use \"SvGROW\"\ninstead. This is because \"SvPVrenew\" ignores potential issues that \"SvGROW\" handles.\n\"sv\" needs to have a real \"PV\" that is unencumbered by things like COW. Using\n\"SVCHECKTHINKFIRST\" or \"SVCHECKTHINKFIRSTCOWDROP\" before calling this should clean\nit up, but why not just use \"SvGROW\" if you're not sure about the provenance?\n\nvoid SvPVrenew(SV* sv, STRLEN len)\n\n\"SvPVset\"\nThis is probably not what you want to use, you probably wanted \"svusepvnflags\" or\n\"svsetpvn\" or \"svsetpvs\".\n\nSet the value of the PV pointer in \"sv\" to the Perl allocated \"NUL\"-terminated string\n\"val\". See also \"SvIVset\".\n\nRemember to free the previous PV buffer. There are many things to check. Beware that the\nexisting pointer may be involved in copy-on-write or other mischief, so do SvOOKoff(sv)\nand use \"svforcenormal\" or \"SvPVforce\" (or check the \"SvIsCOW\" flag) first to make\nsure this modification is safe. Then finally, if it is not a COW, call \"SvPVfree\" to\nfree the previous PV buffer.\n\nvoid SvPVset(SV* sv, char* val)\n\n\"SvPVshrinktocur\"\nTrim any trailing unused memory in the PV of \"sv\", which needs to have a real \"PV\" that\nis unencumbered by things like COW. Think first before using this functionality. Is the\nspace saving really worth giving up COW? Will the needed size of \"sv\" stay the same?\n\nIf the answers are both yes, then use \"\"SVCHECKTHINKFIRST\"\" or\n\"\"SVCHECKTHINKFIRSTCOWDROP\"\" before calling this.\n\nvoid SvPVshrinktocur(SV* sv)\n\n\"sv2pvutf8\"\n\"sv2pvutf8flags\"\nThese implement the various forms of the \"\"SvPVutf8\"\" in perlapi macros. The macros are\nthe preferred interface.\n\nThese return a pointer to the UTF-8-encoded representation of the SV, and set *lp to its\nlength in bytes. They may cause the SV to be upgraded to UTF-8 as a side-effect.\n\nThe forms differ in that plain \"sv2pvutf8\" always processes 'get' magic; and\n\"sv2pvutf8flags\" processes 'get' magic if and only if \"flags\" contains \"SVGMAGIC\".\n\nchar * sv2pvutf8 (SV *sv, STRLEN * const lp)\nchar * sv2pvutf8flags(SV *sv, STRLEN * const lp,\nconst U32 flags)\n\n\"SvPVX\"\n\"SvPVXconst\"\n\"SvPVXmutable\"\n\"SvPVXx\"\nThese return a pointer to the physical string in the SV. The SV must contain a string.\nPrior to 5.9.3 it is not safe to execute these unless the SV's type >= \"SVtPV\".\n\nThese are also used to store the name of an autoloaded subroutine in an XS AUTOLOAD\nroutine. See \"Autoloading with XSUBs\" in perlguts.\n\n\"SvPVXx\" is identical to \"SvPVX\".\n\n\"SvPVXmutable\" is merely a synonym for \"SvPVX\", but its name emphasizes that the string\nis modifiable by the caller.\n\n\"SvPVXconst\" differs in that the return value has been cast so that the compiler will\ncomplain if you were to try to modify the contents of the string, (unless you cast away\nconst yourself).\n\nchar* SvPVX (SV* sv)\nconst char* SvPVXconst (SV* sv)\nchar* SvPVXmutable(SV* sv)\nchar* SvPVXx (SV* sv)\n\n\"SvPVXtrue\"\nReturns a boolean as to whether or not \"sv\" contains a PV that is considered TRUE. FALSE\nis returned if \"sv\" doesn't contain a PV, or if the PV it does contain is zero length, or\nconsists of just the single character '0'. Every other PV value is considered TRUE.\n\nAs of Perl v5.37.1, \"sv\" is evaluated exactly once; in earlier releases, it could be\nevaluated more than once.\n\nbool SvPVXtrue(SV *sv)\n\n\"SvREADONLY\"\nReturns true if the argument is readonly, otherwise returns false. Exposed to perl code\nvia Internals::SvREADONLY().\n\nU32 SvREADONLY(SV* sv)\n\n\"SvREADONLYoff\"\nMark an object as not-readonly. Exactly what this mean depends on the object type.\nExposed to perl code via Internals::SvREADONLY().\n\nU32 SvREADONLYoff(SV* sv)\n\n\"SvREADONLYon\"\nMark an object as readonly. Exactly what this means depends on the object type. Exposed\nto perl code via Internals::SvREADONLY().\n\nU32 SvREADONLYon(SV* sv)\n\n\"svref\"\nReturns a SV describing what the SV passed in is a reference to.\n\ndst can be a SV to be set to the description or NULL, in which case a mortal SV is\nreturned.\n\nIf ob is true and the SV is blessed, the description is the class name, otherwise it is\nthe type of the SV, \"SCALAR\", \"ARRAY\" etc.\n\nSV * svref(SV *dst, const SV * const sv, const int ob)\n\n\"SvREFCNT\"\nReturns the value of the object's reference count. Exposed to perl code via\nInternals::SvREFCNT().\n\nU32 SvREFCNT(SV* sv)\n\n\"SvREFCNTdec\"\n\"SvREFCNTdecsetNULL\"\n\"SvREFCNTdecretNULL\"\n\"SvREFCNTdecNN\"\nThese decrement the reference count of the given SV.\n\n\"SvREFCNTdecNN\" may only be used when \"sv\" is known to not be \"NULL\".\n\nThe function SvREFCNTdecretNULL() is identical to the SvREFCNTdec() except it returns\na NULL \"SV *\". It is used by SvREFCNTdecsetNULL() which is a macro which will, when\npassed a non-NULL argument, decrement the reference count of its argument and then set it\nto NULL. You can replace code of the following form:\n\nif (sv) {\nSvREFCNTdecNN(sv);\nsv = NULL;\n}\n\nwith\n\nSvREFCNTdecsetNULL(sv);\n\nvoid SvREFCNTdec (SV *sv)\nvoid SvREFCNTdecsetNULL(SV *sv)\nSV * SvREFCNTdecretNULL(SV *sv)\nvoid SvREFCNTdecNN (SV *sv)\n\n\"SvREFCNTinc\"\n\"SvREFCNTincNN\"\n\"SvREFCNTincsimple\"\n\"SvREFCNTincsimpleNN\"\n\"SvREFCNTincsimplevoid\"\n\"SvREFCNTincsimplevoidNN\"\n\"SvREFCNTincvoid\"\n\"SvREFCNTincvoidNN\"\nThese all increment the reference count of the given SV. The ones without \"void\" in\ntheir names return the SV.\n\n\"SvREFCNTinc\" is the base operation; the rest are optimizations if various input\nconstraints are known to be true; hence, all can be replaced with \"SvREFCNTinc\".\n\n\"SvREFCNTincNN\" can only be used if you know \"sv\" is not \"NULL\". Since we don't have\nto check the NULLness, it's faster and smaller.\n\n\"SvREFCNTincvoid\" can only be used if you don't need the return value. The macro\ndoesn't need to return a meaningful value.\n\n\"SvREFCNTincvoidNN\" can only be used if you both don't need the return value, and you\nknow that \"sv\" is not \"NULL\". The macro doesn't need to return a meaningful value, or\ncheck for NULLness, so it's smaller and faster.\n\n\"SvREFCNTincsimple\" can only be used with expressions without side effects. Since we\ndon't have to store a temporary value, it's faster.\n\n\"SvREFCNTincsimpleNN\" can only be used with expressions without side effects and you\nknow \"sv\" is not \"NULL\". Since we don't have to store a temporary value, nor check for\nNULLness, it's faster and smaller.\n\n\"SvREFCNTincsimplevoid\" can only be used with expressions without side effects and you\ndon't need the return value.\n\n\"SvREFCNTincsimplevoidNN\" can only be used with expressions without side effects, you\ndon't need the return value, and you know \"sv\" is not \"NULL\".\n\nSV * SvREFCNTinc (SV *sv)\nSV * SvREFCNTincNN (SV *sv)\nSV* SvREFCNTincsimple (SV* sv)\nSV* SvREFCNTincsimpleNN (SV* sv)\nvoid SvREFCNTincsimplevoid (SV* sv)\nvoid SvREFCNTincsimplevoidNN(SV* sv)\nvoid SvREFCNTincvoid (SV *sv)\nvoid SvREFCNTincvoidNN (SV* sv)\n\n\"svreftype\"\nReturns a string describing what the SV is a reference to.\n\nIf ob is true and the SV is blessed, the string is the class name, otherwise it is the\ntype of the SV, \"SCALAR\", \"ARRAY\" etc.\n\nconst char * svreftype(const SV * const sv, const int ob)\n\n\"svreplace\"\nMake the first argument a copy of the second, then delete the original. The target SV\nphysically takes over ownership of the body of the source SV and inherits its flags;\nhowever, the target keeps any magic it owns, and any magic in the source is discarded.\nNote that this is a rather specialist SV copying operation; most of the time you'll want\nto use \"svsetsv\" or one of its many macro front-ends.\n\nvoid svreplace(SV * const sv, SV * const nsv)\n\n\"svreportused\"\nDump the contents of all SVs not yet freed (debugging aid).\n\nvoid svreportused()\n\n\"svreset\"\nUnderlying implementation for the \"reset\" Perl function. Note that the perl-level\nfunction is vaguely deprecated.\n\nvoid svreset(const char *s, HV * const stash)\n\n\"SvROK\"\nTests if the SV is an RV.\n\nU32 SvROK(SV* sv)\n\n\"SvROKoff\"\nUnsets the RV status of an SV.\n\nvoid SvROKoff(SV* sv)\n\n\"SvROKon\"\nTells an SV that it is an RV.\n\nvoid SvROKon(SV* sv)\n\n\"SvRV\"\nDereferences an RV to return the SV.\n\nSV* SvRV(SV* sv)\n\n\"SvRVset\"\nSet the value of the RV pointer in \"sv\" to val. See \"SvIVset\".\n\nvoid SvRVset(SV* sv, SV* val)\n\n\"svrvunweaken\"\nUnweaken a reference: Clear the \"SvWEAKREF\" flag on this RV; remove the backreference to\nthis RV from the array of backreferences associated with the target SV, increment the\nrefcount of the target. Silently ignores \"undef\" and warns on non-weak references.\n\nSV * svrvunweaken(SV * const sv)\n\n\"svrvweaken\"\nWeaken a reference: set the \"SvWEAKREF\" flag on this RV; give the referred-to SV\n\"PERLMAGICbackref\" magic if it hasn't already; and push a back-reference to this RV\nonto the array of backreferences associated with that magic. If the RV is magical, set\nmagic will be called after the RV is cleared. Silently ignores \"undef\" and warns on\nalready-weak references.\n\nSV * svrvweaken(SV * const sv)\n\n\"svsetbool\"\n\"svsetboolmg\"\nThese set an SV to a true or false boolean value, upgrading first if necessary.\n\nThey differ only in that \"svsetboolmg\" handles 'set' magic; \"svsetbool\" does not.\n\nvoid svsetbool(SV *sv, bool b)\n\n\"svsetbool\"\nEquivalent to \"svsetsv(sv, boolval ? &Plsvyes : &PLsvno)\", but may be made more\nefficient in the future. Doesn't handle set magic.\n\nThe perl equivalent is \"$sv = !!$expr;\".\n\nIntroduced in perl 5.35.11.\n\nvoid svsetbool(SV *sv, const bool boolval)\n\n\"svsetfalse\"\nEquivalent to \"svsetsv(sv, &PLsvno)\", but may be made more efficient in the future.\nDoesn't handle set magic.\n\nThe perl equivalent is \"$sv = !1;\".\n\nIntroduced in perl 5.35.11.\n\nvoid svsetfalse(SV *sv)\n\n\"svsetiv\"\n\"svsetivmg\"\nThese copy an integer into the given SV, upgrading first if necessary.\n\nThey differ only in that \"svsetivmg\" handles 'set' magic; \"svsetiv\" does not.\n\nvoid svsetiv (SV * const sv, const IV num)\nvoid svsetivmg(SV * const sv, const IV i)\n\n\"SvSETMAGIC\"\nInvokes \"mgset\" on an SV if it has 'set' magic. This is necessary after modifying a\nscalar, in case it is a magical variable like $| or a tied variable (it calls \"STORE\").\nThis macro evaluates its argument more than once.\n\nvoid SvSETMAGIC(SV* sv)\n\n\"SvSetMagicSV\"\n\"SvSetMagicSVnosteal\"\n\"SvSetSV\"\n\"SvSetSVnosteal\"\nif \"dsv\" is the same as \"ssv\", these do nothing. Otherwise they all call some form of\n\"svsetsv\". They may evaluate their arguments more than once.\n\nThe only differences are:\n\n\"SvSetMagicSV\" and \"SvSetMagicSVnosteal\" perform any required 'set' magic afterwards on\nthe destination SV; \"SvSetSV\" and \"SvSetSVnosteal\" do not.\n\n\"SvSetSVnosteal\" \"SvSetMagicSVnosteal\" call a non-destructive version of \"svsetsv\".\n\nvoid SvSetMagicSV(SV* dsv, SV* ssv)\n\n\"svsetnv\"\n\"svsetnvmg\"\nThese copy a double into the given SV, upgrading first if necessary.\n\nThey differ only in that \"svsetnvmg\" handles 'set' magic; \"svsetnv\" does not.\n\nvoid svsetnv(SV * const sv, const NV num)\n\n\"svsetpv\"\n\"svsetpvmg\"\n\"svsetpvn\"\n\"svsetpvnfresh\"\n\"svsetpvnmg\"\n\"svsetpvs\"\n\"svsetpvsmg\"\nThese copy a string into the SV \"sv\", making sure it is \"SvPOKonly\".\n\nIn the \"pvs\" forms, the string must be a C literal string, enclosed in double quotes.\n\nIn the \"pvn\" forms, the first byte of the string is pointed to by \"ptr\", and \"len\"\nindicates the number of bytes to be copied, potentially including embedded \"NUL\"\ncharacters.\n\nIn the plain \"pv\" forms, \"ptr\" points to a NUL-terminated C string. That is, it points\nto the first byte of the string, and the copy proceeds up through the first encountered\n\"NUL\" byte.\n\nIn the forms that take a \"ptr\" argument, if it is NULL, the SV will become undefined.\n\nThe UTF-8 flag is not changed by these functions. A terminating NUL byte is guaranteed\nin the result.\n\nThe \"mg\" forms handle 'set' magic; the other forms skip all magic.\n\n\"svsetpvnfresh\" is a cut-down alternative to \"svsetpvn\", intended ONLY to be used with\na fresh sv that has been upgraded to a SVtPV, SVtPVIV, SVtPVNV, or SVtPVMG.\n\nvoid svsetpv (SV * const sv, const char * const ptr)\nvoid svsetpvmg (SV * const sv, const char * const ptr)\nvoid svsetpvn (SV * const sv, const char * const ptr,\nconst STRLEN len)\nvoid svsetpvnfresh(SV * const sv, const char * const ptr,\nconst STRLEN len)\nvoid svsetpvnmg (SV * const sv, const char * const ptr,\nconst STRLEN len)\nvoid svsetpvs (SV* sv, \"literal string\")\nvoid svsetpvsmg (SV* sv, \"literal string\")\n\n\"svsetpvbufsize\"\nSets the SV to be a string of cur bytes length, with at least len bytes available.\nEnsures that there is a null byte at SvEND. Returns a char * pointer to the SvPV buffer.\n\nchar * svsetpvbufsize(SV * const sv, const STRLEN cur,\nconst STRLEN len)\n\n\"svsetpvf\"\n\"svsetpvfmg\"\n\"svsetpvfmgnocontext\"\n\"svsetpvfnocontext\"\nThese work like \"svcatpvf\" but copy the text into the SV instead of appending it.\n\nThe differences between these are:\n\n\"svsetpvfmg\" and \"svsetpvfmgnocontext\" perform 'set' magic; \"svsetpvf\" and\n\"svsetpvfnocontext\" skip all magic.\n\n\"svsetpvfnocontext\" and \"svsetpvfmgnocontext\" do not take a thread context (\"aTHX\")\nparameter, so are used in situations where the caller doesn't already have the thread\ncontext.\n\nNOTE: \"svsetpvf\" must be explicitly called as \"Perlsvsetpvf\" with an \"aTHX\"\nparameter.\n\nNOTE: \"svsetpvfmg\" must be explicitly called as \"Perlsvsetpvfmg\" with an \"aTHX\"\nparameter.\n\nvoid Perlsvsetpvf (pTHX SV * const sv,\nconst char * const pat, ...)\nvoid Perlsvsetpvfmg (pTHX SV * const sv,\nconst char * const pat, ...)\nvoid svsetpvfmgnocontext(SV * const sv,\nconst char * const pat, ...)\nvoid svsetpvfnocontext (SV * const sv,\nconst char * const pat, ...)\n\n\"svsetrefiv\"\nCopies an integer into a new SV, optionally blessing the SV. The \"rv\" argument will be\nupgraded to an RV. That RV will be modified to point to the new SV. The \"classname\"\nargument indicates the package for the blessing. Set \"classname\" to \"NULL\" to avoid the\nblessing. The new SV will have a reference count of 1, and the RV will be returned.\n\nSV * svsetrefiv(SV * const rv, const char * const classname,\nconst IV iv)\n\n\"svsetrefnv\"\nCopies a double into a new SV, optionally blessing the SV. The \"rv\" argument will be\nupgraded to an RV. That RV will be modified to point to the new SV. The \"classname\"\nargument indicates the package for the blessing. Set \"classname\" to \"NULL\" to avoid the\nblessing. The new SV will have a reference count of 1, and the RV will be returned.\n\nSV * svsetrefnv(SV * const rv, const char * const classname,\nconst NV nv)\n\n\"svsetrefpv\"\nCopies a pointer into a new SV, optionally blessing the SV. The \"rv\" argument will be\nupgraded to an RV. That RV will be modified to point to the new SV. If the \"pv\"\nargument is \"NULL\", then \"PLsvundef\" will be placed into the SV. The \"classname\"\nargument indicates the package for the blessing. Set \"classname\" to \"NULL\" to avoid the\nblessing. The new SV will have a reference count of 1, and the RV will be returned.\n\nDo not use with other Perl types such as HV, AV, SV, CV, because those objects will\nbecome corrupted by the pointer copy process.\n\nNote that \"svsetrefpvn\" copies the string while this copies the pointer.\n\nSV * svsetrefpv(SV * const rv, const char * const classname,\nvoid * const pv)\n\n\"svsetrefpvn\"\nCopies a string into a new SV, optionally blessing the SV. The length of the string must\nbe specified with \"n\". The \"rv\" argument will be upgraded to an RV. That RV will be\nmodified to point to the new SV. The \"classname\" argument indicates the package for the\nblessing. Set \"classname\" to \"NULL\" to avoid the blessing. The new SV will have a\nreference count of 1, and the RV will be returned.\n\nNote that \"svsetrefpv\" copies the pointer while this copies the string.\n\nSV * svsetrefpvn(SV * const rv, const char * const classname,\nconst char * const pv, const STRLEN n)\n\n\"svsetrefpvs\"\nLike \"svsetrefpvn\", but takes a literal string instead of a string/length pair.\n\nSV * svsetrefpvs(SV *const rv, const char *const classname,\n\"literal string\")\n\n\"svsetrefuv\"\nCopies an unsigned integer into a new SV, optionally blessing the SV. The \"rv\" argument\nwill be upgraded to an RV. That RV will be modified to point to the new SV. The\n\"classname\" argument indicates the package for the blessing. Set \"classname\" to \"NULL\"\nto avoid the blessing. The new SV will have a reference count of 1, and the RV will be\nreturned.\n\nSV * svsetrefuv(SV * const rv, const char * const classname,\nconst UV uv)\n\n\"svsetrvinc\"\n\"svsetrvincmg\"\nAs \"svsetrvnoinc\" but increments the reference count of ref.\n\n\"svsetrvincmg\" will invoke 'set' magic on the SV; \"svsetrvinc\" will not.\n\nvoid svsetrvinc(SV * const sv, SV * const ref)\n\n\"svsetrvnoinc\"\n\"svsetrvnoincmg\"\nCopies an SV pointer into the given SV as an SV reference, upgrading it if necessary.\nAfter this, SvRV(sv) is equal to ref. This does not adjust the reference count of ref.\nThe reference ref must not be NULL.\n\n\"svsetrvnoincmg\" will invoke 'set' magic on the SV; \"svsetrvnoinc\" will not.\n\nvoid svsetrvnoinc(SV * const sv, SV * const ref)\n\n\"svsetsv\"\n\"svsetsvflags\"\n\"svsetsvmg\"\n\"svsetsvnomg\"\nThese copy the contents of the source SV \"ssv\" into the destination SV \"dsv\". \"ssv\" may\nbe destroyed if it is mortal, so don't use these functions if the source SV needs to be\nreused. Loosely speaking, they perform a copy-by-value, obliterating any previous\ncontent of the destination.\n\nThey differ only in that:\n\n\"svsetsv\" calls 'get' magic on \"ssv\", but skips 'set' magic on \"dsv\".\n\n\"svsetsvmg\" calls both 'get' magic on \"ssv\" and 'set' magic on \"dsv\".\n\n\"svsetsvnomg\" skips all magic.\n\n\"svsetsvflags\" has a \"flags\" parameter which you can use to specify any combination of\nmagic handling, and also you can specify \"SVNOSTEAL\" so that the buffers of temps will\nnot be stolen.\n\nYou probably want to instead use one of the assortment of wrappers, such as \"SvSetSV\",\n\"SvSetSVnosteal\", \"SvSetMagicSV\" and \"SvSetMagicSVnosteal\".\n\n\"svsetsvflags\" is the primary function for copying scalars, and most other copy-ish\nfunctions and macros use it underneath.\n\nvoid svsetsv (SV *dsv, SV *ssv)\nvoid svsetsvflags(SV *dsv, SV *ssv, const I32 flags)\nvoid svsetsvmg (SV * const dsv, SV * const ssv)\nvoid svsetsvnomg (SV *dsv, SV *ssv)\n\n\"svsettrue\"\nEquivalent to \"svsetsv(sv, &PLsvyes)\", but may be made more efficient in the future.\nDoesn't handle set magic.\n\nThe perl equivalent is \"$sv = !0;\".\n\nIntroduced in perl 5.35.11.\n\nvoid svsettrue(SV *sv)\n\n\"svsetundef\"\nEquivalent to \"svsetsv(sv, &PLsvundef)\", but more efficient. Doesn't handle set\nmagic.\n\nThe perl equivalent is \"$sv = undef;\". Note that it doesn't free any string buffer,\nunlike \"undef $sv\".\n\nIntroduced in perl 5.25.12.\n\nvoid svsetundef(SV *sv)\n\n\"svsetuv\"\n\"svsetuvmg\"\nThese copy an unsigned integer into the given SV, upgrading first if necessary.\n\nThey differ only in that \"svsetuvmg\" handles 'set' magic; \"svsetuv\" does not.\n\nvoid svsetuv (SV * const sv, const UV num)\nvoid svsetuvmg(SV * const sv, const UV u)\n\n\"SvSHARE\"\nArranges for \"sv\" to be shared between threads if a suitable module has been loaded.\n\nvoid SvSHARE(SV* sv)\n\n\"SvSHAREDHASH\"\nReturns the hash for \"sv\" created by \"newSVpvnshare\".\n\nstruct hek* SvSHAREDHASH(SV * sv)\n\n\"SvSTASH\"\nReturns the stash of the SV.\n\nHV* SvSTASH(SV* sv)\n\n\"SvSTASHset\"\nSet the value of the STASH pointer in \"sv\" to val. See \"SvIVset\".\n\nvoid SvSTASHset(SV* sv, HV* val)\n\n\"svstreq\"\nA convenient shortcut for calling \"svstreqflags\" with the \"SVGMAGIC\" flag. This\nfunction basically behaves like the Perl code \"$sv1 eq $sv2\".\n\nbool svstreq(SV *sv1, SV *sv2)\n\n\"svstreqflags\"\nReturns a boolean indicating whether the strings in the two SVs are identical. If the\nflags argument has the \"SVGMAGIC\" bit set, it handles get-magic too. Will coerce its\nargs to strings if necessary. Treats \"NULL\" as undef. Correctly handles the UTF8 flag.\n\nIf flags does not have the \"SVSKIPOVERLOAD\" bit set, an attempt to use \"eq\" overloading\nwill be made. If such overloading does not exist or the flag is set, then regular string\ncomparison will be used instead.\n\nbool svstreqflags(SV *sv1, SV *sv2, const U32 flags)\n\n\"SvTRUE\"\n\"SvTRUENN\"\n\"SvTRUEnomg\"\n\"SvTRUEnomgNN\"\n\"SvTRUEx\"\nThese return a boolean indicating whether Perl would evaluate the SV as true or false.\nSee \"SvOK\" for a defined/undefined test.\n\nAs of Perl 5.32, all are guaranteed to evaluate \"sv\" only once. Prior to that release,\nonly \"SvTRUEx\" guaranteed single evaluation; now \"SvTRUEx\" is identical to \"SvTRUE\".\n\n\"SvTRUEnomg\" and \"TRUEnomgNN\" do not perform 'get' magic; the others do unless the\nscalar is already \"SvPOK\", \"SvIOK\", or \"SvNOK\" (the public, not the private flags).\n\n\"SvTRUENN\" is like \"SvTRUE\", but \"sv\" is assumed to be non-null (NN). If there is a\npossibility that it is NULL, use plain \"SvTRUE\".\n\n\"SvTRUEnomgNN\" is like \"SvTRUEnomg\", but \"sv\" is assumed to be non-null (NN). If\nthere is a possibility that it is NULL, use plain \"SvTRUEnomg\".\n\nbool SvTRUE(SV *sv)\n\n\"SvTYPE\"\nReturns the type of the SV. See \"svtype\".\n\nsvtype SvTYPE(SV* sv)\n\n\"SvUNLOCK\"\nReleases a mutual exclusion lock on \"sv\" if a suitable module has been loaded.\n\nvoid SvUNLOCK(SV* sv)\n\n\"svunmagic\"\nRemoves all magic of type \"type\" from an SV.\n\nint svunmagic(SV * const sv, const int type)\n\n\"svunmagicext\"\nRemoves all magic of type \"type\" with the specified \"vtbl\" from an SV.\n\nint svunmagicext(SV * const sv, const int type,\nconst MGVTBL *vtbl)\n\n\"svunref\"\nUnsets the RV status of the SV, and decrements the reference count of whatever was being\nreferenced by the RV. This can almost be thought of as a reversal of \"newSVrv\". This is\n\"svunrefflags\" with the \"flag\" being zero. See \"SvROKoff\".\n\nvoid svunref(SV *sv)\n\n\"svunrefflags\"\nUnsets the RV status of the SV, and decrements the reference count of whatever was being\nreferenced by the RV. This can almost be thought of as a reversal of \"newSVrv\". The\n\"cflags\" argument can contain \"SVIMMEDIATEUNREF\" to force the reference count to be\ndecremented (otherwise the decrementing is conditional on the reference count being\ndifferent from one or the reference being a readonly SV). See \"SvROKoff\".\n\nvoid svunrefflags(SV * const ref, const U32 flags)\n\n\"SvUOK\"\nReturns a boolean indicating whether the SV contains an integer that must be interpreted\nas unsigned. A non-negative integer whose value is within the range of both an IV and a\nUV may be flagged as either \"SvUOK\" or \"SvIOK\".\n\nbool SvUOK(SV* sv)\n\n\"SvUPGRADE\"\nUsed to upgrade an SV to a more complex form. Uses \"svupgrade\" to perform the upgrade\nif necessary. See \"svtype\".\n\nvoid SvUPGRADE(SV* sv, svtype type)\n\n\"svupgrade\"\nUpgrade an SV to a more complex form. Generally adds a new body type to the SV, then\ncopies across as much information as possible from the old body. It croaks if the SV is\nalready in a more complex form than requested. You generally want to use the \"SvUPGRADE\"\nmacro wrapper, which checks the type before calling \"svupgrade\", and hence does not\ncroak. See also \"svtype\".\n\nvoid svupgrade(SV * const sv, svtype newtype)\n\n\"svusepvn\"\n\"svusepvnflags\"\n\"svusepvnmg\"\nThese tell an SV to use \"ptr\" for its string value. Normally SVs have their string\nstored inside the SV, but these tell the SV to use an external string instead.\n\n\"ptr\" should point to memory that was allocated by \"\"Newx\"\". It must be the start of a\n\"Newx\"-ed block of memory, and not a pointer to the middle of it (beware of \"OOK\" and\ncopy-on-write), and not be from a non-\"Newx\" memory allocator like \"malloc\". The string\nlength, \"len\", must be supplied. By default this function will \"\"Renew\"\" (i.e. realloc,\nmove) the memory pointed to by \"ptr\", so that the pointer should not be freed or used by\nthe programmer after giving it to \"svusepvn\", and neither should any pointers from\n\"behind\" that pointer (e.g., \"ptr\" + 1) be used.\n\nIn the \"svusepvnflags\" form, if \"flags & SVSMAGIC\" is true, \"SvSETMAGIC\" is called\nbefore returning. And if \"flags & SVHASTRAILINGNUL\" is true, then \"ptr[len]\" must be\n\"NUL\", and the realloc will be skipped (i.e., the buffer is actually at least 1 byte\nlonger than \"len\", and already meets the requirements for storing in \"SvPVX\").\n\n\"svusepvn\" is merely \"svusepvnflags\" with \"flags\" set to 0, so 'set' magic is skipped.\n\n\"svusepvnmg\" is merely \"svusepvnflags\" with \"flags\" set to \"SVSMAGIC\", so 'set'\nmagic is performed.\n\nvoid svusepvn (SV *sv, char *ptr, STRLEN len)\nvoid svusepvnflags(SV * const sv, char *ptr, const STRLEN len,\nconst U32 flags)\nvoid svusepvnmg (SV *sv, char *ptr, STRLEN len)\n\n\"svutf8decode\"\nIf the PV of the SV is an octet sequence in Perl's extended UTF-8 and contains a\nmultiple-byte character, the \"SvUTF8\" flag is turned on so that it looks like a\ncharacter. If the PV contains only single-byte characters, the \"SvUTF8\" flag stays off.\nScans PV for validity and returns FALSE if the PV is invalid UTF-8.\n\nbool svutf8decode(SV * const sv)\n\n\"svutf8downgrade\"\n\"svutf8downgradeflags\"\n\"svutf8downgradenomg\"\nThese attempt to convert the PV of an SV from characters to bytes. If the PV contains a\ncharacter that cannot fit in a byte, this conversion will fail; in this case, \"FALSE\" is\nreturned if \"failok\" is true; otherwise they croak.\n\nThey are not a general purpose Unicode to byte encoding interface: use the \"Encode\"\nextension for that.\n\nThey differ only in that:\n\n\"svutf8downgrade\" processes 'get' magic on \"sv\".\n\n\"svutf8downgradenomg\" does not.\n\n\"svutf8downgradeflags\" has an additional \"flags\" parameter in which you can specify\n\"SVGMAGIC\" to process 'get' magic, or leave it cleared to not process 'get' magic.\n\nbool svutf8downgrade (SV * const sv, const bool failok)\nbool svutf8downgradeflags(SV * const sv, const bool failok,\nconst U32 flags)\nbool svutf8downgradenomg (SV * const sv, const bool failok)\n\n\"svutf8encode\"\nConverts the PV of an SV to UTF-8, but then turns the \"SvUTF8\" flag off so that it looks\nlike octets again.\n\nvoid svutf8encode(SV * const sv)\n\n\"SvUTF8off\"\nUnsets the UTF-8 status of an SV (the data is not changed, just the flag). Do not use\nfrivolously.\n\nvoid SvUTF8off(SV *sv)\n\n\"SvUTF8on\"\nTurn on the UTF-8 status of an SV (the data is not changed, just the flag). Do not use\nfrivolously.\n\nvoid SvUTF8on(SV *sv)\n\n\"svutf8upgrade\"\n\"svutf8upgradeflags\"\n\"svutf8upgradeflagsgrow\"\n\"svutf8upgradenomg\"\nThese convert the PV of an SV to its UTF-8-encoded form. The SV is forced to string form\nif it is not already. They always set the \"SvUTF8\" flag to avoid future validity checks\neven if the whole string is the same in UTF-8 as not. They return the number of bytes in\nthe converted string\n\nThe forms differ in just two ways. The main difference is whether or not they perform\n'get magic' on \"sv\". \"svutf8upgradenomg\" skips 'get magic'; \"svutf8upgrade\"\nperforms it; and \"svutf8upgradeflags\" and \"svutf8upgradeflagsgrow\" either perform\nit (if the \"SVGMAGIC\" bit is set in \"flags\") or don't (if that bit is cleared).\n\nThe other difference is that \"svutf8upgradeflagsgrow\" has an additional parameter,\n\"extra\", which allows the caller to specify an amount of space to be reserved as spare\nbeyond what is needed for the actual conversion. This is used when the caller knows it\nwill soon be needing yet more space, and it is more efficient to request space from the\nsystem in a single call. This form is otherwise identical to \"svutf8upgradeflags\".\n\nThese are not a general purpose byte encoding to Unicode interface: use the Encode\nextension for that.\n\nThe \"SVFORCEUTF8UPGRADE\" flag is now ignored.\n\nSTRLEN svutf8upgrade (SV *sv)\nSTRLEN svutf8upgradeflags (SV * const sv, const I32 flags)\nSTRLEN svutf8upgradeflagsgrow(SV * const sv, const I32 flags,\nSTRLEN extra)\nSTRLEN svutf8upgradenomg (SV *sv)\n\n\"SvUTF8\"\nReturns a U32 value indicating the UTF-8 status of an SV. If things are set-up properly,\nthis indicates whether or not the SV contains UTF-8 encoded data. You should use this\nafter a call to \"SvPV\" or one of its variants, in case any call to string overloading\nupdates the internal flag.\n\nIf you want to take into account the bytes pragma, use \"DOUTF8\" instead.\n\nU32 SvUTF8(SV* sv)\n\n\"SvUV\"\n\"SvUVnomg\"\n\"SvUVx\"\nThese each coerce the given SV to UV and return it. The returned value in many\ncircumstances will get stored in \"sv\"'s UV slot, but not in all cases. (Use \"svsetuv\"\nto make sure it does).\n\nAs of 5.37.1, all are guaranteed to evaluate \"sv\" only once.\n\n\"SvUVx\" is now identical to \"SvUV\", but prior to 5.37.1, it was the only form guaranteed\nto evaluate \"sv\" only once.\n\nUV SvUV(SV *sv)\n\n\"sv2uvflags\"\nReturn the unsigned integer value of an SV, doing any necessary string conversion. If\n\"flags\" has the \"SVGMAGIC\" bit set, does an mgget() first. Normally used via the\nSvUV(sv) and SvUVx(sv) macros.\n\nUV sv2uvflags(SV * const sv, const I32 flags)\n\n\"SvUVset\"\nSet the value of the UV pointer in \"sv\" to val. See \"SvIVset\".\n\nvoid SvUVset(SV* sv, UV val)\n\n\"SvUVX\"\nReturns the raw value in the SV's UV slot, without checks or conversions. Only use when\nyou are sure \"SvIOK\" is true. See also \"SvUV\".\n\nUV SvUVX(SV* sv)\n\n\"SvUVXx\"\n\"DEPRECATED!\" It is planned to remove \"SvUVXx\" from a future release of Perl. Do not\nuse it for new code; remove it from existing code.\n\nThis is an unnecessary synonym for \"SvUVX\"\n\nUV SvUVXx(SV* sv)\n\n\"svvcatpvf\"\n\"svvcatpvfmg\"\nThese process their arguments like \"svvcatpvfn\" called with a non-null C-style variable\nargument list, and append the formatted output to \"sv\".\n\nThey differ only in that \"svvcatpvfmg\" performs 'set' magic; \"svvcatpvf\" skips 'set'\nmagic.\n\nBoth perform 'get' magic.\n\nThey are usually accessed via their frontends \"svcatpvf\" and \"svcatpvfmg\".\n\nvoid svvcatpvf(SV * const sv, const char * const pat,\nvalist * const args)\n\n\"svvcatpvfn\"\n\"svvcatpvfnflags\"\nThese process their arguments like vsprintf(3) and append the formatted output to an SV.\nThey use an array of SVs if the C-style variable argument list is missing (\"NULL\").\nArgument reordering (using format specifiers like \"%2$d\" or \"%*2$d\") is supported only\nwhen using an array of SVs; using a C-style \"valist\" argument list with a format string\nthat uses argument reordering will yield an exception.\n\nWhen running with taint checks enabled, they indicate via \"maybetainted\" if results are\nuntrustworthy (often due to the use of locales).\n\nThey assume that \"pat\" has the same utf8-ness as \"sv\". It's the caller's responsibility\nto ensure that this is so.\n\nThey differ in that \"svvcatpvfnflags\" has a \"flags\" parameter in which you can set or\nclear the \"SVGMAGIC\" and/or SVSMAGIC flags, to specify which magic to handle or not\nhandle; whereas plain \"svvcatpvfn\" always specifies both 'get' and 'set' magic.\n\nThey are usually used via one of the frontends \"\"svvcatpvf\"\" and \"\"svvcatpvfmg\"\".\n\nvoid svvcatpvfn (SV * const sv, const char * const pat,\nconst STRLEN patlen, valist * const args,\nSV const svargs, const Sizet svcount,\nbool * const maybetainted)\nvoid svvcatpvfnflags(SV * const sv, const char * const pat,\nconst STRLEN patlen, valist * const args,\nSV const svargs, const Sizet svcount,\nbool * const maybetainted,\nconst U32 flags)\n\n\"SvVOK\"\nReturns a boolean indicating whether the SV contains a v-string.\n\nbool SvVOK(SV* sv)\n\n\"svvsetpvf\"\n\"svvsetpvfmg\"\nThese work like \"svvcatpvf\" but copy the text into the SV instead of appending it.\n\nThey differ only in that \"svvsetpvfmg\" performs 'set' magic; \"svvsetpvf\" skips all\nmagic.\n\nThey are usually used via their frontends, \"svsetpvf\" and \"svsetpvfmg\".\n\nvoid svvsetpvf(SV * const sv, const char * const pat,\nvalist * const args)\n\n\"svvsetpvfn\"\nWorks like \"svvcatpvfn\" but copies the text into the SV instead of appending it.\n\nUsually used via one of its frontends \"\"svvsetpvf\"\" and \"\"svvsetpvfmg\"\".\n\nvoid svvsetpvfn(SV * const sv, const char * const pat,\nconst STRLEN patlen, valist * const args,\nSV const svargs, const Sizet svcount,\nbool * const maybetainted)\n\n\"SvVSTRINGmg\"\nReturns the vstring magic, or NULL if none\n\nMAGIC* SvVSTRINGmg(SV * sv)\n\n\"vnewSVpvf\"\nLike \"newSVpvf\" but the arguments are an encapsulated argument list.\n\nSV * vnewSVpvf(const char * const pat, valist * const args)\n", "subsections": [] }, "Tainting": { "content": "\"SvTAINT\"\nTaints an SV if tainting is enabled, and if some input to the current expression is\ntainted--usually a variable, but possibly also implicit inputs such as locale settings.\n\"SvTAINT\" propagates that taintedness to the outputs of an expression in a pessimistic\nfashion; i.e., without paying attention to precisely which outputs are influenced by\nwhich inputs.\n\nvoid SvTAINT(SV* sv)\n\n\"SvTAINTED\"\nChecks to see if an SV is tainted. Returns TRUE if it is, FALSE if not.\n\nbool SvTAINTED(SV* sv)\n\n\"SvTAINTEDoff\"\nUntaints an SV. Be very careful with this routine, as it short-circuits some of Perl's\nfundamental security features. XS module authors should not use this function unless\nthey fully understand all the implications of unconditionally untainting the value.\nUntainting should be done in the standard perl fashion, via a carefully crafted regexp,\nrather than directly untainting variables.\n\nvoid SvTAINTEDoff(SV* sv)\n\n\"SvTAINTEDon\"\nMarks an SV as tainted if tainting is enabled.\n\nvoid SvTAINTEDon(SV* sv)\n", "subsections": [] }, "Time": { "content": "\"ASCTIMERPROTO\"\nThis symbol encodes the prototype of \"asctimer\". It is zero if \"dasctimer\" is undef,\nand one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dasctimer\" is defined.\n\n\"CTIMERPROTO\"\nThis symbol encodes the prototype of \"ctimer\". It is zero if \"dctimer\" is undef, and\none of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dctimer\" is defined.\n\n\"GMTIMEMAX\"\nThis symbol contains the maximum value for the \"timet\" offset that the system function\ngmtime () accepts, and defaults to 0\n\n\"GMTIMEMIN\"\nThis symbol contains the minimum value for the \"timet\" offset that the system function\ngmtime () accepts, and defaults to 0\n\n\"GMTIMERPROTO\"\nThis symbol encodes the prototype of \"gmtimer\". It is zero if \"dgmtimer\" is undef,\nand one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dgmtimer\" is defined.\n\n\"HASASCTIMER\"\nThis symbol, if defined, indicates that the \"asctimer\" routine is available to asctime\nre-entrantly.\n\n\"HASASCTIME64\"\nThis symbol, if defined, indicates that the \"asctime64\" () routine is available to do the\n64bit variant of asctime ()\n\n\"HASCTIMER\"\nThis symbol, if defined, indicates that the \"ctimer\" routine is available to ctime re-\nentrantly.\n\n\"HASCTIME64\"\nThis symbol, if defined, indicates that the \"ctime64\" () routine is available to do the\n64bit variant of ctime ()\n\n\"HASDIFFTIME\"\nThis symbol, if defined, indicates that the \"difftime\" routine is available.\n\n\"HASDIFFTIME64\"\nThis symbol, if defined, indicates that the \"difftime64\" () routine is available to do\nthe 64bit variant of difftime ()\n\n\"HASFUTIMES\"\nThis symbol, if defined, indicates that the \"futimes\" routine is available to change file\ndescriptor time stamps with \"struct timevals\".\n\n\"HASGETITIMER\"\nThis symbol, if defined, indicates that the \"getitimer\" routine is available to return\ninterval timers.\n\n\"HASGETTIMEOFDAY\"\nThis symbol, if defined, indicates that the gettimeofday() system call is available for a\nsub-second accuracy clock. Usually, the file sys/resource.h needs to be included (see\n\"ISYSRESOURCE\"). The type \"Timeval\" should be used to refer to \"\"struct timeval\"\".\n\n\"HASGMTIMER\"\nThis symbol, if defined, indicates that the \"gmtimer\" routine is available to gmtime re-\nentrantly.\n\n\"HASGMTIME64\"\nThis symbol, if defined, indicates that the \"gmtime64\" () routine is available to do the\n64bit variant of gmtime ()\n\n\"HASLOCALTIMER\"\nThis symbol, if defined, indicates that the \"localtimer\" routine is available to\nlocaltime re-entrantly.\n\n\"HASLOCALTIME64\"\nThis symbol, if defined, indicates that the \"localtime64\" () routine is available to do\nthe 64bit variant of localtime ()\n\n\"HASMKTIME\"\nThis symbol, if defined, indicates that the \"mktime\" routine is available.\n\n\"HASMKTIME64\"\nThis symbol, if defined, indicates that the \"mktime64\" () routine is available to do the\n64bit variant of mktime ()\n\n\"HASNANOSLEEP\"\nThis symbol, if defined, indicates that the \"nanosleep\" system call is available to sleep\nwith 1E-9 sec accuracy.\n\n\"HASSETITIMER\"\nThis symbol, if defined, indicates that the \"setitimer\" routine is available to set\ninterval timers.\n\n\"HASSTRFTIME\"\nThis symbol, if defined, indicates that the \"strftime\" routine is available to do time\nformatting.\n\n\"HASTIME\"\nThis symbol, if defined, indicates that the time() routine exists.\n\n\"HASTIMEGM\"\nThis symbol, if defined, indicates that the \"timegm\" routine is available to do the\nopposite of gmtime ()\n\n\"HASTIMES\"\nThis symbol, if defined, indicates that the times() routine exists. Note that this\nbecame obsolete on some systems (\"SUNOS\"), which now use getrusage(). It may be necessary\nto include sys/times.h.\n\n\"HASTMTMGMTOFF\"\nThis symbol, if defined, indicates to the C program that the \"struct tm\" has a\n\"tmgmtoff\" field.\n\n\"HASTMTMZONE\"\nThis symbol, if defined, indicates to the C program that the \"struct tm\" has a \"tmzone\"\nfield.\n\n\"HASTZNAME\"\nThis symbol, if defined, indicates that the \"tzname[]\" array is available to access\ntimezone names.\n\n\"HASUSLEEP\"\nThis symbol, if defined, indicates that the \"usleep\" routine is available to let the\nprocess sleep on a sub-second accuracy.\n\n\"HASUSLEEPPROTO\"\nThis symbol, if defined, indicates that the system provides a prototype for the usleep()\nfunction. Otherwise, it is up to the program to supply one. A good guess is\n\nextern int usleep(usecondst);\n\n\"ITIME\"\nThis symbol is always defined, and indicates to the C program that it should include\ntime.h.\n\n#ifdef ITIME\n#include \n#endif\n\n\"IUTIME\"\nThis symbol, if defined, indicates to the C program that it should include utime.h.\n\n#ifdef IUTIME\n#include \n#endif\n\n\"LOCALTIMEMAX\"\nThis symbol contains the maximum value for the \"timet\" offset that the system function\nlocaltime () accepts, and defaults to 0\n\n\"LOCALTIMEMIN\"\nThis symbol contains the minimum value for the \"timet\" offset that the system function\nlocaltime () accepts, and defaults to 0\n\n\"LOCALTIMERNEEDSTZSET\"\nMany libc's \"localtimer\" implementations do not call tzset, making them differ from\nlocaltime(), and making timezone changes using $\"ENV\"{TZ} without explicitly calling\ntzset impossible. This symbol makes us call tzset before \"localtimer\"\n\n\"LOCALTIMERPROTO\"\nThis symbol encodes the prototype of \"localtimer\". It is zero if \"dlocaltimer\" is\nundef, and one of the \"REENTRANTPROTOTABC\" macros of reentr.h if \"dlocaltimer\" is\ndefined.\n\n\"LRTZSET\"\nIf localtimer() needs tzset, it is defined in this define\n\n\"minimktime\"\nnormalise \"struct tm\" values without the localtime() semantics (and overhead) of\nmktime().\n\nvoid minimktime(struct tm *ptm)\n\n\"mystrftime\"\nstrftime(), but with a different API so that the return value is a pointer to the\nformatted result (which MUST be arranged to be FREED BY THE CALLER). This allows this\nfunction to increase the buffer size as needed, so that the caller doesn't have to worry\nabout that.\n\nOn failure it returns NULL.\n\nNote that yday and wday effectively are ignored by this function, as minimktime()\noverwrites them.\n\nAlso note that it is always executed in the underlying \"LCTIME\" locale of the program,\ngiving results based on that locale.\n\nchar * mystrftime(const char *fmt, int sec, int min, int hour,\nint mday, int mon, int year, int wday,\nint yday, int isdst)\n\n\"switchtogloballocale\"\nThis function copies the locale state of the calling thread into the program's global\nlocale, and converts the thread to use that global locale.\n\nIt is intended so that Perl can safely be used with C libraries that access the global\nlocale and which can't be converted to not access it. Effectively, this means libraries\nthat call setlocale(3) on non-Windows systems. (For portability, it is a good idea to\nuse it on Windows as well.)\n\nA downside of using it is that it disables the services that Perl provides to hide locale\ngotchas from your code. The service you most likely will miss regards the radix\ncharacter (decimal point) in floating point numbers. Code executed after this function\nis called can no longer just assume that this character is correct for the current\ncircumstances.\n\nTo return to Perl control, and restart the gotcha prevention services, call\n\"synclocale\". Behavior is undefined for any pure Perl code that executes while the\nswitch is in effect.\n\nThe global locale and the per-thread locales are independent. As long as just one thread\nconverts to the global locale, everything works smoothly. But if more than one does,\nthey can easily interfere with each other, and races are likely. On Windows systems\nprior to Visual Studio 15 (at which point Microsoft fixed a bug), races can occur (even\nif only one thread has been converted to the global locale), but only if you use the\nfollowing operations:\n\nPOSIX::localeconv\nI18N::Langinfo, items \"CRNCYSTR\" and \"THOUSEP\"\n\"Perllanginfo\" in perlapi, items \"CRNCYSTR\" and \"THOUSEP\"\n\nThe first item is not fixable (except by upgrading to a later Visual Studio release), but\nit would be possible to work around the latter two items by having Perl change its\nalgorithm for calculating these to use Windows API functions (likely \"GetNumberFormat\"\nand \"GetCurrencyFormat\"); patches welcome.\n\nXS code should never call plain \"setlocale\", but should instead be converted to either\ncall \"Perlsetlocale\" (which is a drop-in for the system \"setlocale\") or use the methods\ngiven in perlcall to call \"POSIX::setlocale\". Either one will transparently properly\nhandle all cases of single- vs multi-thread, POSIX 2008-supported or not.\n\nvoid switchtogloballocale()\n\n\"synclocale\"\nThis function copies the state of the program global locale into the calling thread, and\nconverts that thread to using per-thread locales, if it wasn't already, and the platform\nsupports them. The LCNUMERIC locale is toggled into the standard state (using the C\nlocale's conventions), if not within the lexical scope of \"use locale\".\n\nPerl will now consider itself to have control of the locale.\n\nSince unthreaded perls have only a global locale, this function is a no-op without\nthreads.\n\nThis function is intended for use with C libraries that do locale manipulation. It\nallows Perl to accommodate the use of them. Call this function before transferring back\nto Perl space so that it knows what state the C code has left things in.\n\nXS code should not manipulate the locale on its own. Instead, \"Perlsetlocale\" can be\nused at any time to query or change the locale (though changing the locale is antisocial\nand dangerous on multi-threaded systems that don't have multi-thread safe locale\noperations. (See \"Multi-threaded operation\" in perllocale).\n\nUsing the libc setlocale(3) function should be avoided. Nevertheless, certain non-Perl\nlibraries called from XS, do call it, and their behavior may not be able to be changed.\nThis function, along with \"switchtogloballocale\", can be used to get seamless behavior\nin these circumstances, as long as only one thread is involved.\n\nIf the library has an option to turn off its locale manipulation, doing that is\npreferable to using this mechanism. \"Gtk\" is such a library.\n\nThe return value is a boolean: TRUE if the global locale at the time of call was in\neffect for the caller; and FALSE if a per-thread locale was in effect.\n\nbool synclocale()\n", "subsections": [] }, "Typedef names": { "content": "\"DBHasht\"\nThis symbol contains the type of the prefix structure element in the db.h header file.\nIn older versions of DB, it was int, while in newer ones it is \"sizet\".\n\n\"DBPrefixt\"\nThis symbol contains the type of the prefix structure element in the db.h header file.\nIn older versions of DB, it was int, while in newer ones it is \"uint32t\".\n\n\"Direntryt\"\nThis symbol is set to '\"struct direct\"' or '\"struct dirent\"' depending on whether dirent\nis available or not. You should use this pseudo type to portably declare your directory\nentries.\n\n\"Fpost\"\nThis symbol holds the type used to declare file positions in libc. It can be \"fpost\",\nlong, uint, etc... It may be necessary to include sys/types.h to get any typedef'ed\ninformation.\n\n\"Freet\"\nThis variable contains the return type of free(). It is usually void, but occasionally\nint.\n\n\"Gidt\"\nThis symbol holds the return type of getgid() and the type of argument to setrgid() and\nrelated functions. Typically, it is the type of group ids in the kernel. It can be int,\nushort, \"gidt\", etc... It may be necessary to include sys/types.h to get any typedef'ed\ninformation.\n\n\"Gidtf\"\nThis symbol defines the format string used for printing a \"Gidt\".\n\n\"Gidtsign\"\nThis symbol holds the signedness of a \"Gidt\". 1 for unsigned, -1 for signed.\n\n\"Gidtsize\"\nThis symbol holds the size of a \"Gidt\" in bytes.\n\n\"Groupst\"\nThis symbol holds the type used for the second argument to getgroups() and setgroups().\nUsually, this is the same as gidtype (\"gidt\") , but sometimes it isn't. It can be int,\nushort, \"gidt\", etc... It may be necessary to include sys/types.h to get any typedef'ed\ninformation. This is only required if you have getgroups() or setgroups()..\n\n\"Malloct\"\nThis symbol is the type of pointer returned by malloc and realloc.\n\n\"Mmapt\"\nThis symbol holds the return type of the mmap() system call (and simultaneously the type\nof the first argument). Usually set to 'void *' or '\"caddrt\"'.\n\n\"Modet\"\nThis symbol holds the type used to declare file modes for systems calls. It is usually\n\"modet\", but may be int or unsigned short. It may be necessary to include sys/types.h\nto get any typedef'ed information.\n\n\"Netdbhlent\"\nThis symbol holds the type used for the 2nd argument to gethostbyaddr().\n\n\"Netdbhostt\"\nThis symbol holds the type used for the 1st argument to gethostbyaddr().\n\n\"Netdbnamet\"\nThis symbol holds the type used for the argument to gethostbyname().\n\n\"Netdbnett\"\nThis symbol holds the type used for the 1st argument to getnetbyaddr().\n\n\"Offt\"\nThis symbol holds the type used to declare offsets in the kernel. It can be int, long,\n\"offt\", etc... It may be necessary to include sys/types.h to get any typedef'ed\ninformation.\n\n\"Offtsize\"\nThis symbol holds the number of bytes used by the \"Offt\".\n\n\"Pidt\"\nThis symbol holds the type used to declare process ids in the kernel. It can be int,\nuint, \"pidt\", etc... It may be necessary to include sys/types.h to get any typedef'ed\ninformation.\n\n\"Randseedt\"\nThis symbol defines the type of the argument of the random seed function.\n\n\"Selectfdsett\"\nThis symbol holds the type used for the 2nd, 3rd, and 4th arguments to select. Usually,\nthis is '\"fdset\" *', if \"HASFDSET\" is defined, and 'int *' otherwise. This is only\nuseful if you have select(), of course.\n\n\"Shmatt\"\nThis symbol holds the return type of the shmat() system call. Usually set to 'void *' or\n'char *'.\n\n\"Signalt\"\nThis symbol's value is either \"void\" or \"int\", corresponding to the appropriate return\ntype of a signal handler. Thus, you can declare a signal handler using \"\"Signalt\"\n(*handler)()\", and define the handler using \"\"Signalt\" handler(sig)\".\n\n\"Sizet\"\nThis symbol holds the type used to declare length parameters for string functions. It is\nusually \"sizet\", but may be unsigned long, int, etc. It may be necessary to include\nsys/types.h to get any typedef'ed information.\n\n\"Sizetsize\"\nThis symbol holds the size of a \"Sizet\" in bytes.\n\n\"Socksizet\"\nThis symbol holds the type used for the size argument of various socket calls (just the\nbase type, not the pointer-to).\n\n\"SSizet\"\nThis symbol holds the type used by functions that return a count of bytes or an error\ncondition. It must be a signed type. It is usually \"ssizet\", but may be long or int,\netc. It may be necessary to include sys/types.h or unistd.h to get any typedef'ed\ninformation. We will pick a type such that sizeof(SSizet) == sizeof(Sizet).\n\n\"Timet\"\nThis symbol holds the type returned by time(). It can be long, or \"timet\" on \"BSD\" sites\n(in which case sys/types.h should be included).\n\n\"Uidt\"\nThis symbol holds the type used to declare user ids in the kernel. It can be int,\nushort, \"uidt\", etc... It may be necessary to include sys/types.h to get any typedef'ed\ninformation.\n\n\"Uidtf\"\nThis symbol defines the format string used for printing a \"Uidt\".\n\n\"Uidtsign\"\nThis symbol holds the signedness of a \"Uidt\". 1 for unsigned, -1 for signed.\n\n\"Uidtsize\"\nThis symbol holds the size of a \"Uidt\" in bytes.\n", "subsections": [] }, "Unicode Support": { "content": "\"Unicode Support\" in perlguts has an introduction to this API.\n\nSee also \"Character classification\", \"Character case changing\", and \"String Handling\".\nVarious functions outside this section also work specially with Unicode. Search for the\nstring \"utf8\" in this document.\n\n\"BOMUTF8\"\nThis is a macro that evaluates to a string constant of the UTF-8 bytes that define the\nUnicode BYTE ORDER MARK (U+FEFF) for the platform that perl is compiled on. This allows\ncode to use a mnemonic for this character that works on both ASCII and EBCDIC platforms.\n\"sizeof(BOMUTF8) - 1\" can be used to get its length in bytes.\n\n\"bytescmputf8\"\nCompares the sequence of characters (stored as octets) in \"b\", \"blen\" with the sequence\nof characters (stored as UTF-8) in \"u\", \"ulen\". Returns 0 if they are equal, -1 or -2 if\nthe first string is less than the second string, +1 or +2 if the first string is greater\nthan the second string.\n\n-1 or +1 is returned if the shorter string was identical to the start of the longer\nstring. -2 or +2 is returned if there was a difference between characters within the\nstrings.\n\nint bytescmputf8(const U8 *b, STRLEN blen, const U8 *u,\nSTRLEN ulen)\n\n\"bytesfromutf8\"\nNOTE: \"bytesfromutf8\" is experimental and may change or be removed without notice.\n\nConverts a potentially UTF-8 encoded string \"s\" of length *lenp into native byte\nencoding. On input, the boolean *isutf8p gives whether or not \"s\" is actually encoded\nin UTF-8.\n\nUnlike \"utf8tobytes\" but like \"bytestoutf8\", this is non-destructive of the input\nstring.\n\nDo nothing if *isutf8p is 0, or if there are code points in the string not expressible\nin native byte encoding. In these cases, *isutf8p and *lenp are unchanged, and the\nreturn value is the original \"s\".\n\nOtherwise, *isutf8p is set to 0, and the return value is a pointer to a newly created\nstring containing a downgraded copy of \"s\", and whose length is returned in *lenp,\nupdated. The new string is \"NUL\"-terminated. The caller is responsible for arranging\nfor the memory used by this string to get freed.\n\nUpon successful return, the number of variants in the string can be computed by having\nsaved the value of *lenp before the call, and subtracting the after-call value of *lenp\nfrom it.\n\nU8 * bytesfromutf8(const U8 *s, STRLEN *lenp, bool *isutf8p)\n\n\"bytestoutf8\"\nNOTE: \"bytestoutf8\" is experimental and may change or be removed without notice.\n\nConverts a string \"s\" of length *lenp bytes from the native encoding into UTF-8. Returns\na pointer to the newly-created string, and sets *lenp to reflect the new length in bytes.\nThe caller is responsible for arranging for the memory used by this string to get freed.\n\nUpon successful return, the number of variants in the string can be computed by having\nsaved the value of *lenp before the call, and subtracting it from the after-call value of\n*lenp.\n\nA \"NUL\" character will be written after the end of the string.\n\nIf you want to convert to UTF-8 from encodings other than the native (Latin1 or EBCDIC),\nsee \"svrecodetoutf8\"().\n\nU8 * bytestoutf8(const U8 *s, STRLEN *lenp)\n\n\"DOUTF8\"\nReturns a bool giving whether or not the PV in \"sv\" is to be treated as being encoded in\nUTF-8.\n\nYou should use this after a call to SvPV() or one of its variants, in case any call to\nstring overloading updates the internal UTF-8 encoding flag.\n\nbool DOUTF8(SV* sv)\n\n\"foldEQutf8\"\nReturns true if the leading portions of the strings \"s1\" and \"s2\" (either or both of\nwhich may be in UTF-8) are the same case-insensitively; false otherwise. How far into\nthe strings to compare is determined by other input parameters.\n\nIf \"u1\" is true, the string \"s1\" is assumed to be in UTF-8-encoded Unicode; otherwise it\nis assumed to be in native 8-bit encoding. Correspondingly for \"u2\" with respect to\n\"s2\".\n\nIf the byte length \"l1\" is non-zero, it says how far into \"s1\" to check for fold\nequality. In other words, \"s1\"+\"l1\" will be used as a goal to reach. The scan will not\nbe considered to be a match unless the goal is reached, and scanning won't continue past\nthat goal. Correspondingly for \"l2\" with respect to \"s2\".\n\nIf \"pe1\" is non-\"NULL\" and the pointer it points to is not \"NULL\", that pointer is\nconsidered an end pointer to the position 1 byte past the maximum point in \"s1\" beyond\nwhich scanning will not continue under any circumstances. (This routine assumes that\nUTF-8 encoded input strings are not malformed; malformed input can cause it to read past\n\"pe1\"). This means that if both \"l1\" and \"pe1\" are specified, and \"pe1\" is less than\n\"s1\"+\"l1\", the match will never be successful because it can never get as far as its goal\n(and in fact is asserted against). Correspondingly for \"pe2\" with respect to \"s2\".\n\nAt least one of \"s1\" and \"s2\" must have a goal (at least one of \"l1\" and \"l2\" must be\nnon-zero), and if both do, both have to be reached for a successful match. Also, if the\nfold of a character is multiple characters, all of them must be matched (see tr21\nreference below for 'folding').\n\nUpon a successful match, if \"pe1\" is non-\"NULL\", it will be set to point to the beginning\nof the next character of \"s1\" beyond what was matched. Correspondingly for \"pe2\" and\n\"s2\".\n\nFor case-insensitiveness, the \"casefolding\" of Unicode is used instead of\nupper/lowercasing both the characters, see (Case\nMappings).\n\nI32 foldEQutf8(const char *s1, char pe1, UV l1, bool u1,\nconst char *s2, char pe2, UV l2, bool u2)\n\n\"isasciistring\"\nThis is a misleadingly-named synonym for \"isutf8invariantstring\". On ASCII-ish\nplatforms, the name isn't misleading: the ASCII-range characters are exactly the UTF-8\ninvariants. But EBCDIC machines have more invariants than just the ASCII characters, so\n\"isutf8invariantstring\" is preferred.\n\nbool isasciistring(const U8 * const s, STRLEN len)\n\n\"isC9STRICTUTF8CHAR\"\nEvaluates to non-zero if the first few bytes of the string starting at \"s\" and looking no\nfurther than \"e - 1\" are well-formed UTF-8 that represents some Unicode non-surrogate\ncode point; otherwise it evaluates to 0. If non-zero, the value gives how many bytes\nstarting at \"s\" comprise the code point's representation. Any bytes remaining before\n\"e\", but beyond the ones needed to form the first code point in \"s\", are not examined.\n\nThe largest acceptable code point is the Unicode maximum 0x10FFFF. This differs from\n\"isSTRICTUTF8CHAR\" only in that it accepts non-character code points. This corresponds\nto Unicode Corrigendum #9 . which\nsaid that non-character code points are merely discouraged rather than completely\nforbidden in open interchange. See \"Noncharacter code points\" in perlunicode.\n\nUse \"isUTF8CHAR\" to check for Perl's extended UTF-8; and \"isUTF8CHARflags\" for a more\ncustomized definition.\n\nUse \"isc9strictutf8string\", \"isc9strictutf8stringloc\", and\n\"isc9strictutf8stringloclen\" to check entire strings.\n\nSizet isC9STRICTUTF8CHAR(const U8 * const s0,\nconst U8 * const e)\n\n\"isc9strictutf8string\"\nReturns TRUE if the first \"len\" bytes of string \"s\" form a valid UTF-8-encoded string\nthat conforms to Unicode Corrigendum #9\n; otherwise it returns FALSE. If\n\"len\" is 0, it will be calculated using strlen(s) (which means if you use this option,\nthat \"s\" can't have embedded \"NUL\" characters and has to have a terminating \"NUL\" byte).\nNote that all characters being ASCII constitute 'a valid UTF-8 string'.\n\nThis function returns FALSE for strings containing any code points above the Unicode max\nof 0x10FFFF or surrogate code points, but accepts non-character code points per\nCorrigendum #9 .\n\nSee also \"isutf8invariantstring\", \"isutf8invariantstringloc\", \"isutf8string\",\n\"isutf8stringflags\", \"isutf8stringloc\", \"isutf8stringlocflags\",\n\"isutf8stringloclen\", \"isutf8stringloclenflags\", \"isutf8fixedwidthbufflags\",\n\"isutf8fixedwidthbuflocflags\", \"isutf8fixedwidthbufloclenflags\",\n\"isstrictutf8string\", \"isstrictutf8stringloc\", \"isstrictutf8stringloclen\",\n\"isc9strictutf8stringloc\", and \"isc9strictutf8stringloclen\".\n\nbool isc9strictutf8string(const U8 *s, STRLEN len)\n\n\"isc9strictutf8stringloc\"\nLike \"isc9strictutf8string\" but stores the location of the failure (in the case of\n\"utf8ness failure\") or the location \"s\"+\"len\" (in the case of \"utf8ness success\") in the\n\"ep\" pointer.\n\nSee also \"isc9strictutf8stringloclen\".\n\nbool isc9strictutf8stringloc(const U8 *s, STRLEN len,\nconst U8 ep)\n\n\"isc9strictutf8stringloclen\"\nLike \"isc9strictutf8string\" but stores the location of the failure (in the case of\n\"utf8ness failure\") or the location \"s\"+\"len\" (in the case of \"utf8ness success\") in the\n\"ep\" pointer, and the number of UTF-8 encoded characters in the \"el\" pointer.\n\nSee also \"isc9strictutf8stringloc\".\n\nbool isc9strictutf8stringloclen(const U8 *s, STRLEN len,\nconst U8 ep, STRLEN *el)\n\n\"isinvariantstring\"\nThis is a somewhat misleadingly-named synonym for \"isutf8invariantstring\".\n\"isutf8invariantstring\" is preferred, as it indicates under what conditions the string\nis invariant.\n\nbool isinvariantstring(const U8 * const s, STRLEN len)\n\n\"isSTRICTUTF8CHAR\"\nEvaluates to non-zero if the first few bytes of the string starting at \"s\" and looking no\nfurther than \"e - 1\" are well-formed UTF-8 that represents some Unicode code point\ncompletely acceptable for open interchange between all applications; otherwise it\nevaluates to 0. If non-zero, the value gives how many bytes starting at \"s\" comprise the\ncode point's representation. Any bytes remaining before \"e\", but beyond the ones needed\nto form the first code point in \"s\", are not examined.\n\nThe largest acceptable code point is the Unicode maximum 0x10FFFF, and must not be a\nsurrogate nor a non-character code point. Thus this excludes any code point from Perl's\nextended UTF-8.\n\nThis is used to efficiently decide if the next few bytes in \"s\" is legal Unicode-\nacceptable UTF-8 for a single character.\n\nUse \"isC9STRICTUTF8CHAR\" to use the Unicode Corrigendum #9\n definition of allowable code points;\n\"isUTF8CHAR\" to check for Perl's extended UTF-8; and \"isUTF8CHARflags\" for a more\ncustomized definition.\n\nUse \"isstrictutf8string\", \"isstrictutf8stringloc\", and\n\"isstrictutf8stringloclen\" to check entire strings.\n\nSizet isSTRICTUTF8CHAR(const U8 * const s0,\nconst U8 * const e)\n\n\"isstrictutf8string\"\nReturns TRUE if the first \"len\" bytes of string \"s\" form a valid UTF-8-encoded string\nthat is fully interchangeable by any application using Unicode rules; otherwise it\nreturns FALSE. If \"len\" is 0, it will be calculated using strlen(s) (which means if you\nuse this option, that \"s\" can't have embedded \"NUL\" characters and has to have a\nterminating \"NUL\" byte). Note that all characters being ASCII constitute 'a valid UTF-8\nstring'.\n\nThis function returns FALSE for strings containing any code points above the Unicode max\nof 0x10FFFF, surrogate code points, or non-character code points.\n\nSee also \"isutf8invariantstring\", \"isutf8invariantstringloc\", \"isutf8string\",\n\"isutf8stringflags\", \"isutf8stringloc\", \"isutf8stringlocflags\",\n\"isutf8stringloclen\", \"isutf8stringloclenflags\", \"isutf8fixedwidthbufflags\",\n\"isutf8fixedwidthbuflocflags\", \"isutf8fixedwidthbufloclenflags\",\n\"isstrictutf8stringloc\", \"isstrictutf8stringloclen\", \"isc9strictutf8string\",\n\"isc9strictutf8stringloc\", and \"isc9strictutf8stringloclen\".\n\nbool isstrictutf8string(const U8 *s, STRLEN len)\n\n\"isstrictutf8stringloc\"\nLike \"isstrictutf8string\" but stores the location of the failure (in the case of\n\"utf8ness failure\") or the location \"s\"+\"len\" (in the case of \"utf8ness success\") in the\n\"ep\" pointer.\n\nSee also \"isstrictutf8stringloclen\".\n\nbool isstrictutf8stringloc(const U8 *s, STRLEN len,\nconst U8 ep)\n\n\"isstrictutf8stringloclen\"\nLike \"isstrictutf8string\" but stores the location of the failure (in the case of\n\"utf8ness failure\") or the location \"s\"+\"len\" (in the case of \"utf8ness success\") in the\n\"ep\" pointer, and the number of UTF-8 encoded characters in the \"el\" pointer.\n\nSee also \"isstrictutf8stringloc\".\n\nbool isstrictutf8stringloclen(const U8 *s, STRLEN len,\nconst U8 ep, STRLEN *el)\n\n\"isUTF8CHAR\"\nEvaluates to non-zero if the first few bytes of the string starting at \"s\" and looking no\nfurther than \"e - 1\" are well-formed UTF-8, as extended by Perl, that represents some\ncode point; otherwise it evaluates to 0. If non-zero, the value gives how many bytes\nstarting at \"s\" comprise the code point's representation. Any bytes remaining before\n\"e\", but beyond the ones needed to form the first code point in \"s\", are not examined.\n\nThe code point can be any that will fit in an IV on this machine, using Perl's extension\nto official UTF-8 to represent those higher than the Unicode maximum of 0x10FFFF. That\nmeans that this macro is used to efficiently decide if the next few bytes in \"s\" is legal\nUTF-8 for a single character.\n\nUse \"isSTRICTUTF8CHAR\" to restrict the acceptable code points to those defined by\nUnicode to be fully interchangeable across applications; \"isC9STRICTUTF8CHAR\" to use\nthe Unicode Corrigendum #9 definition\nof allowable code points; and \"isUTF8CHARflags\" for a more customized definition.\n\nUse \"isutf8string\", \"isutf8stringloc\", and \"isutf8stringloclen\" to check entire\nstrings.\n\nNote also that a UTF-8 \"invariant\" character (i.e. ASCII on non-EBCDIC machines) is a\nvalid UTF-8 character.\n\nSizet isUTF8CHAR(const U8 * const s0, const U8 * const e)\n\n\"isutf8charbuf\"\nThis is identical to the macro \"isUTF8CHAR\" in perlapi.\n\nSTRLEN isutf8charbuf(const U8 *buf, const U8 *bufend)\n\n\"isUTF8CHARflags\"\nEvaluates to non-zero if the first few bytes of the string starting at \"s\" and looking no\nfurther than \"e - 1\" are well-formed UTF-8, as extended by Perl, that represents some\ncode point, subject to the restrictions given by \"flags\"; otherwise it evaluates to 0.\nIf non-zero, the value gives how many bytes starting at \"s\" comprise the code point's\nrepresentation. Any bytes remaining before \"e\", but beyond the ones needed to form the\nfirst code point in \"s\", are not examined.\n\nIf \"flags\" is 0, this gives the same results as \"isUTF8CHAR\"; if \"flags\" is\n\"UTF8DISALLOWILLEGALINTERCHANGE\", this gives the same results as \"isSTRICTUTF8CHAR\";\nand if \"flags\" is \"UTF8DISALLOWILLEGALC9INTERCHANGE\", this gives the same results as\n\"isC9STRICTUTF8CHAR\". Otherwise \"flags\" may be any combination of the\n\"UTF8DISALLOWfoo\" flags understood by \"utf8ntouvchr\", with the same meanings.\n\nThe three alternative macros are for the most commonly needed validations; they are\nlikely to run somewhat faster than this more general one, as they can be inlined into\nyour code.\n\nUse \"isutf8stringflags\", \"isutf8stringlocflags\", and \"isutf8stringloclenflags\"\nto check entire strings.\n\nSizet isUTF8CHARflags(const U8 * const s0, const U8 * const e,\nconst U32 flags)\n\n\"isutf8fixedwidthbufflags\"\nReturns TRUE if the fixed-width buffer starting at \"s\" with length \"len\" is entirely\nvalid UTF-8, subject to the restrictions given by \"flags\"; otherwise it returns FALSE.\n\nIf \"flags\" is 0, any well-formed UTF-8, as extended by Perl, is accepted without\nrestriction. If the final few bytes of the buffer do not form a complete code point,\nthis will return TRUE anyway, provided that \"isutf8validpartialcharflags\" returns\nTRUE for them.\n\nIf \"flags\" in non-zero, it can be any combination of the \"UTF8DISALLOWfoo\" flags\naccepted by \"utf8ntouvchr\", and with the same meanings.\n\nThis function differs from \"isutf8stringflags\" only in that the latter returns FALSE\nif the final few bytes of the string don't form a complete code point.\n\nbool isutf8fixedwidthbufflags(const U8 * const s,\nSTRLEN len, const U32 flags)\n\n\"isutf8fixedwidthbuflocflags\"\nLike \"isutf8fixedwidthbufflags\" but stores the location of the failure in the \"ep\"\npointer. If the function returns TRUE, *ep will point to the beginning of any partial\ncharacter at the end of the buffer; if there is no partial character *ep will contain\n\"s\"+\"len\".\n\nSee also \"isutf8fixedwidthbufloclenflags\".\n\nbool isutf8fixedwidthbuflocflags(const U8 * const s,\nSTRLEN len, const U8 ep,\nconst U32 flags)\n\n\"isutf8fixedwidthbufloclenflags\"\nLike \"isutf8fixedwidthbuflocflags\" but stores the number of complete, valid\ncharacters found in the \"el\" pointer.\n\nbool isutf8fixedwidthbufloclenflags(const U8 * const s,\nSTRLEN len,\nconst U8 ep,\nSTRLEN *el,\nconst U32 flags)\n\n\"isutf8invariantstring\"\nReturns TRUE if the first \"len\" bytes of the string \"s\" are the same regardless of the\nUTF-8 encoding of the string (or UTF-EBCDIC encoding on EBCDIC machines); otherwise it\nreturns FALSE. That is, it returns TRUE if they are UTF-8 invariant. On ASCII-ish\nmachines, all the ASCII characters and only the ASCII characters fit this definition. On\nEBCDIC machines, the ASCII-range characters are invariant, but so also are the C1\ncontrols.\n\nIf \"len\" is 0, it will be calculated using strlen(s), (which means if you use this\noption, that \"s\" can't have embedded \"NUL\" characters and has to have a terminating \"NUL\"\nbyte).\n\nSee also \"isutf8string\", \"isutf8stringflags\", \"isutf8stringloc\",\n\"isutf8stringlocflags\", \"isutf8stringloclen\", \"isutf8stringloclenflags\",\n\"isutf8fixedwidthbufflags\", \"isutf8fixedwidthbuflocflags\",\n\"isutf8fixedwidthbufloclenflags\", \"isstrictutf8string\",\n\"isstrictutf8stringloc\", \"isstrictutf8stringloclen\", \"isc9strictutf8string\",\n\"isc9strictutf8stringloc\", and \"isc9strictutf8stringloclen\".\n\nbool isutf8invariantstring(const U8 * const s, STRLEN len)\n\n\"isutf8invariantstringloc\"\nLike \"isutf8invariantstring\" but upon failure, stores the location of the first UTF-8\nvariant character in the \"ep\" pointer; if all characters are UTF-8 invariant, this\nfunction does not change the contents of *ep.\n\nbool isutf8invariantstringloc(const U8 * const s, STRLEN len,\nconst U8 ep)\n\n\"isutf8string\"\nReturns TRUE if the first \"len\" bytes of string \"s\" form a valid Perl-extended-UTF-8\nstring; returns FALSE otherwise. If \"len\" is 0, it will be calculated using strlen(s)\n(which means if you use this option, that \"s\" can't have embedded \"NUL\" characters and\nhas to have a terminating \"NUL\" byte). Note that all characters being ASCII constitute\n'a valid UTF-8 string'.\n\nThis function considers Perl's extended UTF-8 to be valid. That means that code points\nabove Unicode, surrogates, and non-character code points are considered valid by this\nfunction. Use \"isstrictutf8string\", \"isc9strictutf8string\", or\n\"isutf8stringflags\" to restrict what code points are considered valid.\n\nSee also \"isutf8invariantstring\", \"isutf8invariantstringloc\",\n\"isutf8stringloc\", \"isutf8stringloclen\", \"isutf8fixedwidthbufflags\",\n\"isutf8fixedwidthbuflocflags\", \"isutf8fixedwidthbufloclenflags\",\n\nbool isutf8string(const U8 *s, STRLEN len)\n\n\"isutf8stringflags\"\nReturns TRUE if the first \"len\" bytes of string \"s\" form a valid UTF-8 string, subject to\nthe restrictions imposed by \"flags\"; returns FALSE otherwise. If \"len\" is 0, it will be\ncalculated using strlen(s) (which means if you use this option, that \"s\" can't have\nembedded \"NUL\" characters and has to have a terminating \"NUL\" byte). Note that all\ncharacters being ASCII constitute 'a valid UTF-8 string'.\n\nIf \"flags\" is 0, this gives the same results as \"isutf8string\"; if \"flags\" is\n\"UTF8DISALLOWILLEGALINTERCHANGE\", this gives the same results as\n\"isstrictutf8string\"; and if \"flags\" is \"UTF8DISALLOWILLEGALC9INTERCHANGE\", this\ngives the same results as \"isc9strictutf8string\". Otherwise \"flags\" may be any\ncombination of the \"UTF8DISALLOWfoo\" flags understood by \"utf8ntouvchr\", with the\nsame meanings.\n\nSee also \"isutf8invariantstring\", \"isutf8invariantstringloc\", \"isutf8string\",\n\"isutf8stringloc\", \"isutf8stringlocflags\", \"isutf8stringloclen\",\n\"isutf8stringloclenflags\", \"isutf8fixedwidthbufflags\",\n\"isutf8fixedwidthbuflocflags\", \"isutf8fixedwidthbufloclenflags\",\n\"isstrictutf8string\", \"isstrictutf8stringloc\", \"isstrictutf8stringloclen\",\n\"isc9strictutf8string\", \"isc9strictutf8stringloc\", and\n\"isc9strictutf8stringloclen\".\n\nbool isutf8stringflags(const U8 *s, STRLEN len,\nconst U32 flags)\n\n\"isutf8stringloc\"\nLike \"isutf8string\" but stores the location of the failure (in the case of \"utf8ness\nfailure\") or the location \"s\"+\"len\" (in the case of \"utf8ness success\") in the \"ep\"\npointer.\n\nSee also \"isutf8stringloclen\".\n\nbool isutf8stringloc(const U8 *s, const STRLEN len,\nconst U8 ep)\n\n\"isutf8stringlocflags\"\nLike \"isutf8stringflags\" but stores the location of the failure (in the case of\n\"utf8ness failure\") or the location \"s\"+\"len\" (in the case of \"utf8ness success\") in the\n\"ep\" pointer.\n\nSee also \"isutf8stringloclenflags\".\n\nbool isutf8stringlocflags(const U8 *s, STRLEN len,\nconst U8 ep, const U32 flags)\n\n\"isutf8stringloclen\"\nLike \"isutf8string\" but stores the location of the failure (in the case of \"utf8ness\nfailure\") or the location \"s\"+\"len\" (in the case of \"utf8ness success\") in the \"ep\"\npointer, and the number of UTF-8 encoded characters in the \"el\" pointer.\n\nSee also \"isutf8stringloc\".\n\nbool isutf8stringloclen(const U8 *s, STRLEN len,\nconst U8 ep, STRLEN *el)\n\n\"isutf8stringloclenflags\"\nLike \"isutf8stringflags\" but stores the location of the failure (in the case of\n\"utf8ness failure\") or the location \"s\"+\"len\" (in the case of \"utf8ness success\") in the\n\"ep\" pointer, and the number of UTF-8 encoded characters in the \"el\" pointer.\n\nSee also \"isutf8stringlocflags\".\n\nbool isutf8stringloclenflags(const U8 *s, STRLEN len,\nconst U8 ep, STRLEN *el,\nconst U32 flags)\n\n\"isutf8validpartialchar\"\nReturns 0 if the sequence of bytes starting at \"s\" and looking no further than \"e - 1\" is\nthe UTF-8 encoding, as extended by Perl, for one or more code points. Otherwise, it\nreturns 1 if there exists at least one non-empty sequence of bytes that when appended to\nsequence \"s\", starting at position \"e\" causes the entire sequence to be the well-formed\nUTF-8 of some code point; otherwise returns 0.\n\nIn other words this returns TRUE if \"s\" points to a partial UTF-8-encoded code point.\n\nThis is useful when a fixed-length buffer is being tested for being well-formed UTF-8,\nbut the final few bytes in it don't comprise a full character; that is, it is split\nsomewhere in the middle of the final code point's UTF-8 representation. (Presumably when\nthe buffer is refreshed with the next chunk of data, the new first bytes will complete\nthe partial code point.) This function is used to verify that the final bytes in the\ncurrent buffer are in fact the legal beginning of some code point, so that if they\naren't, the failure can be signalled without having to wait for the next read.\n\nbool isutf8validpartialchar(const U8 * const s0,\nconst U8 * const e)\n\n\"isutf8validpartialcharflags\"\nLike \"isutf8validpartialchar\", it returns a boolean giving whether or not the input\nis a valid UTF-8 encoded partial character, but it takes an extra parameter, \"flags\",\nwhich can further restrict which code points are considered valid.\n\nIf \"flags\" is 0, this behaves identically to \"isutf8validpartialchar\". Otherwise\n\"flags\" can be any combination of the \"UTF8DISALLOWfoo\" flags accepted by\n\"utf8ntouvchr\". If there is any sequence of bytes that can complete the input partial\ncharacter in such a way that a non-prohibited character is formed, the function returns\nTRUE; otherwise FALSE. Non character code points cannot be determined based on partial\ncharacter input. But many of the other possible excluded types can be determined from\njust the first one or two bytes.\n\nbool isutf8validpartialcharflags(const U8 * const s0,\nconst U8 * const e,\nconst U32 flags)\n\n\"LATIN1TONATIVE\"\nReturns the native equivalent of the input Latin-1 code point (including ASCII and\ncontrol characters) given by \"ch\". Thus, LATIN1TONATIVE(66) on EBCDIC platforms\nreturns 194. These each represent the character \"B\" on their respective platforms. On\nASCII platforms no conversion is needed, so this macro expands to just its input, adding\nno time nor space requirements to the implementation.\n\nFor conversion of code points potentially larger than will fit in a character, use\n\"UNITONATIVE\".\n\nU8 LATIN1TONATIVE(U8 ch)\n\n\"NATIVETOLATIN1\"\nReturns the Latin-1 (including ASCII and control characters) equivalent of the input\nnative code point given by \"ch\". Thus, NATIVETOLATIN1(193) on EBCDIC platforms returns\n65. These each represent the character \"A\" on their respective platforms. On ASCII\nplatforms no conversion is needed, so this macro expands to just its input, adding no\ntime nor space requirements to the implementation.\n\nFor conversion of code points potentially larger than will fit in a character, use\n\"NATIVETOUNI\".\n\nU8 NATIVETOLATIN1(U8 ch)\n\n\"NATIVETOUNI\"\nReturns the Unicode equivalent of the input native code point given by \"ch\". Thus,\nNATIVETOUNI(195) on EBCDIC platforms returns 67. These each represent the character\n\"C\" on their respective platforms. On ASCII platforms no conversion is needed, so this\nmacro expands to just its input, adding no time nor space requirements to the\nimplementation.\n\nUV NATIVETOUNI(UV ch)\n\n\"pvunidisplay\"\nBuild to the scalar \"dsv\" a displayable version of the UTF-8 encoded string \"spv\", length\n\"len\", the displayable version being at most \"pvlim\" bytes long (if longer, the rest is\ntruncated and \"...\" will be appended).\n\nThe \"flags\" argument can have \"UNIDISPLAYISPRINT\" set to display isPRINT()able\ncharacters as themselves, \"UNIDISPLAYBACKSLASH\" to display the \"\\\\[nrfta\\\\]\" as the\nbackslashed versions (like \"\\n\") (\"UNIDISPLAYBACKSLASH\" is preferred over\n\"UNIDISPLAYISPRINT\" for \"\\\\\"). \"UNIDISPLAYQQ\" (and its alias \"UNIDISPLAYREGEX\")\nhave both \"UNIDISPLAYBACKSLASH\" and \"UNIDISPLAYISPRINT\" turned on.\n\nAdditionally, there is now \"UNIDISPLAYBACKSPACE\" which allows \"\\b\" for a backspace, but\nonly when \"UNIDISPLAYBACKSLASH\" also is set.\n\nThe pointer to the PV of the \"dsv\" is returned.\n\nSee also \"svunidisplay\".\n\nchar * pvunidisplay(SV *dsv, const U8 *spv, STRLEN len,\nSTRLEN pvlim, UV flags)\n\n\"REPLACEMENTCHARACTERUTF8\"\nThis is a macro that evaluates to a string constant of the UTF-8 bytes that define the\nUnicode REPLACEMENT CHARACTER (U+FFFD) for the platform that perl is compiled on. This\nallows code to use a mnemonic for this character that works on both ASCII and EBCDIC\nplatforms. \"sizeof(REPLACEMENTCHARACTERUTF8) - 1\" can be used to get its length in\nbytes.\n\n\"svcatdecode\"\n\"encoding\" is assumed to be an \"Encode\" object, the PV of \"ssv\" is assumed to be octets\nin that encoding and decoding the input starts from the position which \"(PV + *offset)\"\npointed to. \"dsv\" will be concatenated with the decoded UTF-8 string from \"ssv\".\nDecoding will terminate when the string \"tstr\" appears in decoding output or the input\nends on the PV of \"ssv\". The value which \"offset\" points will be modified to the last\ninput position on \"ssv\".\n\nReturns TRUE if the terminator was found, else returns FALSE.\n\nbool svcatdecode(SV *dsv, SV *encoding, SV *ssv, int *offset,\nchar *tstr, int tlen)\n\n\"svrecodetoutf8\"\n\"encoding\" is assumed to be an \"Encode\" object, on entry the PV of \"sv\" is assumed to be\noctets in that encoding, and \"sv\" will be converted into Unicode (and UTF-8).\n\nIf \"sv\" already is UTF-8 (or if it is not \"POK\"), or if \"encoding\" is not a reference,\nnothing is done to \"sv\". If \"encoding\" is not an \"Encode::XS\" Encoding object, bad\nthings will happen. (See encoding and Encode.)\n\nThe PV of \"sv\" is returned.\n\nchar * svrecodetoutf8(SV *sv, SV *encoding)\n\n\"svunidisplay\"\nBuild to the scalar \"dsv\" a displayable version of the scalar \"sv\", the displayable\nversion being at most \"pvlim\" bytes long (if longer, the rest is truncated and \"...\" will\nbe appended).\n\nThe \"flags\" argument is as in \"pvunidisplay\"().\n\nThe pointer to the PV of the \"dsv\" is returned.\n\nchar * svunidisplay(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)\n\n\"UNICODEISNONCHAR\"\nReturns a boolean as to whether or not \"uv\" is one of the Unicode non-character code\npoints\n\nbool UNICODEISNONCHAR(const UV uv)\n\n\"UNICODEISREPLACEMENT\"\nReturns a boolean as to whether or not \"uv\" is the Unicode REPLACEMENT CHARACTER\n\nbool UNICODEISREPLACEMENT(const UV uv)\n\n\"UNICODEISSUPER\"\nReturns a boolean as to whether or not \"uv\" is above the maximum legal Unicode code point\nof U+10FFFF.\n\nbool UNICODEISSUPER(const UV uv)\n\n\"UNICODEISSURROGATE\"\nReturns a boolean as to whether or not \"uv\" is one of the Unicode surrogate code points\n\nbool UNICODEISSURROGATE(const UV uv)\n\n\"UNICODEREPLACEMENT\"\nEvaluates to 0xFFFD, the code point of the Unicode REPLACEMENT CHARACTER\n\n\"UNITONATIVE\"\nReturns the native equivalent of the input Unicode code point given by \"ch\". Thus,\nUNITONATIVE(68) on EBCDIC platforms returns 196. These each represent the character\n\"D\" on their respective platforms. On ASCII platforms no conversion is needed, so this\nmacro expands to just its input, adding no time nor space requirements to the\nimplementation.\n\nUV UNITONATIVE(UV ch)\n\n\"UTF8CHKSKIP\"\nThis is a safer version of \"UTF8SKIP\", but still not as safe as \"UTF8SAFESKIP\". This\nversion doesn't blindly assume that the input string pointed to by \"s\" is well-formed,\nbut verifies that there isn't a NUL terminating character before the expected end of the\nnext character in \"s\". The length \"UTF8CHKSKIP\" returns stops just before any such\nNUL.\n\nPerl tends to add NULs, as an insurance policy, after the end of strings in SV's, so it\nis likely that using this macro will prevent inadvertent reading beyond the end of the\ninput buffer, even if it is malformed UTF-8.\n\nThis macro is intended to be used by XS modules where the inputs could be malformed, and\nit isn't feasible to restructure to use the safer \"UTF8SAFESKIP\", for example when\ninterfacing with a C library.\n\nSTRLEN UTF8CHKSKIP(char* s)\n\n\"utf8distance\"\nReturns the number of UTF-8 characters between the UTF-8 pointers \"a\" and \"b\".\n\nWARNING: use only if you *know* that the pointers point inside the same UTF-8 buffer.\n\nIV utf8distance(const U8 *a, const U8 *b)\n\n\"utf8hop\"\nReturn the UTF-8 pointer \"s\" displaced by \"off\" characters, either forward (if \"off\" is\npositive) or backward (if negative). \"s\" does not need to be pointing to the starting\nbyte of a character. If it isn't, one count of \"off\" will be used up to get to the start\nof the next character for forward hops, and to the start of the current character for\nnegative ones.\n\nWARNING: Prefer \"utf8hopsafe\" to this one.\n\nDo NOT use this function unless you know \"off\" is within the UTF-8 data pointed to by \"s\"\nand that on entry \"s\" is aligned on the first byte of a character or just after the last\nbyte of a character.\n\nU8 * utf8hop(const U8 *s, SSizet off)\n\n\"utf8hopback\"\nReturn the UTF-8 pointer \"s\" displaced by up to \"off\" characters, backward. \"s\" does not\nneed to be pointing to the starting byte of a character. If it isn't, one count of \"off\"\nwill be used up to get to that start.\n\n\"off\" must be non-positive.\n\n\"s\" must be after or equal to \"start\".\n\nWhen moving backward it will not move before \"start\".\n\nWill not exceed this limit even if the string is not valid \"UTF-8\".\n\nU8 * utf8hopback(const U8 *s, SSizet off, const U8 *start)\n\n\"utf8hopforward\"\nReturn the UTF-8 pointer \"s\" displaced by up to \"off\" characters, forward. \"s\" does not\nneed to be pointing to the starting byte of a character. If it isn't, one count of \"off\"\nwill be used up to get to the start of the next character.\n\n\"off\" must be non-negative.\n\n\"s\" must be before or equal to \"end\".\n\nWhen moving forward it will not move beyond \"end\".\n\nWill not exceed this limit even if the string is not valid \"UTF-8\".\n\nU8 * utf8hopforward(const U8 *s, SSizet off, const U8 *end)\n\n\"utf8hopsafe\"\nReturn the UTF-8 pointer \"s\" displaced by up to \"off\" characters, either forward or\nbackward. \"s\" does not need to be pointing to the starting byte of a character. If it\nisn't, one count of \"off\" will be used up to get to the start of the next character for\nforward hops, and to the start of the current character for negative ones.\n\nWhen moving backward it will not move before \"start\".\n\nWhen moving forward it will not move beyond \"end\".\n\nWill not exceed those limits even if the string is not valid \"UTF-8\".\n\nU8 * utf8hopsafe(const U8 *s, SSizet off, const U8 *start,\nconst U8 *end)\n\n\"UTF8ISINVARIANT\"\nEvaluates to 1 if the byte \"c\" represents the same character when encoded in UTF-8 as\nwhen not; otherwise evaluates to 0. UTF-8 invariant characters can be copied as-is when\nconverting to/from UTF-8, saving time.\n\nIn spite of the name, this macro gives the correct result if the input string from which\n\"c\" comes is not encoded in UTF-8.\n\nSee \"UVCHRISINVARIANT\" for checking if a UV is invariant.\n\nbool UTF8ISINVARIANT(char c)\n\n\"UTF8ISNONCHAR\"\nEvaluates to non-zero if the first few bytes of the string starting at \"s\" and looking no\nfurther than \"e - 1\" are well-formed UTF-8 that represents one of the Unicode non-\ncharacter code points; otherwise it evaluates to 0. If non-zero, the value gives how\nmany bytes starting at \"s\" comprise the code point's representation.\n\nbool UTF8ISNONCHAR(const U8 *s, const U8 *e)\n\n\"UTF8ISREPLACEMENT\"\nEvaluates to non-zero if the first few bytes of the string starting at \"s\" and looking no\nfurther than \"e - 1\" are well-formed UTF-8 that represents the Unicode REPLACEMENT\nCHARACTER; otherwise it evaluates to 0. If non-zero, the value gives how many bytes\nstarting at \"s\" comprise the code point's representation.\n\nbool UTF8ISREPLACEMENT(const U8 *s, const U8 *e)\n\n\"UTF8ISSUPER\"\nRecall that Perl recognizes an extension to UTF-8 that can encode code points larger than\nthe ones defined by Unicode, which are 0..0x10FFFF.\n\nThis macro evaluates to non-zero if the first few bytes of the string starting at \"s\" and\nlooking no further than \"e - 1\" are from this UTF-8 extension; otherwise it evaluates to\n0. If non-zero, the return is how many bytes starting at \"s\" comprise the code point's\nrepresentation.\n\n0 is returned if the bytes are not well-formed extended UTF-8, or if they represent a\ncode point that cannot fit in a UV on the current platform. Hence this macro can give\ndifferent results when run on a 64-bit word machine than on one with a 32-bit word size.\n\nNote that it is illegal in Perl to have code points that are larger than what can fit in\nan IV on the current machine; and illegal in Unicode to have any that this macro matches\n\nbool UTF8ISSUPER(const U8 *s, const U8 *e)\n\n\"UTF8ISSURROGATE\"\nEvaluates to non-zero if the first few bytes of the string starting at \"s\" and looking no\nfurther than \"e - 1\" are well-formed UTF-8 that represents one of the Unicode surrogate\ncode points; otherwise it evaluates to 0. If non-zero, the value gives how many bytes\nstarting at \"s\" comprise the code point's representation.\n\nbool UTF8ISSURROGATE(const U8 *s, const U8 *e)\n\n\"utf8length\"\nReturns the number of characters in the sequence of UTF-8-encoded bytes starting at \"s\"\nand ending at the byte just before \"e\". If and point to the same place, it\nreturns 0 with no warning raised.\n\nIf \"e < s\" or if the scan would end up past \"e\", it raises a UTF8 warning and returns the\nnumber of valid characters.\n\nSTRLEN utf8length(const U8 *s0, const U8 *e)\n\n\"UTF8MAXBYTES\"\nThe maximum width of a single UTF-8 encoded character, in bytes.\n\nNOTE: Strictly speaking Perl's UTF-8 should not be called UTF-8 since UTF-8 is an\nencoding of Unicode, and Unicode's upper limit, 0x10FFFF, can be expressed with 4 bytes.\nHowever, Perl thinks of UTF-8 as a way to encode non-negative integers in a binary\nformat, even those above Unicode.\n\n\"UTF8MAXBYTESCASE\"\nThe maximum number of UTF-8 bytes a single Unicode character can\nuppercase/lowercase/titlecase/fold into.\n\n\"utf8nesst\"\nThis typedef is used by several core functions that return PV strings, to indicate the\nUTF-8ness of those strings.\n\n(If you write a new function, you probably should instead return the PV in an SV with the\nUTF-8 flag of the SV properly set, rather than use this mechanism.)\n\nThe possible values this can be are:\n\n\"UTF8NESSYES\"\nThis means the string definitely should be treated as a sequence of UTF-8-encoded\ncharacters.\n\nMost code that needs to handle this typedef should be of the form:\n\nif (utf8nessflag == UTF8NESSYES) {\ntreat as utf8; // like turning on an SV UTF-8 flag\n}\n\n\"UTF8NESSNO\"\nThis means the string definitely should be treated as a sequence of bytes, not\nencoded as UTF-8.\n\n\"UTF8NESSIMMATERIAL\"\nThis means it is equally valid to treat the string as bytes, or as UTF-8 characters;\nuse whichever way you want. This happens when the string consists entirely of\ncharacters which have the same representation whether encoded in UTF-8 or not.\n\n\"UTF8NESSUNKNOWN\"\nThis means it is unknown how the string should be treated. No core function will\never return this value to a non-core caller. Instead, it is used by the caller to\ninitialize a variable to a non-legal value. A typical call will look like:\n\nutf8nesst stringisutf8 = UTF8NESSUNKNOWN\nconst char * string = foo(arg1, arg2, ..., &stringisutf8);\nif (stringisutf8 == UTF8NESSYES) {\ndo something for UTF-8;\n}\n\nThe following relationships hold between the enum values:\n\n\"0 <= enum value <= UTF8NESSIMMATERIAL\"\nthe string may be treated in code as non-UTF8\n\n\"UTF8NESSIMMATERIAL <= . The difference\nbetween traditional strictness and C9 strictness is that the latter does not forbid non-\ncharacter code points. (They are still discouraged, however.) For more discussion see\n\"Noncharacter code points\" in perlunicode.\n\nThe flags \"UTF8WARNILLEGALINTERCHANGE\", \"UTF8WARNILLEGALC9INTERCHANGE\",\n\"UTF8WARNSURROGATE\", \"UTF8WARNNONCHAR\", and \"UTF8WARNSUPER\" will cause warning\nmessages to be raised for their respective categories, but otherwise the code points are\nconsidered valid (not malformations). To get a category to both be treated as a\nmalformation and raise a warning, specify both the WARN and DISALLOW flags. (But note\nthat warnings are not raised if lexically disabled nor if \"UTF8CHECKONLY\" is also\nspecified.)\n\nExtremely high code points were never specified in any standard, and require an extension\nto UTF-8 to express, which Perl does. It is likely that programs written in something\nother than Perl would not be able to read files that contain these; nor would Perl\nunderstand files written by something that uses a different extension. For these\nreasons, there is a separate set of flags that can warn and/or disallow these extremely\nhigh code points, even if other above-Unicode ones are accepted. They are the\n\"UTF8WARNPERLEXTENDED\" and \"UTF8DISALLOWPERLEXTENDED\" flags. For more information\nsee \"UTF8GOTPERLEXTENDED\". Of course \"UTF8DISALLOWSUPER\" will treat all above-\nUnicode code points, including these, as malformations. (Note that the Unicode standard\nconsiders anything above 0x10FFFF to be illegal, but there are standards predating it\nthat allow up to 0x7FFFFFFF (231 -1))\n\nA somewhat misleadingly named synonym for \"UTF8WARNPERLEXTENDED\" is retained for\nbackward compatibility: \"UTF8WARNABOVE31BIT\". Similarly,\n\"UTF8DISALLOWABOVE31BIT\" is usable instead of the more accurately named\n\"UTF8DISALLOWPERLEXTENDED\". The names are misleading because these flags can apply to\ncode points that actually do fit in 31 bits. This happens on EBCDIC platforms, and\nsometimes when the overlong malformation is also present. The new names accurately\ndescribe the situation in all cases.\n\nAll other code points corresponding to Unicode characters, including private use and\nthose yet to be assigned, are never considered malformed and never warn.\n\nUV utf8ntouvchr(const U8 *s, STRLEN curlen, STRLEN *retlen,\nconst U32 flags)\n\n\"utf8ntouvchrerror\"\nTHIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES. Most code should\nuse \"utf8touvchrbuf\"() rather than call this directly.\n\nThis function is for code that needs to know what the precise malformation(s) are when an\nerror is found. If you also need to know the generated warning messages, use\n\"utf8ntouvchrmsgs\"() instead.\n\nIt is like \"utf8ntouvchr\" but it takes an extra parameter placed after all the others,\n\"errors\". If this parameter is 0, this function behaves identically to \"utf8ntouvchr\".\nOtherwise, \"errors\" should be a pointer to a \"U32\" variable, which this function sets to\nindicate any errors found. Upon return, if *errors is 0, there were no errors found.\nOtherwise, *errors is the bit-wise \"OR\" of the bits described in the list below. Some of\nthese bits will be set if a malformation is found, even if the input \"flags\" parameter\nindicates that the given malformation is allowed; those exceptions are noted:\n\n\"UTF8GOTPERLEXTENDED\"\nThe input sequence is not standard UTF-8, but a Perl extension. This bit is set only\nif the input \"flags\" parameter contains either the \"UTF8DISALLOWPERLEXTENDED\" or\nthe \"UTF8WARNPERLEXTENDED\" flags.\n\nCode points above 0x7FFFFFFF (231 - 1) were never specified in any standard, and\nso some extension must be used to express them. Perl uses a natural extension to\nUTF-8 to represent the ones up to 236-1, and invented a further extension to\nrepresent even higher ones, so that any code point that fits in a 64-bit word can be\nrepresented. Text using these extensions is not likely to be portable to non-Perl\ncode. We lump both of these extensions together and refer to them as Perl extended\nUTF-8. There exist other extensions that people have invented, incompatible with\nPerl's.\n\nOn EBCDIC platforms starting in Perl v5.24, the Perl extension for representing\nextremely high code points kicks in at 0x3FFFFFFF (230 -1), which is lower than on\nASCII. Prior to that, code points 231 and higher were simply unrepresentable, and\na different, incompatible method was used to represent code points between 230 and\n231 - 1.\n\nOn both platforms, ASCII and EBCDIC, \"UTF8GOTPERLEXTENDED\" is set if Perl extended\nUTF-8 is used.\n\nIn earlier Perls, this bit was named \"UTF8GOTABOVE31BIT\", which you still may use\nfor backward compatibility. That name is misleading, as this flag may be set when\nthe code point actually does fit in 31 bits. This happens on EBCDIC platforms, and\nsometimes when the overlong malformation is also present. The new name accurately\ndescribes the situation in all cases.\n\n\"UTF8GOTCONTINUATION\"\nThe input sequence was malformed in that the first byte was a UTF-8 continuation\nbyte.\n\n\"UTF8GOTEMPTY\"\nThe input \"curlen\" parameter was 0.\n\n\"UTF8GOTLONG\"\nThe input sequence was malformed in that there is some other sequence that evaluates\nto the same code point, but that sequence is shorter than this one.\n\nUntil Unicode 3.1, it was legal for programs to accept this malformation, but it was\ndiscovered that this created security issues.\n\n\"UTF8GOTNONCHAR\"\nThe code point represented by the input UTF-8 sequence is for a Unicode non-character\ncode point. This bit is set only if the input \"flags\" parameter contains either the\n\"UTF8DISALLOWNONCHAR\" or the \"UTF8WARNNONCHAR\" flags.\n\n\"UTF8GOTNONCONTINUATION\"\nThe input sequence was malformed in that a non-continuation type byte was found in a\nposition where only a continuation type one should be. See also \"UTF8GOTSHORT\".\n\n\"UTF8GOTOVERFLOW\"\nThe input sequence was malformed in that it is for a code point that is not\nrepresentable in the number of bits available in an IV on the current platform.\n\n\"UTF8GOTSHORT\"\nThe input sequence was malformed in that \"curlen\" is smaller than required for a\ncomplete sequence. In other words, the input is for a partial character sequence.\n\n\"UTF8GOTSHORT\" and \"UTF8GOTNONCONTINUATION\" both indicate a too short sequence.\nThe difference is that \"UTF8GOTNONCONTINUATION\" indicates always that there is an\nerror, while \"UTF8GOTSHORT\" means that an incomplete sequence was looked at. If\nno other flags are present, it means that the sequence was valid as far as it went.\nDepending on the application, this could mean one of three things:\n\n• The \"curlen\" length parameter passed in was too small, and the function was\nprevented from examining all the necessary bytes.\n\n• The buffer being looked at is based on reading data, and the data received so far\nstopped in the middle of a character, so that the next read will read the\nremainder of this character. (It is up to the caller to deal with the split\nbytes somehow.)\n\n• This is a real error, and the partial sequence is all we're going to get.\n\n\"UTF8GOTSUPER\"\nThe input sequence was malformed in that it is for a non-Unicode code point; that is,\none above the legal Unicode maximum. This bit is set only if the input \"flags\"\nparameter contains either the \"UTF8DISALLOWSUPER\" or the \"UTF8WARNSUPER\" flags.\n\n\"UTF8GOTSURROGATE\"\nThe input sequence was malformed in that it is for a -Unicode UTF-16 surrogate code\npoint. This bit is set only if the input \"flags\" parameter contains either the\n\"UTF8DISALLOWSURROGATE\" or the \"UTF8WARNSURROGATE\" flags.\n\nTo do your own error handling, call this function with the \"UTF8CHECKONLY\" flag to\nsuppress any warnings, and then examine the *errors return.\n\nUV utf8ntouvchrerror(const U8 *s, STRLEN curlen,\nSTRLEN *retlen, const U32 flags,\nU32 *errors)\n\n\"utf8ntouvchrmsgs\"\nTHIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES. Most code should\nuse \"utf8touvchrbuf\"() rather than call this directly.\n\nThis function is for code that needs to know what the precise malformation(s) are when an\nerror is found, and wants the corresponding warning and/or error messages to be returned\nto the caller rather than be displayed. All messages that would have been displayed if\nall lexical warnings are enabled will be returned.\n\nIt is just like \"utf8ntouvchrerror\" but it takes an extra parameter placed after all\nthe others, \"msgs\". If this parameter is 0, this function behaves identically to\n\"utf8ntouvchrerror\". Otherwise, \"msgs\" should be a pointer to an \"AV *\" variable, in\nwhich this function creates a new AV to contain any appropriate messages. The elements\nof the array are ordered so that the first message that would have been displayed is in\nthe 0th element, and so on. Each element is a hash with three key-value pairs, as\nfollows:\n\n\"text\"\nThe text of the message as a \"SVpv\".\n\n\"warncategories\"\nThe warning category (or categories) packed into a \"SVuv\".\n\n\"flag\"\nA single flag bit associated with this message, in a \"SVuv\". The bit corresponds to\nsome bit in the *errors return value, such as \"UTF8GOTLONG\".\n\nIt's important to note that specifying this parameter as non-null will cause any warnings\nthis function would otherwise generate to be suppressed, and instead be placed in *msgs.\nThe caller can check the lexical warnings state (or not) when choosing what to do with\nthe returned messages.\n\nIf the flag \"UTF8CHECKONLY\" is passed, no warnings are generated, and hence no AV is\ncreated.\n\nThe caller, of course, is responsible for freeing any returned AV.\n\nUV utf8ntouvchrmsgs(const U8 *s, STRLEN curlen,\nSTRLEN *retlen, const U32 flags,\nU32 *errors, AV msgs)\n\n\"UTF8SAFESKIP\"\nreturns 0 if \"s >= e\"; otherwise returns the number of bytes in the UTF-8 encoded\ncharacter whose first byte is pointed to by \"s\". But it never returns beyond \"e\". On\nDEBUGGING builds, it asserts that \"s <= e\".\n\nSTRLEN UTF8SAFESKIP(char* s, char* e)\n\n\"UTF8SKIP\"\nreturns the number of bytes a non-malformed UTF-8 encoded character whose first (perhaps\nonly) byte is pointed to by \"s\".\n\nIf there is a possibility of malformed input, use instead:\n\n\"UTF8SAFESKIP\" if you know the maximum ending pointer in the buffer pointed to by \"s\";\nor\n\"UTF8CHKSKIP\" if you don't know it.\n\nIt is better to restructure your code so the end pointer is passed down so that you know\nwhat it actually is at the point of this call, but if that isn't possible,\n\"UTF8CHKSKIP\" can minimize the chance of accessing beyond the end of the input buffer.\n\nSTRLEN UTF8SKIP(char* s)\n\n\"UTF8SKIP\"\nThis is a synonym for \"UTF8SKIP\"\n\nSTRLEN UTF8SKIP(char* s)\n\n\"utf8tobytes\"\nNOTE: \"utf8tobytes\" is experimental and may change or be removed without notice.\n\nConverts a string \"s\" of length *lenp from UTF-8 into native byte encoding. Unlike\n\"bytestoutf8\", this over-writes the original string, and updates *lenp to contain the\nnew length. Returns zero on failure (leaving \"s\" unchanged) setting *lenp to -1.\n\nUpon successful return, the number of variants in the string can be computed by having\nsaved the value of *lenp before the call, and subtracting the after-call value of *lenp\nfrom it.\n\nIf you need a copy of the string, see \"bytesfromutf8\".\n\nU8 * utf8tobytes(U8 *s, STRLEN *lenp)\n\n\"utf8touvchr\"\n\"DEPRECATED!\" It is planned to remove \"utf8touvchr\" from a future release of Perl. Do\nnot use it for new code; remove it from existing code.\n\nReturns the native code point of the first character in the string \"s\" which is assumed\nto be in UTF-8 encoding; \"retlen\" will be set to the length, in bytes, of that character.\n\nSome, but not all, UTF-8 malformations are detected, and in fact, some malformed input\ncould cause reading beyond the end of the input buffer, which is why this function is\ndeprecated. Use \"utf8touvchrbuf\" instead.\n\nIf \"s\" points to one of the detected malformations, and UTF8 warnings are enabled, zero\nis returned and *retlen is set (if \"retlen\" isn't \"NULL\") to -1. If those warnings are\noff, the computed value if well-defined (or the Unicode REPLACEMENT CHARACTER, if not) is\nsilently returned, and *retlen is set (if \"retlen\" isn't NULL) so that (\"s\" + *retlen) is\nthe next possible position in \"s\" that could begin a non-malformed character. See\n\"utf8ntouvchr\" for details on when the REPLACEMENT CHARACTER is returned.\n\nUV utf8touvchr(const U8 *s, STRLEN *retlen)\n\n\"utf8touvchrbuf\"\nReturns the native code point of the first character in the string \"s\" which is assumed\nto be in UTF-8 encoding; \"send\" points to 1 beyond the end of \"s\". *retlen will be set\nto the length, in bytes, of that character.\n\nIf \"s\" does not point to a well-formed UTF-8 character and UTF8 warnings are enabled,\nzero is returned and *retlen is set (if \"retlen\" isn't \"NULL\") to -1. If those warnings\nare off, the computed value, if well-defined (or the Unicode REPLACEMENT CHARACTER if\nnot), is silently returned, and *retlen is set (if \"retlen\" isn't \"NULL\") so that\n(\"s\" + *retlen) is the next possible position in \"s\" that could begin a non-malformed\ncharacter. See \"utf8ntouvchr\" for details on when the REPLACEMENT CHARACTER is\nreturned.\n\nUV utf8touvchrbuf(const U8 *s, const U8 *send, STRLEN *retlen)\n\n\"UVCHRISINVARIANT\"\nEvaluates to 1 if the representation of code point \"cp\" is the same whether or not it is\nencoded in UTF-8; otherwise evaluates to 0. UTF-8 invariant characters can be copied as-\nis when converting to/from UTF-8, saving time. \"cp\" is Unicode if above 255; otherwise\nis platform-native.\n\nbool UVCHRISINVARIANT(UV cp)\n\n\"UVCHRSKIP\"\nreturns the number of bytes required to represent the code point \"cp\" when encoded as\nUTF-8. \"cp\" is a native (ASCII or EBCDIC) code point if less than 255; a Unicode code\npoint otherwise.\n\nSTRLEN UVCHRSKIP(UV cp)\n\n\"uvchrtoutf8flags\"\nAdds the UTF-8 representation of the native code point \"uv\" to the end of the string \"d\";\n\"d\" should have at least \"UVCHRSKIP(uv)+1\" (up to \"UTF8MAXBYTES+1\") free bytes\navailable. The return value is the pointer to the byte after the end of the new\ncharacter. In other words,\n\nd = uvchrtoutf8flags(d, uv, flags);\n\nor, in most cases,\n\nd = uvchrtoutf8flags(d, uv, 0);\n\nThis is the Unicode-aware way of saying\n\n*(d++) = uv;\n\nIf \"flags\" is 0, this function accepts any code point from 0..\"IVMAX\" as input.\n\"IVMAX\" is typically 0x7FFFFFFF in a 32-bit word.\n\nSpecifying \"flags\" can further restrict what is allowed and not warned on, as follows:\n\nIf \"uv\" is a Unicode surrogate code point and \"UNICODEWARNSURROGATE\" is set, the\nfunction will raise a warning, provided UTF8 warnings are enabled. If instead\n\"UNICODEDISALLOWSURROGATE\" is set, the function will fail and return NULL. If both\nflags are set, the function will both warn and return NULL.\n\nSimilarly, the \"UNICODEWARNNONCHAR\" and \"UNICODEDISALLOWNONCHAR\" flags affect how the\nfunction handles a Unicode non-character.\n\nAnd likewise, the \"UNICODEWARNSUPER\" and \"UNICODEDISALLOWSUPER\" flags affect the\nhandling of code points that are above the Unicode maximum of 0x10FFFF. Languages other\nthan Perl may not be able to accept files that contain these.\n\nThe flag \"UNICODEWARNILLEGALINTERCHANGE\" selects all three of the above WARN flags;\nand \"UNICODEDISALLOWILLEGALINTERCHANGE\" selects all three DISALLOW flags.\n\"UNICODEDISALLOWILLEGALINTERCHANGE\" restricts the allowed inputs to the strict UTF-8\ntraditionally defined by Unicode. Similarly, \"UNICODEWARNILLEGALC9INTERCHANGE\" and\n\"UNICODEDISALLOWILLEGALC9INTERCHANGE\" are shortcuts to select the above-Unicode and\nsurrogate flags, but not the non-character ones, as defined in Unicode Corrigendum #9\n. See \"Noncharacter code points\" in\nperlunicode.\n\nExtremely high code points were never specified in any standard, and require an extension\nto UTF-8 to express, which Perl does. It is likely that programs written in something\nother than Perl would not be able to read files that contain these; nor would Perl\nunderstand files written by something that uses a different extension. For these\nreasons, there is a separate set of flags that can warn and/or disallow these extremely\nhigh code points, even if other above-Unicode ones are accepted. They are the\n\"UNICODEWARNPERLEXTENDED\" and \"UNICODEDISALLOWPERLEXTENDED\" flags. For more\ninformation see \"UTF8GOTPERLEXTENDED\". Of course \"UNICODEDISALLOWSUPER\" will treat\nall above-Unicode code points, including these, as malformations. (Note that the Unicode\nstandard considers anything above 0x10FFFF to be illegal, but there are standards\npredating it that allow up to 0x7FFFFFFF (231 -1))\n\nA somewhat misleadingly named synonym for \"UNICODEWARNPERLEXTENDED\" is retained for\nbackward compatibility: \"UNICODEWARNABOVE31BIT\". Similarly,\n\"UNICODEDISALLOWABOVE31BIT\" is usable instead of the more accurately named\n\"UNICODEDISALLOWPERLEXTENDED\". The names are misleading because on EBCDIC\nplatforms,these flags can apply to code points that actually do fit in 31 bits. The new\nnames accurately describe the situation in all cases.\n\nU8 * uvchrtoutf8flags(U8 *d, UV uv, UV flags)\n\n\"uvchrtoutf8flagsmsgs\"\nTHIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES.\n\nMost code should use \"\"uvchrtoutf8flags\"()\" rather than call this directly.\n\nThis function is for code that wants any warning and/or error messages to be returned to\nthe caller rather than be displayed. All messages that would have been displayed if all\nlexical warnings are enabled will be returned.\n\nIt is just like \"uvchrtoutf8flags\" but it takes an extra parameter placed after all\nthe others, \"msgs\". If this parameter is 0, this function behaves identically to\n\"uvchrtoutf8flags\". Otherwise, \"msgs\" should be a pointer to an \"HV *\" variable, in\nwhich this function creates a new HV to contain any appropriate messages. The hash has\nthree key-value pairs, as follows:\n\n\"text\"\nThe text of the message as a \"SVpv\".\n\n\"warncategories\"\nThe warning category (or categories) packed into a \"SVuv\".\n\n\"flag\"\nA single flag bit associated with this message, in a \"SVuv\". The bit corresponds to\nsome bit in the *errors return value, such as \"UNICODEGOTSURROGATE\".\n\nIt's important to note that specifying this parameter as non-null will cause any warnings\nthis function would otherwise generate to be suppressed, and instead be placed in *msgs.\nThe caller can check the lexical warnings state (or not) when choosing what to do with\nthe returned messages.\n\nThe caller, of course, is responsible for freeing any returned HV.\n\nU8 * uvchrtoutf8flagsmsgs(U8 *d, UV uv, UV flags, HV msgs)\n\n\"uvchrtoutf8\"\nAdds the UTF-8 representation of the native code point \"uv\" to the end of the string \"d\";\n\"d\" should have at least \"UVCHRSKIP(uv)+1\" (up to \"UTF8MAXBYTES+1\") free bytes\navailable. The return value is the pointer to the byte after the end of the new\ncharacter. In other words,\n\nd = uvchrtoutf8(d, uv);\n\nis the recommended wide native character-aware way of saying\n\n*(d++) = uv;\n\nThis function accepts any code point from 0..\"IVMAX\" as input. \"IVMAX\" is typically\n0x7FFFFFFF in a 32-bit word.\n\nIt is possible to forbid or warn on non-Unicode code points, or those that may be\nproblematic by using \"uvchrtoutf8flags\".\n\nU8 * uvchrtoutf8(U8 *d, UV uv)\n", "subsections": [] }, "Utility Functions": { "content": "\"CARRAYEND\"\nReturns a pointer to one element past the final element of the input C array.\n\nvoid * CARRAYEND(void *a)\n\n\"CARRAYLENGTH\"\nReturns the number of elements in the input C array (so you want your zero-based indices\nto be less than but not equal to).\n\nSTRLEN CARRAYLENGTH(void *a)\n\n\"getcwdsv\"\nFill \"sv\" with current working directory\n\nint getcwdsv(SV *sv)\n\n\"INPERLCOMPILETIME\"\nReturns 1 if this macro is being called during the compilation phase of the program;\notherwise 0;\n\nbool INPERLCOMPILETIME\n\n\"INPERLRUNTIME\"\nReturns 1 if this macro is being called during the execution phase of the program;\notherwise 0;\n\nbool INPERLRUNTIME\n\n\"ISSAFESYSCALL\"\nSame as \"issafesyscall\".\n\nbool ISSAFESYSCALL(NN const char *pv, STRLEN len,\nNN const char *what, NN const char *opname)\n\n\"issafesyscall\"\nTest that the given \"pv\" (with length \"len\") doesn't contain any internal \"NUL\"\ncharacters. If it does, set \"errno\" to \"ENOENT\", optionally warn using the \"syscalls\"\ncategory, and return FALSE.\n\nReturn TRUE if the name is safe.\n\n\"what\" and \"opname\" are used in any warning.\n\nUsed by the ISSAFESYSCALL() macro.\n\nbool issafesyscall(const char *pv, STRLEN len,\nconst char *what, const char *opname)\n\n\"mysetenv\"\nA wrapper for the C library setenv(3). Don't use the latter, as the perl version has\ndesirable safeguards\n\nvoid mysetenv(const char *nam, const char *val)\n\n\"newPADxVOP\"\nConstructs, checks and returns an op containing a pad offset. \"type\" is the opcode,\nwhich should be one of \"OPPADSV\", \"OPPADAV\", \"OPPADHV\" or \"OPPADCV\". The returned op\nwill have the \"optarg\" field set by the \"padix\" argument.\n\nThis is convenient when constructing a large optree in nested function calls, as it\navoids needing to store the pad op directly to set the \"optarg\" field as a side-effect.\nFor example\n\no = opappendelem(OPLINESEQ, o,\nnewPADxVOP(OPPADSV, 0, padix));\n\nOP * newPADxVOP(I32 type, I32 flags, PADOFFSET padix)\n\n\"phasename\"\nReturns the given phase's name as a NUL-terminated string.\n\nFor example, to print a stack trace that includes the current interpreter phase you might\ndo:\n\nconst char* phasename = phasename(PLphase);\nmess(\"This is weird. (Perl phase: %s)\", phasename);\n\nconst char * const phasename(enum perlphase)\n\n\"Poison\"\nPoisonWith(0xEF) for catching access to freed memory.\n\nvoid Poison(void* dest, int nitems, type)\n\n\"PoisonFree\"\nPoisonWith(0xEF) for catching access to freed memory.\n\nvoid PoisonFree(void* dest, int nitems, type)\n\n\"PoisonNew\"\nPoisonWith(0xAB) for catching access to allocated but uninitialized memory.\n\nvoid PoisonNew(void* dest, int nitems, type)\n\n\"PoisonWith\"\nFill up memory with a byte pattern (a byte repeated over and over again) that hopefully\ncatches attempts to access uninitialized memory.\n\nvoid PoisonWith(void* dest, int nitems, type, U8 byte)\n\n\"StructCopy\"\nThis is an architecture-independent macro to copy one structure to another.\n\nvoid StructCopy(type *src, type *dest, type)\n\n\"svdestroyable\"\nDummy routine which reports that object can be destroyed when there is no sharing module\npresent. It ignores its single SV argument, and returns 'true'. Exists to avoid test\nfor a \"NULL\" function pointer and because it could potentially warn under some level of\nstrict-ness.\n\nbool svdestroyable(SV *sv)\n\n\"svnosharing\"\nDummy routine which \"shares\" an SV when there is no sharing module present. Or \"locks\"\nit. Or \"unlocks\" it. In other words, ignores its single SV argument. Exists to avoid\ntest for a \"NULL\" function pointer and because it could potentially warn under some level\nof strict-ness.\n\nvoid svnosharing(SV *sv)\n", "subsections": [] }, "Versioning": { "content": "\"newversion\"\nReturns a new version object based on the passed in SV:\n\nSV *sv = newversion(SV *ver);\n\nDoes not alter the passed in ver SV. See \"upgversion\" if you want to upgrade the SV.\n\nSV * newversion(SV *ver)\n\n\"PERLREVISION\"\n\"DEPRECATED!\" It is planned to remove \"PERLREVISION\" from a future release of Perl. Do\nnot use it for new code; remove it from existing code.\n\nThe major number component of the perl interpreter currently being compiled or executing.\nThis has been 5 from 1993 into 2020.\n\nInstead use one of the version comparison macros. See \"PERLVERSIONEQ\".\n\n\"PERLSUBVERSION\"\n\"DEPRECATED!\" It is planned to remove \"PERLSUBVERSION\" from a future release of Perl.\nDo not use it for new code; remove it from existing code.\n\nThe micro number component of the perl interpreter currently being compiled or executing.\nIn stable releases this gives the dot release number for maintenance updates. In\ndevelopment releases this gives a tag for a snapshot of the status at various points in\nthe development cycle.\n\nInstead use one of the version comparison macros. See \"PERLVERSIONEQ\".\n\n\"PERLVERSION\"\n\"DEPRECATED!\" It is planned to remove \"PERLVERSION\" from a future release of Perl. Do\nnot use it for new code; remove it from existing code.\n\nThe minor number component of the perl interpreter currently being compiled or executing.\nBetween 1993 into 2020, this has ranged from 0 to 33.\n\nInstead use one of the version comparison macros. See \"PERLVERSIONEQ\".\n\n\"PERLVERSIONEQ\"\n\"PERLVERSIONGE\"\n\"PERLVERSIONGT\"\n\"PERLVERSIONLE\"\n\"PERLVERSIONLT\"\n\"PERLVERSIONNE\"\nReturns whether or not the perl currently being compiled has the specified relationship\nto the perl given by the parameters. For example,\n\n#if PERLVERSIONGT(5,24,2)\ncode that will only be compiled on perls after v5.24.2\n#else\nfallback code\n#endif\n\nNote that this is usable in making compile-time decisions\n\nYou may use the special value '*' for the final number to mean ALL possible values for\nit. Thus,\n\n#if PERLVERSIONEQ(5,31,'*')\n\nmeans all perls in the 5.31 series. And\n\n#if PERLVERSIONNE(5,24,'*')\n\nmeans all perls EXCEPT 5.24 ones. And\n\n#if PERLVERSIONLE(5,9,'*')\n\nis effectively\n\n#if PERLVERSIONLT(5,10,0)\n\nThis means you don't have to think so much when converting from the existing deprecated\n\"PERLVERSION\" to using this macro:\n\n#if PERLVERSION <= 9\n\nbecomes\n\n#if PERLVERSIONLE(5,9,'*')\n\nbool PERLVERSIONEQ(const U8 major, const U8 minor,\nconst U8 patch)\n\n\"prescanversion\"\nValidate that a given string can be parsed as a version object, but doesn't actually\nperform the parsing. Can use either strict or lax validation rules. Can optionally set\na number of hint variables to save the parsing code some time when tokenizing.\n\nconst char * prescanversion(const char *s, bool strict,\nconst char errstr, bool *sqv,\nint *ssawdecimal, int *swidth,\nbool *salpha)\n\n\"scanversion\"\nReturns a pointer to the next character after the parsed version string, as well as\nupgrading the passed in SV to an RV.\n\nFunction must be called with an already existing SV like\n\nsv = newSV(0);\ns = scanversion(s, SV *sv, bool qv);\n\nPerforms some preprocessing to the string to ensure that it has the correct\ncharacteristics of a version. Flags the object if it contains an underscore (which\ndenotes this is an alpha version). The boolean qv denotes that the version should be\ninterpreted as if it had multiple decimals, even if it doesn't.\n\nconst char * scanversion(const char *s, SV *rv, bool qv)\n\n\"upgversion\"\nIn-place upgrade of the supplied SV to a version object.\n\nSV *sv = upgversion(SV *sv, bool qv);\n\nReturns a pointer to the upgraded SV. Set the boolean qv if you want to force this SV to\nbe interpreted as an \"extended\" version.\n\nSV * upgversion(SV *ver, bool qv)\n\n\"vcmp\"\nVersion object aware cmp. Both operands must already have been converted into version\nobjects.\n\nint vcmp(SV *lhv, SV *rhv)\n\n\"vnormal\"\nAccepts a version object and returns the normalized string representation. Call like:\n\nsv = vnormal(rv);\n\nNOTE: you can pass either the object directly or the SV contained within the RV.\n\nThe SV returned has a refcount of 1.\n\nSV * vnormal(SV *vs)\n\n\"vnumify\"\nAccepts a version object and returns the normalized floating point representation. Call\nlike:\n\nsv = vnumify(rv);\n\nNOTE: you can pass either the object directly or the SV contained within the RV.\n\nThe SV returned has a refcount of 1.\n\nSV * vnumify(SV *vs)\n\n\"vstringify\"\nIn order to maintain maximum compatibility with earlier versions of Perl, this function\nwill return either the floating point notation or the multiple dotted notation, depending\non whether the original version contained 1 or more dots, respectively.\n\nThe SV returned has a refcount of 1.\n\nSV * vstringify(SV *vs)\n\n\"vverify\"\nValidates that the SV contains valid internal structure for a version object. It may be\npassed either the version object (RV) or the hash itself (HV). If the structure is\nvalid, it returns the HV. If the structure is invalid, it returns NULL.\n\nSV *hv = vverify(sv);\n\nNote that it only confirms the bare minimum structure (so as not to get confused by\nderived classes which may contain additional hash entries):\n\n• The SV is an HV or a reference to an HV\n\n• The hash contains a \"version\" key\n\n• The \"version\" key has a reference to an AV as its value\n\nSV * vverify(SV *vs)\n", "subsections": [] }, "Warning and Dieing": { "content": "In all these calls, the \"U32 wn\" parameters are warning category constants. You can see the\nones currently available in \"Category Hierarchy\" in warnings, just capitalize all letters in\nthe names and prefix them by \"WARN\". So, for example, the category \"void\" used in a perl\nprogram becomes \"WARNVOID\" when used in XS code and passed to one of the calls below.\n\n\"ckWARN\"\n\"ckWARN2\"\n\"ckWARN3\"\n\"ckWARN4\"\nThese return a boolean as to whether or not warnings are enabled for any of the warning\ncategory(ies) parameters: \"w\", \"w1\", ....\n\nShould any of the categories by default be enabled even if not within the scope of\n\"use warnings\", instead use the \"ckWARNd\" macros.\n\nThe categories must be completely independent, one may not be subclassed from the other.\n\nbool ckWARN (U32 w)\nbool ckWARN2(U32 w1, U32 w2)\nbool ckWARN3(U32 w1, U32 w2, U32 w3)\nbool ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)\n\n\"ckWARNd\"\n\"ckWARN2d\"\n\"ckWARN3d\"\n\"ckWARN4d\"\nLike \"ckWARN\", but for use if and only if the warning category(ies) is by default enabled\neven if not within the scope of \"use warnings\".\n\nbool ckWARNd (U32 w)\nbool ckWARN2d(U32 w1, U32 w2)\nbool ckWARN3d(U32 w1, U32 w2, U32 w3)\nbool ckWARN4d(U32 w1, U32 w2, U32 w3, U32 w4)\n\n\"ckwarner\"\n\"ckwarnerd\"\nIf none of the warning categories given by \"err\" are enabled, do nothing; otherwise call\n\"warner\" or \"warnernocontext\" with the passed-in parameters;.\n\n\"err\" must be one of the \"packWARN\", \"packWARN2\", \"packWARN3\", \"packWARN4\" macros\npopulated with the appropriate number of warning categories.\n\nThe two forms differ only in that \"ckwarnerd\" should be used if warnings for any of the\ncategories are by default enabled.\n\nNOTE: \"ckwarner\" must be explicitly called as \"Perlckwarner\" with an \"aTHX\"\nparameter.\n\nNOTE: \"ckwarnerd\" must be explicitly called as \"Perlckwarnerd\" with an \"aTHX\"\nparameter.\n\nvoid Perlckwarner(pTHX U32 err, const char *pat, ...)\n\n\"CLEARERRSV\"\nClear the contents of $@, setting it to the empty string.\n\nThis replaces any read-only SV with a fresh SV and removes any magic.\n\nvoid CLEARERRSV()\n\n\"croak\"\n\"croaknocontext\"\nThese are XS interfaces to Perl's \"die\" function.\n\nThey take a sprintf-style format pattern and argument list, which are used to generate a\nstring message. If the message does not end with a newline, then it will be extended\nwith some indication of the current location in the code, as described for \"messsv\".\n\nThe error message will be used as an exception, by default returning control to the\nnearest enclosing \"eval\", but subject to modification by a $SIG{DIE} handler. In any\ncase, these croak functions never return normally.\n\nFor historical reasons, if \"pat\" is null then the contents of \"ERRSV\" ($@) will be used\nas an error message or object instead of building an error message from arguments. If\nyou want to throw a non-string object, or build an error message in an SV yourself, it is\npreferable to use the \"croaksv\" function, which does not involve clobbering \"ERRSV\".\n\nThe two forms differ only in that \"croaknocontext\" does not take a thread context\n(\"aTHX\") parameter. It is usually preferred as it takes up fewer bytes of code than\nplain \"Perlcroak\", and time is rarely a critical resource when you are about to throw an\nexception.\n\nNOTE: \"croak\" must be explicitly called as \"Perlcroak\" with an \"aTHX\" parameter.\n\nvoid Perlcroak (pTHX const char *pat, ...)\nvoid croaknocontext(const char *pat, ...)\n\n\"croaknomodify\"\nThis encapsulates a common reason for dying, generating terser object code than using the\ngeneric \"Perlcroak\". It is exactly equivalent to \"Perlcroak(aTHX \"%s\", PLnomodify)\"\n(which expands to something like \"Modification of a read-only value attempted\").\n\nLess code used on exception code paths reduces CPU cache pressure.\n\nvoid croaknomodify()\n\n\"croaksv\"\nThis is an XS interface to Perl's \"die\" function.\n\n\"baseex\" is the error message or object. If it is a reference, it will be used as-is.\nOtherwise it is used as a string, and if it does not end with a newline then it will be\nextended with some indication of the current location in the code, as described for\n\"messsv\".\n\nThe error message or object will be used as an exception, by default returning control to\nthe nearest enclosing \"eval\", but subject to modification by a $SIG{DIE} handler. In\nany case, the \"croaksv\" function never returns normally.\n\nTo die with a simple string message, the \"croak\" function may be more convenient.\n\nvoid croaksv(SV *baseex)\n\n\"die\"\n\"dienocontext\"\nThese behave the same as \"croak\", except for the return type. They should be used only\nwhere the \"OP *\" return type is required. They never actually return.\n\nThe two forms differ only in that \"dienocontext\" does not take a thread context (\"aTHX\")\nparameter, so is used in situations where the caller doesn't already have the thread\ncontext.\n\nNOTE: \"die\" must be explicitly called as \"Perldie\" with an \"aTHX\" parameter.\n\nOP * Perldie (pTHX const char *pat, ...)\nOP * dienocontext(const char *pat, ...)\n\n\"diesv\"\nThis behaves the same as \"croaksv\", except for the return type. It should be used only\nwhere the \"OP *\" return type is required. The function never actually returns.\n\nOP * diesv(SV *baseex)\n\n\"ERRSV\"\nReturns the SV for $@, creating it if needed.\n\nSV * ERRSV\n\n\"packWARN\"\n\"packWARN2\"\n\"packWARN3\"\n\"packWARN4\"\nThese macros are used to pack warning categories into a single U32 to pass to macros and\nfunctions that take a warning category parameter. The number of categories to pack is\ngiven by the name, with a corresponding number of category parameters passed.\n\nU32 packWARN (U32 w1)\nU32 packWARN2(U32 w1, U32 w2)\nU32 packWARN3(U32 w1, U32 w2, U32 w3)\nU32 packWARN4(U32 w1, U32 w2, U32 w3, U32 w4)\n\n\"SANEERRSV\"\nClean up ERRSV so we can safely set it.\n\nThis replaces any read-only SV with a fresh writable copy and removes any magic.\n\nvoid SANEERRSV()\n\n\"vcroak\"\nThis is an XS interface to Perl's \"die\" function.\n\n\"pat\" and \"args\" are a sprintf-style format pattern and encapsulated argument list.\nThese are used to generate a string message. If the message does not end with a newline,\nthen it will be extended with some indication of the current location in the code, as\ndescribed for \"messsv\".\n\nThe error message will be used as an exception, by default returning control to the\nnearest enclosing \"eval\", but subject to modification by a $SIG{DIE} handler. In any\ncase, the \"croak\" function never returns normally.\n\nFor historical reasons, if \"pat\" is null then the contents of \"ERRSV\" ($@) will be used\nas an error message or object instead of building an error message from arguments. If\nyou want to throw a non-string object, or build an error message in an SV yourself, it is\npreferable to use the \"croaksv\" function, which does not involve clobbering \"ERRSV\".\n\nvoid vcroak(const char *pat, valist *args)\n\n\"vwarn\"\nThis is an XS interface to Perl's \"warn\" function.\n\nThis is like \"warn\", but \"args\" are an encapsulated argument list.\n\nUnlike with \"vcroak\", \"pat\" is not permitted to be null.\n\nvoid vwarn(const char *pat, valist *args)\n\n\"vwarner\"\nThis is like \"warner\", but \"args\" are an encapsulated argument list.\n\nvoid vwarner(U32 err, const char *pat, valist *args)\n\n\"warn\"\n\"warnnocontext\"\nThese are XS interfaces to Perl's \"warn\" function.\n\nThey take a sprintf-style format pattern and argument list, which are used to generate a\nstring message. If the message does not end with a newline, then it will be extended\nwith some indication of the current location in the code, as described for \"messsv\".\n\nThe error message or object will by default be written to standard error, but this is\nsubject to modification by a $SIG{WARN} handler.\n\nUnlike with \"croak\", \"pat\" is not permitted to be null.\n\nThe two forms differ only in that \"warnnocontext\" does not take a thread context\n(\"aTHX\") parameter, so is used in situations where the caller doesn't already have the\nthread context.\n\nNOTE: \"warn\" must be explicitly called as \"Perlwarn\" with an \"aTHX\" parameter.\n\nvoid Perlwarn (pTHX const char *pat, ...)\nvoid warnnocontext(const char *pat, ...)\n\n\"warner\"\n\"warnernocontext\"\nThese output a warning of the specified category (or categories) given by \"err\", using\nthe sprintf-style format pattern \"pat\", and argument list.\n\n\"err\" must be one of the \"packWARN\", \"packWARN2\", \"packWARN3\", \"packWARN4\" macros\npopulated with the appropriate number of warning categories. If any of the warning\ncategories they specify is fatal, a fatal exception is thrown.\n\nIn any event a message is generated by the pattern and arguments. If the message does\nnot end with a newline, then it will be extended with some indication of the current\nlocation in the code, as described for \"messsv\".\n\nThe error message or object will by default be written to standard error, but this is\nsubject to modification by a $SIG{WARN} handler.\n\n\"pat\" is not permitted to be null.\n\nThe two forms differ only in that \"warnernocontext\" does not take a thread context\n(\"aTHX\") parameter, so is used in situations where the caller doesn't already have the\nthread context.\n\nThese functions differ from the similarly named \"warn\" functions, in that the latter are\nfor XS code to unconditionally display a warning, whereas these are for code that may be\ncompiling a perl program, and does extra checking to see if the warning should be fatal.\n\nNOTE: \"warner\" must be explicitly called as \"Perlwarner\" with an \"aTHX\" parameter.\n\nvoid Perlwarner (pTHX U32 err, const char *pat, ...)\nvoid warnernocontext(U32 err, const char *pat, ...)\n\n\"warnsv\"\nThis is an XS interface to Perl's \"warn\" function.\n\n\"baseex\" is the error message or object. If it is a reference, it will be used as-is.\nOtherwise it is used as a string, and if it does not end with a newline then it will be\nextended with some indication of the current location in the code, as described for\n\"messsv\".\n\nThe error message or object will by default be written to standard error, but this is\nsubject to modification by a $SIG{WARN} handler.\n\nTo warn with a simple string message, the \"warn\" function may be more convenient.\n\nvoid warnsv(SV *baseex)\n\nXS\nxsubpp compiles XS code into C. See \"xsubpp\" in perlutil.\n\n\"aMYCXT\"\nDescribed in perlxs.\n\n\"aMYCXT\"\nDescribed in perlxs.\n\n\"aMYCXT\"\nDescribed in perlxs.\n\n\"ax\"\nVariable which is setup by \"xsubpp\" to indicate the stack base offset, used by the \"ST\",\n\"XSprePUSH\" and \"XSRETURN\" macros. The \"dMARK\" macro must be called prior to setup the\n\"MARK\" variable.\n\nI32 ax\n\n\"CLASS\"\nVariable which is setup by \"xsubpp\" to indicate the class name for a C++ XS constructor.\nThis is always a \"char*\". See \"THIS\".\n\nchar* CLASS\n\n\"dAX\"\nSets up the \"ax\" variable. This is usually handled automatically by \"xsubpp\" by calling\n\"dXSARGS\".\n\ndAX;\n\n\"dAXMARK\"\nSets up the \"ax\" variable and stack marker variable \"mark\". This is usually handled\nautomatically by \"xsubpp\" by calling \"dXSARGS\".\n\ndAXMARK;\n\n\"dITEMS\"\nSets up the \"items\" variable. This is usually handled automatically by \"xsubpp\" by\ncalling \"dXSARGS\".\n\ndITEMS;\n\n\"dMYCXT\"\nDescribed in perlxs.\n\n\"dMYCXTSV\"\nNow a placeholder that declares nothing\n\ndMYCXTSV;\n\n\"dUNDERBAR\"\nSets up any variable needed by the \"UNDERBAR\" macro. It used to define \"padoffdu\", but\nit is currently a noop. However, it is strongly advised to still use it for ensuring\npast and future compatibility.\n\ndUNDERBAR;\n\n\"dXSARGS\"\nSets up stack and mark pointers for an XSUB, calling \"dSP\" and \"dMARK\". Sets up the \"ax\"\nand \"items\" variables by calling \"dAX\" and \"dITEMS\". This is usually handled\nautomatically by \"xsubpp\".\n\ndXSARGS;\n\n\"dXSI32\"\nSets up the \"ix\" variable for an XSUB which has aliases. This is usually handled\nautomatically by \"xsubpp\".\n\ndXSI32;\n\n\"items\"\nVariable which is setup by \"xsubpp\" to indicate the number of items on the stack. See\n\"Variable-length Parameter Lists\" in perlxs.\n\nI32 items\n\n\"ix\"\nVariable which is setup by \"xsubpp\" to indicate which of an XSUB's aliases was used to\ninvoke it. See \"The ALIAS: Keyword\" in perlxs.\n\nI32 ix\n\n\"MYCXT\"\nDescribed in perlxs.\n\n\"MYCXTCLONE\"\nDescribed in perlxs.\n\n\"MYCXTINIT\"\nDescribed in perlxs.\n\n\"pMYCXT\"\nDescribed in perlxs.\n\n\"pMYCXT\"\nDescribed in perlxs.\n\n\"pMYCXT\"\nDescribed in perlxs.\n\n\"RETVAL\"\nVariable which is setup by \"xsubpp\" to hold the return value for an XSUB. This is always\nthe proper type for the XSUB. See \"The RETVAL Variable\" in perlxs.\n\ntype RETVAL\n\n\"ST\"\nUsed to access elements on the XSUB's stack.\n\nSV* ST(int ix)\n\n\"STARTMYCXT\"\nDescribed in perlxs.\n\n\"THIS\"\nVariable which is setup by \"xsubpp\" to designate the object in a C++ XSUB. This is\nalways the proper type for the C++ object. See \"CLASS\" and \"Using XS With C++\" in\nperlxs.\n\ntype THIS\n\n\"UNDERBAR\"\nThe SV* corresponding to the $ variable. Works even if there is a lexical $ in scope.\n\n\"XS\"\nMacro to declare an XSUB and its C parameter list. This is handled by \"xsubpp\". It is\nthe same as using the more explicit \"XSEXTERNAL\" macro; the latter is preferred.\n\n\"XSEXTERNAL\"\nMacro to declare an XSUB and its C parameter list explicitly exporting the symbols.\n\n\"XSINTERNAL\"\nMacro to declare an XSUB and its C parameter list without exporting the symbols. This is\nhandled by \"xsubpp\" and generally preferable over exporting the XSUB symbols\nunnecessarily.\n\n\"XSPROTO\"\nMacro used by \"XSINTERNAL\" and \"XSEXTERNAL\" to declare a function prototype. You\nprobably shouldn't be using this directly yourself.\n", "subsections": [] }, "Undocumented elements": { "content": "The following functions have been flagged as part of the public API, but are currently\nundocumented. Use them at your own risk, as the interfaces are subject to change. Functions\nthat are not listed in this document are not intended for public use, and should NOT be used\nunder any circumstances.\n\nIf you feel you need to use one of these functions, first send email to\nperl5-porters@perl.org . It may be that there is a good\nreason for the function not being documented, and it should be removed from this list; or it\nmay just be that no one has gotten around to documenting it. In the latter case, you will be\nasked to submit a patch to document the function. Once your patch is accepted, it will\nindicate that the interface is stable (unless it is explicitly marked otherwise) and usable\nby you.\n\ncloneparamsdel newANONATTRSUB newAVREF newSVREF svdupinc\ncloneparamsnew newANONHASH newCVREF PERLBUILDDATE\ndoopen newANONLIST newGVREF resumecompcv\ndoopenn newANONSUB newHVREF svdup\n\nNext are the API-flagged elements that are considered experimental. Using one of these is\neven more risky than plain undocumented ones. They are listed here because they should be\nlisted somewhere (so their existence doesn't get lost) and this is the best place for them.\n\napplyattrsstring hvstoreflags threadlocaleinit\ngvfetchmethodpvflags leaveadjuststacks threadlocaleterm\ngvfetchmethodpvnflags newXSflags\ngvfetchmethodsvflags savetmps\n\nFinally are deprecated undocumented API elements. Do not use any for new code; remove all\noccurrences of all of these from existing code.\n\nThere are currently no items of this type\n", "subsections": [] }, "AUTHORS": { "content": "Until May 1997, this document was maintained by Jeff Okamoto . It is\nnow maintained as part of Perl itself.\n\nWith lots of help and suggestions from Dean Roehrich, Malcolm Beattie, Andreas Koenig, Paul\nHudson, Ilya Zakharevich, Paul Marquess, Neil Bowers, Matthew Green, Tim Bunce, Spider\nBoardman, Ulrich Pfeifer, Stephen McCamant, and Gurusamy Sarathy.\n\nAPI Listing originally by Dean Roehrich .\n\nUpdated to be autogenerated from comments in the source by Benjamin Stuhl.\n", "subsections": [] }, "SEE ALSO": { "content": "config.h, perlapio, perlcall, perlclib, perlembed, perlfilter, perlguts, perlhacktips,\nperlintern, perlinterp, perliol, perlmroapi, perlreapi, perlreguts, perlxs\n\nperl v5.38.2 2026-06-12 PERLAPI(1)", "subsections": [] } } } }