| Extracted from Pike v7.8 release 866 at 2018-02-09.

[Top]
Process
Process.create_process

# Method Process.create_process()->create()

Method create

  `void Process.create_process(array(string) command_args, void|mapping modifiers)`

Parameter `command_args`

  The command name and its command-line arguments. You do not have to worry about quoting them; pike does this for you.

Parameter `modifiers`

  This optional mapping can can contain zero or more of the following parameters:

  `"callback" : function(Process.Process:void)` | Function called when the created process changes state.
  `"cwd" : string` | Execute the command in another directory than the current directory of this process. Please note that if the command is given is a relative path, it will be relative to this directory rather than the current directory of this process.
  `"chroot" : string` | Chroot to this directory before executing the command.
  `"stdin" : Stdio.File` | These parameters allows you to change the standard input, output and error streams of the newly created process. This is particularly useful in combination with Stdio.File.pipe .
  `"stdout" : Stdio.File`
  `"stderr" : Stdio.File`
  `"env" : mapping(string:string)` | This mapping will become the environment variables for the created process. Normally you will want to only add or change variables which can be achived by getting the environment mapping for this process with getenv . See the examples section.

  `"uid" : int|string`

  This parameter changes which user the new process will execute as. Note that the current process must be running as UID 0 to use this option. The uid can be given either as an integer as a string containing the login name of that user.

  The "gid" and "groups" for the new process will be set to the right values for that user unless overriden by options below.

  (See setuid and getpwuid for more info.)

  `"gid" : int|string` | This parameter changes the primary group for the new process. When the new process creates files, they will will be created with this group. The group can either be given as an int or a string containing the name of the group. (See setuid and getgrgid for more info.)
  `"setsid" : int(0..1)|Stdio.File` | Set this to `1` to create a new session group. It is also possible to set it to a File object, in which case a new session group will be created with this file as the controlling terminal.
  `"setgroups" : array(int|string)` | This parameter allows you to the set the list of groups that the new process belongs to. It is recommended that if you use this parameter you supply at least one and no more than 16 groups. (Some system only support up to 8...) The groups can be given as gids or as strings with the group names.
  `"noinitgroups" : int(0..1)` | This parameter overrides a behaviour of the "uid" parameter. If this parameter is used, the gid and groups of the new process will be inherited from the current process rather than changed to the approperiate values for that uid.
  `"priority" : string` | This sets the priority of the new process, see set_priority for more info.
  `"nice" : int` | This sets the nice level of the new process; the lower the number, the higher the priority of the process. Note that only UID 0 may use negative numbers.
  `"keep_signals" : int(0..1)` | This prevents Pike from restoring all signal handlers to their default values for the new process. Useful to ignore certain signals in the new process.
  `"fds" : array(Stdio.File|int(0..0))` | This parameter allows you to map files to filedescriptors 3 and up. The file `fds[0]` will be remapped to fd 3 in the new process, etc.

  `"rlimit" : mapping(string:limit_value)`

  There are two values for each limit, the soft limit and the hard limit. Processes that do not have UID 0 may not raise the hard limit, and the soft limit may never be increased over the hard limit. The indices of the mapping indicate what limit to impose, and the values dictate what the limit should be. (See also System.setrlimit )

  `"core" : limit_value` | maximum core file size in bytes
  `"cpu" : limit_value` | maximum amount of cpu time used by the process in seconds
  `"data" : limit_value` | maximum heap (brk, malloc) size in bytes
  `"fsize" : limit_value` | maximum size of files created by the process in bytes
  `"map_mem" : limit_value` | maximum size of the process's mapped address space (mmap() and heap size) in bytes
  `"mem" : limit_value` | maximum size of the process's total amount of available memory (mmap, heap and stack size) in bytes
  `"nofile" : limit_value` | maximum number of file descriptors the process may create
  `"stack" : limit_value` | maximum stack size in bytes

Example

      Process.create_process(({ "/usr/bin/env" }),
                              (["env" : getenv() + (["TERM":"vt100"]) ]));

Example

      //! Spawn a new process with the args @[args] and optionally a
       //! standard input if you provide such a @[Stdio.File] object.
       //! @returns
       //!   Returns the new process and a pipe from which you can read
       //!   its output.
       array(Process.Process|Stdio.File) spawn(Stdio.File|void stdin, string ... args)
       {
         Stdio.File stdout = Stdio.File();
         mapping opts = ([ "stdout" : stdout->pipe() ]);
         if( stdin )
          opts->stdin = stdin;
         return ({ Process.create_process( args, opts ), stdout });
       }

Note

  All parameters that accept both string or int input can be noticeably slower using a string instead of an integer; if maximum performance is an issue, please use integers.

Note

  The modifiers `"callback"`, `"fds"`, `"uid"`, `"gid"`, `"nice"`, `"noinitgroups"`, `"setgroups"`, `"keep_signals"` and `"rlimit"` only exist on unix.

Note

  Support for `"callback"` was added in Pike 7.7.