pcntl_exec

    (PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

    pcntl_exec — Executes specified program in current process space

    Description

    function pcntl_exec(string $path, array $args = [], array $env_vars = []): false

    Executes the program with the given arguments.

    Parameters

    path

    path must be the path to a binary executable or a script with a valid path pointing to an executable in the shebang ( #!/usr/local/bin/perl for example) as the first line. See your system's man execve(2) page for additional information.

    args

    args is an array of argument strings passed to the program.

    env_vars

    env_vars is an array of strings which are passed as environment to the program. The array is in the format of name => value, the key being the name of the environmental variable and the value being the value of that variable.

    Return Values

    Returns false on failure. On success the function does not return, because the current process image is replaced by the executed program.

    Errors/Exceptions

    As of PHP 8.5.0, a ValueError is thrown if any entry of args contains a null byte, or if any entry or key of env_vars contains a null byte.

    Changelog

    Version Description
    8.5.0 A ValueError is now thrown if any entry of args contains a null byte, or if any entry or key of env_vars contains a null byte.

    See Also

    • pcntl_fork() - Forks the currently running process
    • pcntl_waitpid() - Waits on or returns the status of a forked child
    • exec() - Execute an external program
    • proc_open() - Execute a command and open file pointers for input/output

    Found A Problem?

    Learn How To Improve This Page • Submit a Pull Request • Report a Bug
    ＋add a note

    User Contributed Notes 3 notes

    up
    15
    agodong at verizon dot net
    19 years ago
    Some people might find it useful to run other program using the same process as a different user. This is very usefull if the script is running under root. Here is a simple code to achieve that under *nix PHP CLI:

#!/usr/bin/php -q
<?php
//Enter run-as user below (argument needed to be passed when the script is called), otherwise it will run as the caller user process.

$username = $_SERVER['argv'][1];

$user = posix_getpwnam($username);
posix_setuid($user['uid']);
posix_setgid($user['gid']);
pcntl_exec('/path/to/cmd');
?>

I use this as a part of socket program so that a program can be run under different user from remote location.
    up
    10
    eric kilfoil
    19 years ago
    The pcntl_exec() function works exactly like the standard (unix-style) exec() function.  It differs from the regular PHP exec() function in that the process calling the pcntl_exec() is replaced with the process that gets called.  This is the ideal method for creating children.  In a simple example (that does no error checking):

switch (pcntl_fork()) {
  case 0:
    $cmd = "/path/to/command";
    $args = array("arg1", "arg2");
    pcntl_exec($cmd, $args);
    // the child will only reach this point on exec failure,
    // because execution shifts to the pcntl_exec()ed command
    exit(0);
  default:
    break;
}

// parent continues
echo "I am the parent";

--

since this is not being executed through a shell, you must provide the exact path from the filesystem root.  Look at the execve() man page for more information.
    up
    1
    rbemrose at vgmusic dot com
    18 years ago
    As a side note, if I'm reading the comments below correctly, you should not run this if you're using a PHP webserver module, as it will replace the webserver's process with whatever process you're telling it to run.
    ＋add a note
    To Top