Miscellaneous Functions
Analyses the string in order to make fast searches on it using fbm_instr() -- the Boyer-Moore algorithm.
Returns the location of the SV in the string delimited by big and bigend. It returns NULL if the string can't be found. The sv does not have to be fbm_compiled, but the search will not be as fast then.
Returns true if the leading len bytes of the strings s1 and s2 are the same case-insensitively; false otherwise. Uppercase and lowercase ASCII range bytes match themselves and their opposite case counterparts. Non-cased and non-ASCII range bytes match only themselves.
Returns true if the leading len bytes of the strings s1 and s2 are the same case-insensitively in the current locale; false otherwise.
Memory Management
Perl's version of strdup(). Returns a pointer to a newly allocated string which is a duplicate of pv. The size of the string is determined by strlen(), which means it may not contain embedded NUL characters and must have a trailing NUL. The memory allocated for the new string can be freed with the Safefree() function.
On some platforms, Windows for example, all allocated memory owned by a thread is deallocated when that thread ends. So if you need that not to happen, you need to use the shared memory functions, such as "savesharedpv".
Perl's version of what strndup() would be if it existed. Returns a pointer to a newly allocated string which is a duplicate of the first len bytes from pv, plus a trailing NUL byte. The memory allocated for the new string can be freed with the Safefree() function.
On some platforms, Windows for example, all allocated memory owned by a thread is deallocated when that thread ends. So if you need that not to happen, you need to use the shared memory functions, such as "savesharedpvn".
A version of savepv() which allocates the duplicate string in memory which is shared between threads.
A version of savepvn() which allocates the duplicate string in memory which is shared between threads. (With the specific difference that a NULL pointer is not acceptable)
A version of savepv()/savepvn() which gets the string to duplicate from the passed in SV using SvPV()
On some platforms, Windows for example, all allocated memory owned by a thread is deallocated when that thread ends. So if you need that not to happen, you need to use the shared memory functions, such as "savesharedsvpv".
A version of savesharedpv() which allocates the duplicate string in memory which is shared between threads.
Miscellaneous Functions =for apidoc form
Takes a sprintf-style format pattern and conventional (non-SV) arguments and returns the formatted string.
(char *) Perl_form(pTHX_ const char* pat, ...)can be used any place a string (char *) is required:
char * s = Perl_form("%d.%d",major,minor);Uses a single private buffer so if you want to format several strings you must explicitly copy the earlier strings away (and free the copies when you are done).
Take a sprintf-style format pattern and argument list. These are used to generate a string message. If the message does not end with a newline, then it will be extended with some indication of the current location in the code, as described for "mess_sv".
Normally, the resulting message is returned in a new mortal SV. During global destruction a single SV may be shared between uses of this function.
Expands a message, intended for the user, to include an indication of the current location in the code, if the message does not already appear to be complete.
basemsg is the initial message or object. If it is a reference, it will be used as-is and will be the result of this function. Otherwise it is used as a string, and if it already ends with a newline, it is taken to be complete, and the result of this function will be the same string. If the message does not end with a newline, then a segment such as at foo.pl line 37 will be appended, and possibly other clauses indicating the current state of execution. The resulting message will end with a dot and a newline.
Normally, the resulting message is returned in a new mortal SV. During global destruction a single SV may be shared between uses of this function. If consume is true, then the function is permitted (but not required) to modify and return basemsg instead of allocating a new SV.
pat and args are a sprintf-style format pattern and encapsulated argument list. These are used to generate a string message. If the message does not end with a newline, then it will be extended with some indication of the current location in the code, as described for "mess_sv".
Normally, the resulting message is returned in a new mortal SV. During global destruction a single SV may be shared between uses of this function.
Warning and Dieing */
/* Common code used in dieing and warning */
STATIC SV * S_with_queued_errors(pTHX_ SV *ex) { PERL_ARGS_ASSERT_WITH_QUEUED_ERRORS; if (PL_errors && SvCUR(PL_errors) && !SvROK(ex)) { sv_catsv(PL_errors, ex); ex = sv_mortalcopy(PL_errors); SvCUR_set(PL_errors, 0); } return ex; }
STATIC bool S_invoke_exception_hook(pTHX_ SV *ex, bool warn) { HV *stash; GV *gv; CV *cv; SV **const hook = warn ? &PL_warnhook : &PL_diehook; /* sv_2cv might call Perl_croak() or Perl_warner() */ SV * const oldhook = *hook;
if (!oldhook)
return FALSE;
ENTER;
SAVESPTR(*hook);
*hook = NULL;
cv = sv_2cv(oldhook, &stash, &gv, 0);
LEAVE;
if (cv && !CvDEPTH(cv) && (CvROOT(cv) || CvXSUB(cv))) {
dSP;
SV *exarg;
ENTER;
save_re_context();
if (warn) {
SAVESPTR(*hook);
*hook = NULL;
}
exarg = newSVsv(ex);
SvREADONLY_on(exarg);
SAVEFREESV(exarg);
PUSHSTACKi(warn ? PERLSI_WARNHOOK : PERLSI_DIEHOOK);
PUSHMARK(SP);
XPUSHs(exarg);
PUTBACK;
call_sv(MUTABLE_SV(cv), G_DISCARD);
POPSTACK;
LEAVE;
return TRUE;
}
return FALSE;
}/* =for apidoc Am|OP *|die_sv|SV *baseex
Behaves the same as "croak_sv", except for the return type. It should be used only where the OP * return type is required. The function never actually returns.
Behaves the same as "croak", except for the return type. It should be used only where the OP * return type is required. The function never actually returns.
This is an XS interface to Perl's die function.
baseex is the error message or object. If it is a reference, it will be used as-is. Otherwise it is used as a string, and if it does not end with a newline then it will be extended with some indication of the current location in the code, as described for "mess_sv".
The error message or object will be used as an exception, by default returning control to the nearest enclosing eval, but subject to modification by a $SIG{__DIE__} handler. In any case, the croak_sv function never returns normally.
To die with a simple string message, the "croak" function may be more convenient.
This is an XS interface to Perl's die function.
pat and args are a sprintf-style format pattern and encapsulated argument list. These are used to generate a string message. If the message does not end with a newline, then it will be extended with some indication of the current location in the code, as described for "mess_sv".
The error message will be used as an exception, by default returning control to the nearest enclosing eval, but subject to modification by a $SIG{__DIE__} handler. In any case, the croak function never returns normally.
For historical reasons, if pat is null then the contents of ERRSV ($@) will be used as an error message or object instead of building an error message from arguments. If you want to throw a non-string object, or build an error message in an SV yourself, it is preferable to use the "croak_sv" function, which does not involve clobbering ERRSV.
This is an XS interface to Perl's die function.
Take a sprintf-style format pattern and argument list. These are used to generate a string message. If the message does not end with a newline, then it will be extended with some indication of the current location in the code, as described for "mess_sv".
The error message will be used as an exception, by default returning control to the nearest enclosing eval, but subject to modification by a $SIG{__DIE__} handler. In any case, the croak function never returns normally.
For historical reasons, if pat is null then the contents of ERRSV ($@) will be used as an error message or object instead of building an error message from arguments. If you want to throw a non-string object, or build an error message in an SV yourself, it is preferable to use the "croak_sv" function, which does not involve clobbering ERRSV.
Exactly equivalent to Perl_croak(aTHX_ "%s", PL_no_modify), but generates terser object code than using Perl_croak. Less code used on exception code paths reduces CPU cache pressure.
This is an XS interface to Perl's warn function.
baseex is the error message or object. If it is a reference, it will be used as-is. Otherwise it is used as a string, and if it does not end with a newline then it will be extended with some indication of the current location in the code, as described for "mess_sv".
The error message or object will by default be written to standard error, but this is subject to modification by a $SIG{__WARN__} handler.
To warn with a simple string message, the "warn" function may be more convenient.
This is an XS interface to Perl's warn function.
pat and args are a sprintf-style format pattern and encapsulated argument list. These are used to generate a string message. If the message does not end with a newline, then it will be extended with some indication of the current location in the code, as described for "mess_sv".
The error message or object will by default be written to standard error, but this is subject to modification by a $SIG{__WARN__} handler.
Unlike with "vcroak", pat is not permitted to be null.
This is an XS interface to Perl's warn function.
Take a sprintf-style format pattern and argument list. These are used to generate a string message. If the message does not end with a newline, then it will be extended with some indication of the current location in the code, as described for "mess_sv".
The error message or object will by default be written to standard error, but this is subject to modification by a $SIG{__WARN__} handler.
Unlike with "croak", pat is not permitted to be null.
Miscellaneous Functions
Fill the sv with current working directory
Dummy routine which "shares" an SV when there is no sharing module present. Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument. Exists to avoid test for a NULL function pointer and because it could potentially warn under some level of strict-ness.
Dummy routine which reports that object can be destroyed when there is no sharing module present. It ignores its single SV argument, and returns 'true'. Exists to avoid test for a NULL function pointer and because it could potentially warn under some level of strict-ness.
The C library sprintf, wrapped if necessary, to ensure that it will return the length of the string written to the buffer. Only rare pre-ANSI systems need the wrapper function - usually this is a direct call to sprintf.
quadmath_snprintf() is very strict about its format string and will fail, returning -1, if the format is invalid. It acccepts exactly one format spec.
quadmath_format_single() checks that the intended single spec looks sane: begins with %, has only one %, ends with [efgaEFGA], and has Q before it. This is not a full "printf syntax check", just the basics.
Returns the format if it is valid, NULL if not.
quadmath_format_single() can and will actually patch in the missing Q, if necessary. In this case it will return the modified copy of the format, which the caller will need to free.
See also "quadmath_format_needed".
quadmath_format_needed() returns true if the format string seems to contain at least one non-Q-prefixed %[efgaEFGA] format specifier, or returns false otherwise.
The format specifier detection is not complete printf-syntax detection, but it should catch most common cases.
If true is returned, those arguments should in theory be processed with quadmath_snprintf(), but in case there is more than one such format specifier (see "quadmath_format_single"), and if there is anything else beyond that one (even just a single byte), they cannot be processed because quadmath_snprintf() is very strict, accepting only one format spec, and nothing else. In this case, the code should probably fail.
The C library snprintf functionality, if available and standards-compliant (uses vsnprintf, actually). However, if the vsnprintf is not available, will unfortunately use the unsafe vsprintf which can overrun the buffer (there is an overrun check, but that may be too late). Consider using sv_vcatpvf instead, or getting vsnprintf.
The C library vsnprintf if available and standards-compliant. However, if if the vsnprintf is not available, will unfortunately use the unsafe vsprintf which can overrun the buffer (there is an overrun check, but that may be too late). Consider using sv_vcatpvf instead, or getting vsnprintf.
The C library strlcat if available, or a Perl implementation of it. This operates on C NUL-terminated strings.
my_strlcat() appends string src to the end of dst. It will append at most size - strlen(dst) - 1 characters. It will then NUL-terminate, unless size is 0 or the original dst string was longer than size (in practice this should not happen as it means that either size is incorrect or that dst is not a proper NUL-terminated string).
Note that size is the full size of the destination buffer and the result is guaranteed to be NUL-terminated if there is room. Note that room for the NUL should be included in size.
The C library strlcpy if available, or a Perl implementation of it. This operates on C NUL-terminated strings.
my_strlcpy() copies up to size - 1 characters from the string src to dst, NUL-terminating the result if size is not 0.
Collects the backtrace (aka "stacktrace") into a single linear malloced buffer, which the caller must Perl_free_c_backtrace().
Scans the frames back by depth + skip, then drops the skip innermost, returning at most depth frames.
Deallocates a backtrace received from get_c_bracktrace.
Returns a SV a dump of |depth| frames of the call stack, skipping the |skip| innermost ones. depth of 20 is usually enough.
The appended output looks like:
... 1 10e004812:0082 Perl_croak util.c:1716 /usr/bin/perl 2 10df8d6d2:1d72 perl_parse perl.c:3975 /usr/bin/perl ...
The fields are tab-separated. The first column is the depth (zero being the innermost non-skipped frame). In the hex:offset, the hex is where the program counter was in S_parse_body, and the :offset (might be missing) tells how much inside the S_parse_body the program counter was.
The util.c:1716 is the source code file and line number.
The /usr/bin/perl is obvious (hopefully).
Unknowns are "-". Unknowns can happen unfortunately quite easily: if the platform doesn't support retrieving the information; if the binary is missing the debug information; if the optimizer has transformed the code by for example inlining.
Dumps the C backtrace to the given fp.
Returns true if a backtrace could be retrieved, false if not.