Class Process.create_process

Inheritance graph

Description: This is the recommended and most portable way to start processes in Pike. The process object is a pike abstraction of the running system process, with methods for various process housekeeping.
See also: Process

Constant limit_value

constant Process.create_process.limit_value

Description

Each limit_value may be either of:

integer: sets current limit, max is left as it is.
mapping: ([ "hard":int, "soft":int ]) Both values are optional, hard <= soft.
array: ({ hard, soft }), both can be set to the string "unlimited". A value of -1 means 'keep the old value'.
string: The string "unlimited" sets both the hard and soft limit to unlimited

Method create

Process.create_process 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.

Note that this function is called in a signal handler context, which means that it may be called by any thread at any time after the child process has changed state, and is thus not only called by the main thread when the main backend is idle. Indeed, you can specify a callback even if your program does not use a backend.

"cwd" : string|Stdio.Fd

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.

Note also that the path is relative to the "chroot" if used.

Note that support for the Stdio.Fd variant is not present prior to Pike 9.0, and is only present on some OSes.

"chroot" : string|Stdio.Fd

Chroot to this directory before executing the command.

Note that the current directory will be changed to "/" in the chroot environment, unless "cwd" above has been set.

Note that support for the Stdio.Fd variant is not present prior to Pike 9.0, and is only present on some OSes.

"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" : bool|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" : bool

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" : bool

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))

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

"conpty" : Stdio.File

Bind the process to the console associated with this pty slave. NT only.

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

On NT the only supported modifiers are: "cwd", "conpty", "stdin", "stdout", "stderr" and "env". All other modifiers are silently ignored.

Note

Support for "callback" was added in Pike 7.7.

Note

Chroot changing directory to "/" was added in Pike 7.9.