<?php
// ==============================
//            CONTENTS            
// ==============================
// PHP_PROCESS_PROGRAMEXECUTION - BEGIN
// PHP_PROCESS_PROGRAMEXECUTION_ESCAPESHELLARG - string php_process_programexecution_escapeshellarg(string $arg)
// PHP_PROCESS_PROGRAMEXECUTION_ESCAPESHELLCMD - string php_process_programexecution_escapeshellcmd(string $command)
// PHP_PROCESS_PROGRAMEXECUTION_EXEC - string|false php_process_programexecution_exec(string $command, array& $output, int& $result_code)
// PHP_PROCESS_PROGRAMEXECUTION_PASSTHRU - bool php_process_programexecution_passthru(string $command, int& $result_code)
// PHP_PROCESS_PROGRAMEXECUTION_PROC_CLOSE - int php_process_programexecution_proc_close(resource $process)
// OFFLINE | PHP_PROCESS_PROGRAMEXECUTION_PROC_GET_STATUS - array php_process_programexecution_proc_get_status(resource $process)
// OFFLINE | PHP_PROCESS_PROGRAMEXECUTION_PROC_NICE - bool php_process_programexecution_proc_nice(int $priority)
// PHP_PROCESS_PROGRAMEXECUTION_PROC_OPEN - resource|false php_process_programexecution_proc_open(array|string $command, array $descriptor_spec, array& $pipes, string $cwd = null, array $env_vars = null, array $options = null)
// OFFLINE | PHP_PROCESS_PROGRAMEXECUTION_PROC_TERMINATE - bool php_process_programexecution_proc_terminate(resource $process, int $signal = 15)
// PHP_PROCESS_PROGRAMEXECUTION_SHELL_EXEC - string|false|null php_process_programexecution_shell_exec(string $command)
// PHP_PROCESS_PROGRAMEXECUTION_SYSTEM - string|false php_process_programexecution_system(string $command, int& $result_code)
// PHP_PROCESS_PROGRAMEXECUTION - END
// ==============================


// ============================== BEGIN
//          REQUIREMENTS          
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== INSTALLATION
// CORE (No installation needed to use these functions; they are part of the PHP core)
// ============================== USING FUNCTIONS (11)
// escapeshellarg() - PHP_4 >= PHP_4_0_3, PHP_5, PHP_7, PHP_8
// escapeshellcmd() - PHP_4, PHP_5, PHP_7, PHP_8
// exec() - PHP_4, PHP_5, PHP_7, PHP_8
// passthru() - PHP_4, PHP_5, PHP_7, PHP_8
// proc_close() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// OFFLINE | proc_get_status() - PHP_5, PHP_7, PHP_8
// OFFLINE | proc_nice() - PHP_5, PHP_7, PHP_8
// proc_open() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// OFFLINE | proc_terminate() - PHP_5, PHP_7, PHP_8
// shell_exec() - PHP_4, PHP_5, PHP_7, PHP_8
// system() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== USING CLASSES (0)
// ============================== USING DATA_TYPES (7)
// string
// false
// array
// int
// bool
// resource
// null
// ============================== END
//          REQUIREMENTS          
// ==============================


// ============================== BEGIN
//  PHP_PROCESS_PROGRAMEXECUTION
// ============================== ABOUT
// PHP Manual / Function Reference / Process Control Extensions / Program execution - System program execution
// URL: https://www.php.net/manual/en/book.exec.php
// ============================== DESCRIPTION
// SYSTEM_PROGRAM_EXECUTION
// LANGUAGE_REFERENCE_OPERATORS_EXECUTION_OPERATORS
// 
// SYSTEM_PROGRAM_EXECUTION - BEGIN
// System program execution
// 
// INTRODUCTION
// INSTALLING_CONFIGURING
// PREDEFINED_CONSTANTS
// PROGRAM_EXECUTION_FUNCTIONS
// 
// INTRODUCTION - BEGIN
// Introduction
// 
// Those functions provide means to execute commands on the system itself, and means to secure such commands.
// Note: All execution functions call the commands through cmd.exe under Windows. Therefore the user calling these functions needs appropriate privilege to run this command. The only exception is proc_open() with bypass_shell option.
// 
// LITERATURE_SOURCES
// * PHP_NET (2023-09-08)
// URL: https://www.php.net/manual/en/intro.exec.php
// INTRODUCTION - END
// 
// INSTALLING_CONFIGURING - BEGIN
// Installing/Configuring
// 
// REQUIREMENTS
// INSTALLATION
// RUNTIME_CONFIGURATION
// RESOURCE_TYPES
// 
// REQUIREMENTS - BEGIN
// Requirements
// 
// No external libraries are needed to build this extension.
// 
// LITERATURE_SOURCES
// * PHP_NET (2023-09-08)
// URL: https://www.php.net/manual/en/exec.requirements.php
// REQUIREMENTS - END
// 
// INSTALLATION - BEGIN
// Installation
// 
// There is no installation needed to use these functions; they are part of the PHP core.
// 
// LITERATURE_SOURCES
// * PHP_NET (2023-09-08)
// URL: https://www.php.net/manual/en/exec.installation.php
// INSTALLATION - END
// 
// RUNTIME_CONFIGURATION - BEGIN
// Runtime Configuration
// 
// This extension has no configuration directives defined in php.ini.
// 
// LITERATURE_SOURCES
// * PHP_NET (2023-09-08)
// URL: https://www.php.net/manual/en/exec.configuration.php
// RUNTIME_CONFIGURATION - END
// 
// RESOURCE_TYPES - BEGIN
// Resource Types
// 
// This extension defines a process resource, returned by proc_open().
// 
// LITERATURE_SOURCES
// * PHP_NET (2023-09-08)
// URL: https://www.php.net/manual/en/exec.resources.php
// RESOURCE_TYPES - END
// 
// LITERATURE_SOURCES
// * PHP_NET (2023-09-08)
// URL: https://www.php.net/manual/en/exec.setup.php
// INSTALLING_CONFIGURING - END
// 
// PREDEFINED_CONSTANTS - BEGIN
// Predefined Constants
// 
// This extension has no constants defined.
// 
// LITERATURE_SOURCES
// * PHP_NET (2023-09-08)
// URL: https://www.php.net/manual/en/exec.constants.php
// PREDEFINED_CONSTANTS - END
// 
// PROGRAM_EXECUTION_FUNCTIONS - BEGIN
// Program execution Functions
// 
// Notes
// Warning: Open files with lock (especially open sessions) should be closed before executing a program in the background.
// 
// See Also
// These functions are also closely related to the backtick operator.
// 
// Table of Contents
// * escapeshellarg  - Escape a string to be used as a shell argument
// * escapeshellcmd  - Escape shell metacharacters
// * exec            - Execute an external program
// * passthru        - Execute an external program and display raw output
// * proc_close      - Close a process opened by proc_open and return the exit code of that process
// * proc_get_status - Get information about a process opened by proc_open
// * proc_nice       - Change the priority of the current process
// * proc_open       - Execute a command and open file pointers for input/output
// * proc_terminate  - Kills a process opened by proc_open
// * shell_exec      - Execute command via shell and return the complete output as a string
// * system          - Execute an external program and display the output
// 
// LITERATURE_SOURCES
// * PHP_NET (2023-09-08)
// URL: https://www.php.net/manual/en/ref.exec.php
// PROGRAM_EXECUTION_FUNCTIONS - END
// 
// LITERATURE_SOURCES
// * PHP_NET (2023-09-08)
// URL: https://www.php.net/manual/en/book.exec.php
// SYSTEM_PROGRAM_EXECUTION - END
// 
// LANGUAGE_REFERENCE_OPERATORS_EXECUTION_OPERATORS - BEGIN
// Execution Operators (PHP Manual / Language Reference / Operators / Execution Operators)
// 
// PHP supports one execution operator: backticks (``). Note that these are not single-quotes! PHP will attempt to execute the contents of the backticks as a shell command; the output will be returned (i.e., it won't simply be dumped to output; it can be assigned to a variable). Use of the backtick operator is identical to shell_exec().
// [php]
// $output = `ls -al`;
// echo "<pre>$output</pre>";
// [/php]
// Note: The backtick operator is disabled when shell_exec() is disabled.
// Note: Unlike some other languages, backticks have no special meaning within double-quoted strings.
// 
// LITERATURE_SOURCES
// * PHP_NET (2023-09-18)
// URL: https://www.php.net/manual/en/language.operators.execution.php
// LANGUAGE_REFERENCE_OPERATORS_EXECUTION_OPERATORS - END
// ==============================


// ============================== BEGIN
// PHP_PROCESS_PROGRAMEXECUTION_ESCAPESHELLARG
// ============================== PUBLIC
// ============================== ABOUT
// Escape a string to be used as a shell argument.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// escapeshellarg() - PHP_4 >= PHP_4_0_3, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_process_programexecution_escapeshellarg($arg)
{
$return_escapeshellarg = null;

// ========== ESCAPESHELLARG - BEGIN
// ===== ABOUT
// Escape a string to be used as a shell argument
// ===== DESCRIPTION
// escapeshellarg() adds single quotes around a string and quotes/escapes any existing single quotes allowing you to pass a string directly to a shell function and having it be treated as a single safe argument. This function should be used to escape individual arguments to shell functions coming from user input. The shell functions include exec(), system() and the backtick operator.
// On Windows, escapeshellarg() instead replaces percent signs, exclamation marks (delayed variable substitution) and double quotes with spaces and adds double quotes around the string. Furthermore, each streak of consecutive backslashes (\) is escaped by one additional backslash.
// ===== SUPPORTED
// PHP_4 >= PHP_4_0_3, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// escapeshellarg(string $arg): string
// ===== CODE
$return_escapeshellarg = escapeshellarg(

$arg // string arg - The argument that will be escaped.

); // Return Values
// The escaped string.
// 
// [examples]
// Examples
// [example]
// Example #1 escapeshellarg() example
// [php]
// system('ls '.escapeshellarg($dir));
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-14)
// URL: https://www.php.net/manual/en/function.escapeshellarg.php
// ========== ESCAPESHELLARG - END

// SYNTAX:
// string escapeshellarg(string $arg)

return $return_escapeshellarg; // string
}
// ============================== END
// PHP_PROCESS_PROGRAMEXECUTION_ESCAPESHELLARG
// ==============================


// ============================== BEGIN
// PHP_PROCESS_PROGRAMEXECUTION_ESCAPESHELLCMD
// ============================== PUBLIC
// ============================== ABOUT
// Escape shell metacharacters.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// escapeshellcmd() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_process_programexecution_escapeshellcmd($command)
{
$return_escapeshellcmd = null;

// ========== ESCAPESHELLCMD - BEGIN
// ===== ABOUT
// Escape shell metacharacters
// ===== DESCRIPTION
// escapeshellcmd() escapes any characters in a string that might be used to trick a shell command into executing arbitrary commands. This function should be used to make sure that any data coming from user input is escaped before this data is passed to the exec() or system() functions, or to the backtick operator.
// Following characters are preceded by a backslash: &#;`|*?~<>^()[]{}$\, \x0A and \xFF. ' and " are escaped only if they are not paired. On Windows, all these characters plus % and ! are preceded by a caret (^).
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// escapeshellcmd(string $command): string
// ===== CODE
$return_escapeshellcmd = escapeshellcmd(

$command // string command - The command that will be escaped.

); // Return Values
// The escaped string.
// 
// [examples]
// Examples
// [example]
// Example #1 escapeshellcmd() example
// [php]
// // We allow arbitrary number of arguments intentionally here.
// $command = './configure '.$_POST['configure_options'];
// 
// $escaped_command = escapeshellcmd($command);
//  
// system($escaped_command);
// [/php]
// Warning: escapeshellcmd() should be used on the whole command string, and it still allows the attacker to pass arbitrary number of arguments. For escaping a single argument escapeshellarg() should be used instead.
//  Warning:
//  Spaces will not be escaped by escapeshellcmd() which can be problematic on Windows with paths like: C:\Program Files\ProgramName\program.exe. This can be mitigated using the following code snippet:
//  [php]
//  $cmd = preg_replace('`(?<!^) `', '^ ', escapeshellcmd($cmd));
//  [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-14)
// URL: https://www.php.net/manual/en/function.escapeshellcmd.php
// ========== ESCAPESHELLCMD - END

// SYNTAX:
// string escapeshellcmd(string $command)

return $return_escapeshellcmd; // string
}
// ============================== END
// PHP_PROCESS_PROGRAMEXECUTION_ESCAPESHELLCMD
// ==============================


// ============================== BEGIN
// PHP_PROCESS_PROGRAMEXECUTION_EXEC
// ============================== PUBLIC
// ============================== ABOUT
// Execute an external program.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// exec() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_process_programexecution_exec($command, & $output, & $result_code)
{
$return_exec = false;

// ========== EXEC - BEGIN
// ===== ABOUT
// Execute an external program
// ===== DESCRIPTION
// exec() executes the given command.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// exec(string $command, array &$output = null, int &$result_code = null): string|false
// ===== CODE
$return_exec = exec(

$command, // string command - The command that will be executed.

$output, // array& output - If the output argument is present, then the specified array will be filled with every line of output from the command. Trailing whitespace, such as \n, is not included in this array. Note that if the array already contains some elements, exec() will append to the end of the array. If you do not want the function to append elements, call unset() on the array before passing it to exec().

$result_code // int& result_code - If the result_code argument is present along with the output argument, then the return status of the executed command will be written to this variable.

); // Return Values
// The last line from the result of the command. If you need to execute a command and have all the data from the command passed directly back without any interference, use the passthru() function.
// Returns false on failure.
// To get the output of the executed command, be sure to set and use the output parameter.
// 
// Errors/Exceptions
// Emits an E_WARNING if exec() is unable to execute the command.
// Throws a ValueError if command is empty or contains null bytes.
// 
// Changelog
// Version - Description
// 8.0.0   - If command is empty or contains null bytes, exec() now throws a ValueError. Previously it emitted an E_WARNING and returned false.
// 
// [examples]
// Examples
// [example]
// Example #1 An exec() example
// [php]
// // outputs the username that owns the running php/httpd process
// // (on a system with the "whoami" executable in the path)
// $output=null;
// $retval=null;
// exec('whoami', $output, $retval);
// echo "Returned with status $retval and output:\n";
// print_r($output);
// [/php]
// The above example will output something similar to:
// [result]
// Returned with status 0 and output:
// Array
// (
//     [0] => cmb
// )
// [/result]
// [/example]
// [/examples]
// 
// Notes
// Warning: When allowing user-supplied data to be passed to this function, use escapeshellarg() or escapeshellcmd() to ensure that users cannot trick the system into executing arbitrary commands.
// Note: If a program is started with this function, in order for it to continue running in the background, the output of the program must be redirected to a file or another output stream. Failing to do so will cause PHP to hang until the execution of the program ends.
// Note: On Windows exec() will first start cmd.exe to launch the command. If you want to start an external program without starting cmd.exe use proc_open() with the bypass_shell option set.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-14)
// URL: https://www.php.net/manual/en/function.exec.php
// ========== EXEC - END

// SYNTAX:
// string|false exec(string $command, array& $output, int& $result_code)

return $return_exec; // string|false
}
// ============================== END
// PHP_PROCESS_PROGRAMEXECUTION_EXEC
// ==============================


// ============================== BEGIN
// PHP_PROCESS_PROGRAMEXECUTION_PASSTHRU
// ============================== PUBLIC
// ============================== ABOUT
// Execute an external program and display raw output.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// passthru() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_process_programexecution_passthru($command, & $result_code)
{
$return_passthru = false;

// ========== PASSTHRU - BEGIN
// ===== ABOUT
// Execute an external program and display raw output
// ===== DESCRIPTION
// The passthru() function is similar to the exec() function in that it executes a command. This function should be used in place of exec() or system() when the output from the Unix command is binary data which needs to be passed directly back to the browser. A common use for this is to execute something like the pbmplus utilities that can output an image stream directly. By setting the Content-type to image/gif and then calling a pbmplus program to output a gif, you can create PHP scripts that output images directly.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// passthru(string $command, int &$result_code = null): ?false
// ===== CODE
$return_passthru = passthru(

$command, // string command - The command that will be executed.

$result_code // int& result_code - If the result_code argument is present, the return status of the Unix command will be placed here.

); // Return Values
// Returns null on success or false on failure.
// 
// Errors/Exceptions
// Will emit an E_WARNING if passthru() is unable to execute the command.
// Throws a ValueError if command is empty or contains null bytes.
// 
// Changelog
// Version - Description
// 8.0.0   - If command is empty or contains null bytes, passthru() now throws a ValueError. Previously it emitted an E_WARNING and returned false.
// 
// Notes
// Warning: When allowing user-supplied data to be passed to this function, use escapeshellarg() or escapeshellcmd() to ensure that users cannot trick the system into executing arbitrary commands.
// Note: If a program is started with this function, in order for it to continue running in the background, the output of the program must be redirected to a file or another output stream. Failing to do so will cause PHP to hang until the execution of the program ends.
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-18)
// URL: https://www.php.net/manual/en/function.passthru.php
// ========== PASSTHRU - END

// SYNTAX:
// bool passthru(string $command, int& $result_code)

return $return_passthru; // bool
}
// ============================== END
// PHP_PROCESS_PROGRAMEXECUTION_PASSTHRU
// ==============================


// ============================== BEGIN
// PHP_PROCESS_PROGRAMEXECUTION_PROC_CLOSE
// ============================== PUBLIC
// ============================== ABOUT
// Close a process opened by proc_open() and return the exit code of that process.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// proc_close() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_process_programexecution_proc_close($process)
{
$return_proc_close = 0;

// ========== PROC_CLOSE - BEGIN
// ===== ABOUT
// Close a process opened by proc_open() and return the exit code of that process
// ===== DESCRIPTION
// proc_close() is similar to pclose() except that it only works on processes opened by proc_open(). proc_close() waits for the process to terminate, and returns its exit code. Open pipes to that process are closed when this function is called, in order to avoid a deadlock - the child process may not be able to exit while the pipes are open.
// ===== SUPPORTED
// PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// proc_close(resource $process): int
// ===== CODE
$return_proc_close = proc_close(

$process // resource process - The proc_open() resource that will be closed.

); // Return Values
// Returns the termination status of the process that was run. In case of an error then -1 is returned.
// Note: If PHP has been compiled with --enable-sigchild, the return value of this function is undefined.
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-18)
// URL: https://www.php.net/manual/en/function.proc-close.php
// ========== PROC_CLOSE - END

// SYNTAX:
// int proc_close(resource $process)

return $return_proc_close; // int
}
// ============================== END
// PHP_PROCESS_PROGRAMEXECUTION_PROC_CLOSE
// ==============================


// ============================== BEGIN
// PHP_PROCESS_PROGRAMEXECUTION_PROC_GET_STATUS
// ============================== OFFLINE
// ============================== ABOUT
// Get information about a process opened by proc_open().
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// proc_get_status() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_process_programexecution_proc_get_status($process)
{
$return_proc_get_status = null;

// ========== PROC_GET_STATUS - BEGIN
// ===== ABOUT
// Get information about a process opened by proc_open()
// ===== DESCRIPTION
// proc_get_status() fetches data about a process opened using proc_open().
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// proc_get_status(resource $process): array
// ===== CODE
$return_proc_get_status = proc_get_status(

$process // resource process - The proc_open() resource that will be evaluated.

); // Return Values
// An array of collected information. The returned array contains the following elements:
// element (type)   - description
// command (string) - The command string that was passed to proc_open().
// pid (int)        - process id
// running (bool)   - true if the process is still running, false if it has terminated.
// signaled (bool)  - true if the child process has been terminated by an uncaught signal. Always set to false on Windows.
// stopped (bool)   - true if the child process has been stopped by a signal. Always set to false on Windows.
// exitcode (int)   - The exit code returned by the process (which is only meaningful if running is false). Only first call of this function return real value, next calls return -1.
// termsig (int)    - The number of the signal that caused the child process to terminate its execution (only meaningful if signaled is true).
// stopsig (int)    - The number of the signal that caused the child process to stop its execution (only meaningful if stopped is true).
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-18)
// URL: https://www.php.net/manual/en/function.proc-get-status.php
// ========== PROC_GET_STATUS - END

// SYNTAX:
// array proc_get_status(resource $process)

return $return_proc_get_status; // array
}
*/
// ============================== END
// PHP_PROCESS_PROGRAMEXECUTION_PROC_GET_STATUS
// ==============================


// ============================== BEGIN
// PHP_PROCESS_PROGRAMEXECUTION_PROC_NICE
// ============================== OFFLINE
// ============================== ABOUT
// Change the priority of the current process.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// proc_nice() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_process_programexecution_proc_nice($priority)
{
$return_proc_nice = false;

// ========== PROC_NICE - BEGIN
// ===== ABOUT
// Change the priority of the current process
// ===== DESCRIPTION
// proc_nice() changes the priority of the current process by the amount specified in priority. A positive priority will lower the priority of the current process, whereas a negative priority will raise the priority.
// proc_nice() is not related to proc_open() and its associated functions in any way.
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// proc_nice(int $priority): bool
// ===== CODE
$return_proc_nice = proc_nice(

$priority // int priority - The new priority value, the value of this may differ on platforms.
// On Unix, a low value, such as -20 means high priority whereas positive values have a lower priority.
// For Windows the priority parameter has the following meaning:
// Priority class        - Possible values
// High priority         - priority < -9
// Above normal priority - priority < -4
// Normal priority       - priority < 5 & priority > -5
// Below normal priority - priority > 5
// Idle priority         - priority > 9

); // Return Values
// Returns true on success or false on failure. If an error occurs, like the user lacks permission to change the priority, an error of level E_WARNING is also generated.
// 
// Changelog
// Version - Description
// 7.2.0   - This function is now available on Windows.
// 
// [examples]
// Examples
// [example]
// Example #1 Using proc_nice() to set the process priority to high
// [php]
// // Highest priority
// proc_nice(-20);
// [/php]
// [/example]
// [/examples]
// 
// Notes
//  Note: Availability
//  proc_nice() will only exist if your system has 'nice' capabilities. 'nice' conforms to: SVr4, SVID EXT, AT&T, X/OPEN, BSD 4.3.
//  Note: Windows only
//  proc_nice() will change the current process priority, even if PHP was compiled using thread safety.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-14)
// URL: https://www.php.net/manual/en/function.proc-nice.php
// ========== PROC_NICE - END

// SYNTAX:
// bool proc_nice(int $priority)

return $return_proc_nice; // bool
}
*/
// ============================== END
// PHP_PROCESS_PROGRAMEXECUTION_PROC_NICE
// ==============================


// ============================== BEGIN
// PHP_PROCESS_PROGRAMEXECUTION_PROC_OPEN
// ============================== PUBLIC
// ============================== ABOUT
// Execute a command and open file pointers for input/output.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// proc_open() - PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_process_programexecution_proc_open($command, $descriptor_spec, & $pipes, $cwd = null, $env_vars = null, $options = null)
{
$return_proc_open = false;

// ========== PROC_OPEN - BEGIN
// ===== ABOUT
// Execute a command and open file pointers for input/output
// ===== DESCRIPTION
// proc_open() is similar to popen() but provides a much greater degree of control over the program execution.
// ===== SUPPORTED
// PHP_4 >= PHP_4_3_0, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// proc_open(
//    array|string $command,
//    array $descriptor_spec,
//    array &$pipes,
//    ?string $cwd = null,
//    ?array $env_vars = null,
//    ?array $options = null
// ): resource|false
// ===== CODE
$return_proc_open = proc_open(

$command, // array|string command - The commandline to execute as string. Special characters have to be properly escaped, and proper quoting has to be applied.
// Note: On Windows, unless bypass_shell is set to true in options, the command is passed to cmd.exe (actually, %ComSpec%) with the /c flag as unquoted string (i.e. exactly as has been given to proc_open()). This can cause cmd.exe to remove enclosing quotes from command (for details see the cmd.exe documentation), resulting in unexpected, and potentially even dangerous behavior, because cmd.exe error messages may contain (parts of) the passed command (see example below).
// As of PHP 7.4.0, command may be passed as array of command parameters. In this case the process will be opened directly (without going through a shell) and PHP will take care of any necessary argument escaping.
// Note: On Windows, the argument escaping of the array elements assumes that the command line parsing of the executed command is compatible with the parsing of command line arguments done by the VC runtime.

$descriptor_spec, // array descriptor_spec - An indexed array where the key represents the descriptor number and the value represents how PHP will pass that descriptor to the child process. 0 is stdin, 1 is stdout, while 2 is stderr.
// Each element can be:
// * An array describing the pipe to pass to the process. The first element is the descriptor type and the second element is an option for the given type. Valid types are pipe (the second element is either r to pass the read end of the pipe to the process, or w to pass the write end) and file (the second element is a filename). Note that anything else than w is treated like r.
// * A stream resource representing a real file descriptor (e.g. opened file, a socket, STDIN).
// The file descriptor numbers are not limited to 0, 1 and 2 - you may specify any valid file descriptor number and it will be passed to the child process. This allows your script to interoperate with other scripts that run as "co-processes". In particular, this is useful for passing passphrases to programs like PGP, GPG and openssl in a more secure manner. It is also useful for reading status information provided by those programs on auxiliary file descriptors.

$pipes, // array& pipes - Will be set to an indexed array of file pointers that correspond to PHP's end of any pipes that are created.

$cwd, // string cwd - The initial working dir for the command. This must be an absolute directory path, or null if you want to use the default value (the working dir of the current PHP process)

$env_vars, // array env_vars - An array with the environment variables for the command that will be run, or null to use the same environment as the current PHP process

$options // array options - Allows you to specify additional options. Currently supported options include:
// * suppress_errors (windows only)      : suppresses errors generated by this function when it's set to true
// * bypass_shell (windows only)         : bypass cmd.exe shell when set to true
// * blocking_pipes (windows only)       : force blocking pipes when set to true
// * create_process_group (windows only) : allow the child process to handle CTRL events when set to true
// * create_new_console (windows only)   : the new process has a new console, instead of inheriting its parent's console

); // Return Values
// Returns a resource representing the process, which should be freed using proc_close() when you are finished with it. On failure returns false.
// 
// Changelog
// Version - Description
// 7.4.4   - Added the create_new_console option to the options parameter.
// 7.4.0   - proc_open() now also accepts an array for the command.
// 7.4.0   - Added the create_process_group option to the options parameter.
// 
// [examples]
// Examples
// [example]
// Example #1 A proc_open() example
// [php]
// $descriptorspec = array(
//    0 => array("pipe", "r"),  // stdin is a pipe that the child will read from
//    1 => array("pipe", "w"),  // stdout is a pipe that the child will write to
//    2 => array("file", "/tmp/error-output.txt", "a") // stderr is a file to write to
// );
// 
// $cwd = '/tmp';
// $env = array('some_option' => 'aeiou');
// 
// $process = proc_open('php', $descriptorspec, $pipes, $cwd, $env);
// 
// if (is_resource($process)) {
//     // $pipes now looks like this:
//     // 0 => writeable handle connected to child stdin
//     // 1 => readable handle connected to child stdout
//     // Any error output will be appended to /tmp/error-output.txt
// 
//     fwrite($pipes[0], '< ?php print_r($_ENV); ? >');
//     fclose($pipes[0]);
// 
//     echo stream_get_contents($pipes[1]);
//     fclose($pipes[1]);
// 
//     // It is important that you close any pipes before calling
//     // proc_close in order to avoid a deadlock
//     $return_value = proc_close($process);
// 
//     echo "command returned $return_value\n";
// }
// [/php]
// The above example will output something similar to:
// [result]
// Array
// (
//     [some_option] => aeiou
//     [PWD] => /tmp
//     [SHLVL] => 1
//     [_] => /usr/local/bin/php
// )
// command returned 0
// [/result]
// [/example]
// [example]
// Example #2 proc_open() quirk on Windows
// While one may expect the following program to search the file filename.txt for the text search and to print the results, it behaves rather differently.
// [php]
// $descriptorspec = [STDIN, STDOUT, STDOUT];
// $cmd = '"findstr" "search" "filename.txt"';
// $proc = proc_open($cmd, $descriptorspec, $pipes);
// proc_close($proc);
// [/php]
// The above example will output:
// [result]
// 'findstr" "search" "filename.txt' is not recognized as an internal or external command,
// operable program or batch file.
// [/result]
// To work around that behavior, it is usually sufficient to enclose the command in additional quotes:
// [code]
// $cmd = '""findstr" "search" "filename.txt""';
// [/code]
// [/example]
// [/examples]
// 
// Notes
// Note: Windows compatibility: Descriptors beyond 2 (stderr) are made available to the child process as inheritable handles, but since the Windows architecture does not associate file descriptor numbers with low-level handles, the child process does not (yet) have a means of accessing those handles. Stdin, stdout and stderr work as expected.
// Note: If you only need a uni-directional (one-way) process pipe, use popen() instead, as it is much easier to use.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-14)
// URL: https://www.php.net/manual/en/function.proc-open.php
// ========== PROC_OPEN - END

// SYNTAX:
// resource|false proc_open(array|string $command, array $descriptor_spec, array& $pipes, string $cwd = null, array $env_vars = null, array $options = null)

return $return_proc_open; // resource|false
}
// ============================== END
// PHP_PROCESS_PROGRAMEXECUTION_PROC_OPEN
// ==============================


// ============================== BEGIN
// PHP_PROCESS_PROGRAMEXECUTION_PROC_TERMINATE
// ============================== OFFLINE
// ============================== ABOUT
// Kills a process opened by proc_open.
// ============================== SUPPORT
// PHP_5 - PHP_8
// ============================== USING FUNCTIONS (1)
// proc_terminate() - PHP_5, PHP_7, PHP_8
// ============================== CODE
/*
function php_process_programexecution_proc_terminate($process, $signal = 15)
{
$return_proc_terminate = false;

// ========== PROC_TERMINATE - BEGIN
// ===== ABOUT
// Kills a process opened by proc_open
// ===== DESCRIPTION
// Signals a process (created using proc_open()) that it should terminate. proc_terminate() returns immediately and does not wait for the process to terminate.
// proc_terminate() allows you terminate the process and continue with other tasks. You may poll the process (to see if it has stopped yet) by using the proc_get_status() function.
// ===== SUPPORTED
// PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// proc_terminate(resource $process, int $signal = 15): bool
// ===== CODE
$return_proc_terminate = proc_terminate(

$process, // resource process - The proc_open() resource that will be closed.

$signal // int signal - This optional parameter is only useful on POSIX operating systems; you may specify a signal to send to the process using the kill(2) system call. The default is SIGTERM.

); // Return Values
// Returns the termination status of the process that was run.
// ===== LITERATURE_SOURCES
// * PHP_NET (2023-09-18)
// URL: https://www.php.net/manual/en/function.proc-terminate.php
// ========== PROC_TERMINATE - END

// SYNTAX:
// bool proc_terminate(resource $process, int $signal = 15)

return $return_proc_terminate; // bool
}
*/
// ============================== END
// PHP_PROCESS_PROGRAMEXECUTION_PROC_TERMINATE
// ==============================


// ============================== BEGIN
// PHP_PROCESS_PROGRAMEXECUTION_SHELL_EXEC
// ============================== PUBLIC
// ============================== ABOUT
// Execute command via shell and return the complete output as a string.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// shell_exec() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_process_programexecution_shell_exec($command)
{
$return_shell_exec = null;

// ========== SHELL_EXEC - BEGIN
// ===== ABOUT
// Execute command via shell and return the complete output as a string
// ===== DESCRIPTION
// This function is identical to the backtick operator.
// Note: On Windows, the underlying pipe is opened in text mode which can cause the function to fail for binary output. Consider to use popen() instead for such cases.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// shell_exec(string $command): string|false|null
// ===== CODE
$return_shell_exec = shell_exec(

$command // string command - The command that will be executed.

); // Return Values
// A string containing the output from the executed command, false if the pipe cannot be established or null if an error occurs or the command produces no output.
// Note: This function can return null both when an error occurs or the program produces no output. It is not possible to detect execution failures using this function. exec() should be used when access to the program exit code is required.
// 
// Errors/Exceptions
// An E_WARNING level error is generated when the pipe cannot be established.
// 
// [examples]
// Examples
// [example]
// Example #1 A shell_exec() example
// [php]
// $output = shell_exec('ls -lart');
// echo "<pre>$output</pre>";
// [/php]
// [/example]
// [/examples]
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-14)
// URL: https://www.php.net/manual/en/function.shell-exec.php
// ========== SHELL_EXEC - END

// SYNTAX:
// string|false|null shell_exec(string $command)

return $return_shell_exec; // string|false|null
}
// ============================== END
// PHP_PROCESS_PROGRAMEXECUTION_SHELL_EXEC
// ==============================


// ============================== BEGIN
// PHP_PROCESS_PROGRAMEXECUTION_SYSTEM
// ============================== PUBLIC
// ============================== ABOUT
// Execute an external program and display the output.
// ============================== SUPPORT
// PHP_4 - PHP_8
// ============================== USING FUNCTIONS (1)
// system() - PHP_4, PHP_5, PHP_7, PHP_8
// ============================== CODE
function php_process_programexecution_system($command, & $result_code)
{
$return_system = false;

// ========== SYSTEM - BEGIN
// ===== ABOUT
// Execute an external program and display the output
// ===== DESCRIPTION
// system() is just like the C version of the function in that it executes the given command and outputs the result.
// The system() call also tries to automatically flush the web server's output buffer after each line of output if PHP is running as a server module.
// If you need to execute a command and have all the data from the command passed directly back without any interference, use the passthru() function.
// ===== SUPPORTED
// PHP_4, PHP_5, PHP_7, PHP_8
// ===== SYNTAX
// system(string $command, int &$result_code = null): string|false
// ===== CODE
$return_system = system(

$command, // string command - The command that will be executed.

$result_code // int& result_code - If the result_code argument is present, then the return status of the executed command will be written to this variable.

); // Return Values
// Returns the last line of the command output on success, and false on failure.
// 
// [examples]
// Examples
// [example]
// Example #1 system() example
// [php]
// echo '<pre>';
// 
// // Outputs all the result of shellcommand "ls", and returns
// // the last output line into $last_line. Stores the return value
// // of the shell command in $retval.
// $last_line = system('ls', $retval);
// 
// // Printing additional info
// echo '
// </pre>
// <hr />Last line of the output: ' . $last_line . '
// <hr />Return value: ' . $retval;
// [/php]
// [/example]
// [/examples]
// 
// Notes
// Warning: When allowing user-supplied data to be passed to this function, use escapeshellarg() or escapeshellcmd() to ensure that users cannot trick the system into executing arbitrary commands.
// Note: If a program is started with this function, in order for it to continue running in the background, the output of the program must be redirected to a file or another output stream. Failing to do so will cause PHP to hang until the execution of the program ends.
// ===== LITERATURE_SOURCES
// * PHP_NET (2024-01-14)
// URL: https://www.php.net/manual/en/function.system.php
// ========== SYSTEM - END

// SYNTAX:
// string|false system(string $command, int& $result_code)

return $return_system; // string|false
}
// ============================== END
// PHP_PROCESS_PROGRAMEXECUTION_SYSTEM
// ==============================


// ============================== END
//  PHP_PROCESS_PROGRAMEXECUTION  
// ==============================
?>