Embedding Functions

Allocates a new Perl interpreter. See perlembed.

Initializes a new Perl interpreter. See perlembed.

Stub that provides thread hook for perl_destruct when there are no threads.

Shuts down a Perl interpreter. See perlembed for a tutorial.

my_perl points to the Perl interpreter. It must have been previously created through the use of "perl_alloc" and "perl_construct". It may have been initialised through "perl_parse", and may have been used through "perl_run" and other means. This function should be called for any Perl interpreter that has been constructed with "perl_construct", even if subsequent operations on it failed, for example if "perl_parse" returned a non-zero value.

If the interpreter's PL_exit_flags word has the PERL_EXIT_DESTRUCT_END flag set, then this function will execute code in END blocks before performing the rest of destruction. If it is desired to make any use of the interpreter between "perl_parse" and "perl_destruct" other than just calling "perl_run", then this flag should be set early on. This matters if "perl_run" will not be called, or if anything else will be done in addition to calling "perl_run".

Returns a value be a suitable value to pass to the C library function exit (or to return from main), to serve as an exit code indicating the nature of the way the interpreter terminated. This takes into account any failure of "perl_parse" and any early exit from "perl_run". The exit code is of the type required by the host operating system, so because of differing exit code conventions it is not portable to interpret specific numeric values as having specific meanings.

Releases a Perl interpreter. See perlembed.

Tells a Perl interpreter to parse a Perl script. This performs most of the initialisation of a Perl interpreter. See perlembed for a tutorial.

my_perl points to the Perl interpreter that is to parse the script. It must have been previously created through the use of "perl_alloc" and "perl_construct". xsinit points to a callback function that will be called to set up the ability for this Perl interpreter to load XS extensions, or may be null to perform no such setup.

argc and argv supply a set of command-line arguments to the Perl interpreter, as would normally be passed to the main function of a C program. argv[argc] must be null. These arguments are where the script to parse is specified, either by naming a script file or by providing a script in a -e option. If $0 will be written to in the Perl interpreter, then the argument strings must be in writable memory, and so mustn't just be string constants.

env specifies a set of environment variables that will be used by this Perl interpreter. If non-null, it must point to a null-terminated array of environment strings. If null, the Perl interpreter will use the environment supplied by the environ global variable.

This function initialises the interpreter, and parses and compiles the script specified by the command-line arguments. This includes executing code in BEGIN, UNITCHECK, and CHECK blocks. It does not execute INIT blocks or the main program.

Returns an integer of slightly tricky interpretation. The correct use of the return value is as a truth value indicating whether there was a failure in initialisation. If zero is returned, this indicates that initialisation was successful, and it is safe to proceed to call "perl_run" and make other use of it. If a non-zero value is returned, this indicates some problem that means the interpreter wants to terminate. The interpreter should not be just abandoned upon such failure; the caller should proceed to shut the interpreter down cleanly with "perl_destruct" and free it with "perl_free".

For historical reasons, the non-zero return value also attempts to be a suitable value to pass to the C library function exit (or to return from main), to serve as an exit code indicating the nature of the way initialisation terminated. However, this isn't portable, due to differing exit code conventions. A historical bug is preserved for the time being: if the Perl built-in exit is called during this function's execution, with a type of exit entailing a zero exit code under the host operating system's conventions, then this function returns zero rather than a non-zero value. This bug, [perl #2754], leads to perl_run being called (and therefore INIT blocks and the main program running) despite a call to exit. It has been preserved because a popular module-installing module has come to rely on it and needs time to be fixed. This issue is [perl #132577], and the original bug is due to be fixed in Perl 5.30.

Tells a Perl interpreter to run its main program. See perlembed for a tutorial.

my_perl points to the Perl interpreter. It must have been previously created through the use of "perl_alloc" and "perl_construct", and initialised through "perl_parse". This function should not be called if "perl_parse" returned a non-zero value, indicating a failure in initialisation or compilation.

This function executes code in INIT blocks, and then executes the main program. The code to be executed is that established by the prior call to "perl_parse". If the interpreter's PL_exit_flags word does not have the PERL_EXIT_DESTRUCT_END flag set, then this function will also execute code in END blocks. If it is desired to make any further use of the interpreter after calling this function, then END blocks should be postponed to "perl_destruct" time by setting that flag.

Returns an integer of slightly tricky interpretation. The correct use of the return value is as a truth value indicating whether the program terminated non-locally. If zero is returned, this indicates that the program ran to completion, and it is safe to make other use of the interpreter (provided that the PERL_EXIT_DESTRUCT_END flag was set as described above). If a non-zero value is returned, this indicates that the interpreter wants to terminate early. The interpreter should not be just abandoned because of this desire to terminate; the caller should proceed to shut the interpreter down cleanly with "perl_destruct" and free it with "perl_free".

For historical reasons, the non-zero return value also attempts to be a suitable value to pass to the C library function exit (or to return from main), to serve as an exit code indicating the nature of the way the program terminated. However, this isn't portable, due to differing exit code conventions. An attempt is made to return an exit code of the type required by the host operating system, but because it is constrained to be non-zero, it is not necessarily possible to indicate every type of exit. It is only reliable on Unix, where a zero exit code can be augmented with a set bit that will be ignored. In any case, this function is not the correct place to acquire an exit code: one should get that from "perl_destruct".

SV Manipulation Functions

Returns the SV of the specified Perl scalar. flags are passed to gv_fetchpv. If GV_ADD is set and the Perl variable does not exist then it will be created. If flags is zero and the variable does not exist then NULL is returned.

Array Manipulation Functions

Returns the AV of the specified Perl global or package array with the given name (so it won't work on lexical variables). flags are passed to gv_fetchpv. If GV_ADD is set and the Perl variable does not exist then it will be created. If flags is zero and the variable does not exist then NULL is returned.

Perl equivalent: @{"$name"}.

Hash Manipulation Functions

Returns the HV of the specified Perl hash. flags are passed to gv_fetchpv. If GV_ADD is set and the Perl variable does not exist then it will be created. If flags is zero and the variable does not exist then NULL is returned.

CV Manipulation Functions

Returns the CV of the specified Perl subroutine. flags are passed to gv_fetchpvn_flags. If GV_ADD is set and the Perl subroutine does not exist then it will be declared (which has the same effect as saying sub name;). If GV_ADD is not set and the subroutine does not exist then NULL is returned.

Uses strlen to get the length of name, then calls get_cvn_flags.

Callback Functions

Performs a callback to the specified named and package-scoped Perl subroutine with argv (a NULL-terminated array of strings) as arguments. See perlcall.

Approximate Perl equivalent: &{"$sub_name"}(@$argv).

Performs a callback to the specified Perl sub. See perlcall.

Performs a callback to the specified Perl method. The blessed object must be on the stack. See perlcall.

Performs a callback to the Perl sub specified by the SV.

If neither the G_METHOD nor G_METHOD_NAMED flag is supplied, the SV may be any of a CV, a GV, a reference to a CV, a reference to a GV or SvPV(sv) will be used as the name of the sub to call.

If the G_METHOD flag is supplied, the SV may be a reference to a CV or SvPV(sv) will be used as the name of the method to call.

If the G_METHOD_NAMED flag is supplied, SvPV(sv) will be used as the name of the method to call.

Some other values are treated specially for internal use and should not be depended on.

See perlcall.

Tells Perl to eval the string in the SV. It supports the same flags as call_sv, with the obvious exception of G_EVAL. See perlcall.

The G_RETHROW flag can be used if you only need eval_sv() to execute code specified by a string, but not catch any errors.

Tells Perl to eval the given string in scalar context and return an SV* result.

Embedding Functions

Tells Perl to require the file named by the string argument. It is analogous to the Perl code eval "require '$file'". It's even implemented that way; consider using load_module instead.

A wrapper for the C library exit(3), honoring what "PL_exit_flags" in perlapi say to do.

cpanm less

perl -MCPAN -e shell
install less