Copy a source buffer to a destination buffer, stopping at (but not including) the first occurrence in the source of the delimiter byte, delim. The source is the bytes between from and from_end - 1. Similarly, the dest is to up to to_end.
The number of bytes copied is written to *retlen.
Returns the position of delim in the from buffer, but if there is no such occurrence before from_end, then from_end is returned, and the entire buffer from .. from_end - 1 is copied.
If there is room in the destination available after the copy, an extra terminating safety NUL byte is appended (not included in the returned length).
The error case is if the destination buffer is not large enough to accommodate everything that should be copied. In this situation, a value larger than to_end - to is written to *retlen, and as much of the source as fits will be written to the destination. Not having room for the safety NUL is not considered an error.
Copy a source buffer to a destination buffer, stopping at (but not including) the first occurrence in the source of an unescaped (defined below) delimiter byte, delim. The source is the bytes between from and from_end - 1. Similarly, the dest is to up to to_end.
The number of bytes copied is written to *retlen.
Returns the position of the first uncopied delim in the from buffer, but if there is no such occurrence before from_end, then from_end is returned, and the entire buffer from .. from_end - 1 is copied.
If there is room in the destination available after the copy, an extra terminating safety NUL byte is appended (not included in the returned length).
The error case is if the destination buffer is not large enough to accommodate everything that should be copied. In this situation, a value larger than to_end - to is written to *retlen, and as much of the source as fits will be written to the destination. Not having room for the safety NUL is not considered an error.
In the following examples, let x be the delimiter, and 0 represent a NUL byte (NOT the digit 0). Then we would have
Source Destinationabcxdef abc0
provided the destination buffer is at least 4 bytes long.
An escaped delimiter is one which is immediately preceded by a single backslash. Escaped delimiters are copied, and the copy continues past the delimiter; the backslash is not copied:
Source Destinationabc\xdef abcxdef0
(provided the destination buffer is at least 8 bytes long).
It's actually somewhat more complicated than that. A sequence of any odd number of backslashes escapes the following delimiter, and the copy continues with exactly one of the backslashes stripped.
Source Destinationabc\xdef abcxdef0abc\\\xdef abc\\xdef0abc\\\\\xdef abc\\\\xdef0
(as always, if the destination is large enough)
An even number of preceding backslashes does not escape the delimiter, so that the copy stops just before it, and includes all the backslashes (no stripping; zero is considered even):
Source Destinationabcxdef abc0abc\\xdef abc\\0abc\\\\xdef abc\\\\0
Find the first (leftmost) occurrence of a sequence of bytes within another sequence. This is the Perl version of strstr(), extended to handle arbitrary sequences, potentially containing embedded NUL characters (NUL is what the initial n in the function name stands for; some systems have an equivalent, memmem(), but with a somewhat different API).
Another way of thinking about this function is finding a needle in a haystack. big points to the first byte in the haystack. big_end points to one byte beyond the final byte in the haystack. little points to the first byte in the needle. little_end points to one byte beyond the final byte in the needle. All the parameters must be non-NULL.
The function returns NULL if there is no occurrence of little within big. If little is the empty string, big is returned.
Because this function operates at the byte level, and because of the inherent characteristics of UTF-8 (or UTF-EBCDIC), it will work properly if both the needle and the haystack are strings with the same UTF-8ness, but not if the UTF-8ness differs.
Like "ninstr", but instead finds the final (rightmost) occurrence of a sequence of bytes within another sequence, returning NULL if there is no such occurrence.
Analyzes 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 (bigend) is the char following the last char). 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.
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)
These take a sprintf-style format pattern and conventional (non-SV) arguments and return the formatted string.
(char *) Perl_form(aTHX_ const char* pat, ...)
They can be used any place a string (char *) is required:
char * s = form_nocontext("%d.%d", major, minor);
They each return a temporary that will be freed "soon", automatically by the system, at the same time that SVs operated on by "sv_2mortal" are freed.
Use the result immediately, or copy to a stable place for longer retention. This is contrary to the incorrect previous documentation of these that claimed that the return was a single per-thread buffer. That was (and is) actually true only when these are called during global destruction.
The two forms differ only in that form_nocontext does not take a thread context (aTHX) parameter, so is used in situations where the caller doesn't already have the thread context.
"vform" is the same except the arguments are an encapsulated argument list.
Like "form" except the arguments are an encapsulated argument list.
These take a sprintf-style format pattern and argument list, which 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. But during global destruction a single SV may be shared between uses of this function.
The two forms differ only in that mess_nocontext does not take a thread context (aTHX) parameter, so is used in situations where the caller doesn't already have the thread context.
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, respectively. 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.
/* 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; }
bool Perl_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 || oldhook == PERL_WARNHOOK_FATAL)returnFALSE;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;returnTRUE;}returnFALSE;}
/* =for apidoc die_sv
This 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.
These behave the same as "croak", except for the return type. They should be used only where the OP * return type is required. They never actually return.
The two forms differ only in that die_nocontext does not take a thread context (aTHX) parameter, so is used in situations where the caller doesn't already have the thread context.
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.
These are XS interfaces to Perl's die function.
They take a sprintf-style format pattern and argument list, which 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, these croak functions never return 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.
The two forms differ only in that croak_nocontext does not take a thread context (aTHX) parameter. It is usually preferred as it takes up fewer bytes of code than plain Perl_croak, and time is rarely a critical resource when you are about to throw an exception.
This encapsulates a common reason for dying, generating terser object code than using the generic Perl_croak. It is exactly equivalent to Perl_croak(aTHX_ "%s", PL_no_modify) (which expands to something like "Modification of a read-only value attempted").
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.
This is like "warn", but args are an encapsulated argument list.
Unlike with "vcroak", pat is not permitted to be null.
These are XS interfaces to Perl's warn function.
They take a sprintf-style format pattern and argument list, which 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.
The two forms differ only in that warn_nocontext does not take a thread context (aTHX) parameter, so is used in situations where the caller doesn't already have the thread context.
These output a warning of the specified category (or categories) given by err, using the sprintf-style format pattern pat, and argument list.
err must be one of the "packWARN", packWARN2, packWARN3, packWARN4 macros populated with the appropriate number of warning categories. If any of the warning categories they specify is fatal, a fatal exception is thrown.
In any event a message is generated by the pattern and arguments. 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.
pat is not permitted to be null.
The two forms differ only in that warner_nocontext does not take a thread context (aTHX) parameter, so is used in situations where the caller doesn't already have the thread context.
These functions differ from the similarly named "warn" functions, in that the latter are for XS code to unconditionally display a warning, whereas these are for code that may be compiling a perl program, and does extra checking to see if the warning should be fatal.
err must be one of the "packWARN", packWARN2, packWARN3, packWARN4 macros populated with the appropriate number of warning categories.
The two forms differ only in that ck_warner_d should be used if warnings for any of the categories are by default enabled.
Like "warner" except that it acts as if fatal warnings are enabled for the warning.
If called when there are pending compilation errors this function may return.
This is currently used to generate "used only once" fatal warnings since the COP where the name being reported is no longer the current COP when the warning is generated and may be useful for similar cases.
err must be one of the "packWARN", packWARN2, packWARN3, packWARN4 macros populated with the appropriate number of warning categories.
This is like "fatal_warner" but args are an encapsulated argument list.
A wrapper for the C library setenv(3). Don't use the latter, as the perl version has desirable safeguards
Implementing function on some systems for PerlProc_popen_list()
A wrapper for the C library popen(3). Don't use the latter, as the Perl version knows things that interact with the rest of the perl interpreter.
This is for the use of PerlProc_fork as a wrapper for the C library fork(2) on some platforms to hide some platform quirks. It should not be used except through PerlProc_fork.
A wrapper for the C library functions sigaction(2) or signal(2). Use this instead of those libc functions, as the Perl version gives the safest available implementation, and knows things that interact with the rest of the perl interpreter.
Returns a the current signal handler for signal signo. See "rsignal".
A wrapper for the C library pclose(3). Don't use the latter, as the Perl version knows things that interact with the rest of the perl interpreter.
Make count copies of the len bytes beginning at from, placing them into memory beginning at to, which must be big enough to accommodate them all.
Implements "PERL_SET_CONTEXT" in perlapi, which you should use instead.
Return a pointer to the array of all the names of the various OPs Given an opcode from the enum in opcodes.h, PL_op_name[opcode] returns a pointer to a C language string giving its name.
Return a pointer to the array of all the descriptions of the various OPs Given an opcode from the enum in opcodes.h, PL_op_desc[opcode] returns a pointer to a C language string giving its description.
Implements PERL_FLUSHALL_FOR_CHILD on some platforms.
Fill sv with current working directory
Emulates socketpair(2) on systems that don't have it, but which do have enough functionality for the emulation.
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.
quadmath_snprintf() is very strict about its format string and will fail, returning -1, if the format is invalid. It accepts exactly one format spec.
quadmath_format_valid() 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 true if it is valid, false if not.
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_valid"), 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 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.
Implements the "MY_CXT_INIT" in perlxs macro, which you should use instead.
The first time a module is loaded, the global PL_my_cxt_index is incremented, and that value is assigned to that module's static my_cxt_index (whose address is passed as an arg). Then, for each interpreter this function is called for, it makes sure a void* slot is available to hang the static data off, by allocating or extending the interpreter's PL_my_cxt_list array
The C library dirfd(3) if available, or a Perl implementation of it, or die if not easily emulatable.
The C library mkostemp(3) if available, or a Perl implementation of it.
The C library mkstemp(3) if available, or a Perl implementation of it.
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_backtrace.
Returns a SV containing 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/perl2 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.