Previous section To contents Next section

14.2 Process

The Process module contains functions to start and control other programs from Pike.

CLASS
Process.create_process - Create a new process

SYNTAX
Process.create_process Process.create_process(array(string) command, void | mapping(string:mixed) modifiers);

DESCRIPTION
This is the recommended and most portable way to start processes in Pike. The command name and arguments are sent as an array of strings so that you do not have to worry about qouting them. The optional mapping modifiers can can contain zero or more of the following parameters:
"cwd" : string dir
This parameter executes 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.
"stdin" : Stdio.File stdin
"stdout" : Stdio.File stdout
"stderr" : Stdio.File stderr
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.
"env" : mapping(string:string) env
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. Example: 
(["env" : getenv() + (["TERM":"vt100"])
.
The following options are only available on some systems.
"uid" : int|string uid
This parameter changes which user the new process will execute as. Note that the current process must be running as root to use this option. The uid can be given either as an integer as a string containing the login name of that user. Please note that using a string here can be noticably slower than using an integer. The "gid" and "groups" for the new process will be set to the right values for that user unless overriden by opions blow. If maximum performance is an issue, you should use the "gid" and "group" options to set those values explicitly. (See setuid and getpwuid for more info)
"gid" : int|string gid
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. As with the "uid" parameters, integers are faster than numbers. (See setgid and getgrgid for more info)
"setgroups" : array(int|string) groups
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 at no more than 16 groups. (Some system only supports 8 groups even...) The groups can be given as gids or as strings with the group names. If maximum performance is an issue, please use integers.
"noinitgroups" : int(0..1) yesno
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 pri
This sets the priority of the new process, see set_priority for more info.
"nice" : int nice
This sets the nice level of the new process. Note that a negative number means higher priority positive numbers means higher priority. Only root may use negative numbers.
"keep_signals" : int(0..1) yesno
This prevents Pike to restore all signal handlers to their default value for the new process. Useful to ignore certain signals in the new process.
"fds" : array(Stdio.File|zero) fds
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.
These parameter limits the new process in certain ways, they are not available on all systems. Each of these can either be given as a mapping (["soft":soft_limit,"hard":hard_limit]) or as an integer. If an integer is given both the hard limit and the soft limit will be changed. The new process may change the soft limit, but may not change it any higher than the hard limit.
"cpu" : int|mapping(string:int) seconds
Limit the CPU time of the new process.
"core" : int|mapping(string:int) bytes
Limit the core file size.
"data" : int|mapping(string:int) bytes
Limit the data size of the new process.
"fsize" : int|mapping(string:int) bytes
Limits the maximum file size of the new process.
"nofile" : int|mapping(string:int) num_files
Maximum open files for the new process.
"stack" : int|mapping(string:int) bytes
Limit the stack size of the nwe process.
"map_mem" : int|mapping(string:int) bytes
"vmem" : int|mapping(string:int) vmem
Maximum amount of mmapped memory.
"as" : int|mapping(string:int) memory
"mem" : int|mapping(string:int) memory
Maximum amount of total memory.

SEE ALSO
Process.popen and Process.system

METHOD
Process.create_process.set_priority - Set the priority of this process

SYNTAX
int set_priority(string pri);

DESCRIPTION
This function sets the priority of this process, the string pri should be one of:
"realtime" or "highest" This gives the process realtime priority, this basically gives the process access to the cpu whenever it wants.
"higher" This gives the process higher priority than most other processes on your system.
"high" This gives your proces a little bit higher priority than what is 'normal'.
"normal" This sets the process' priority to whatever is 'normal' for new processes on your system.
"low" This will give the process a lower priority than what is normal on your system.
"lowest" This will give the process a lower priority than most processes on your system.

METHOD
Process.create_process.wait - Wait for this process to finish

SYNTAX
int wait();

DESCRIPTION
This function makes the calling thread wait for the process to finish. It returns the exit code of that process.

METHOD
Process.create_process.status - Check if process is still running

SYNTAX
int status();

DESCRIPTION
This function returns zero if the process is still running. If the process has exited, it will return one.

METHOD
Process.create_process.pid - Get the process id of this process

SYNTAX
int pid();

DESCRIPTION
This function returns the process identifier for the process.

METHOD
Process.create_process.kill - Kill this process

SYNTAX
int kill(int signal);

DESCRIPTION
This function sends the given signal to the process, it returns one if the operation succeded, zero otherwise.

SEE ALSO
signum

FUNCTION
Process.popen - pipe open

SYNTAX
string popen(string cmd);

DESCRIPTION
This function runs the command cmd as in a shell and returns the output. See your Unix/C manual for details on popen.

FUNCTION
Process.system - run an external program

SYNTAX
void system(string cmd);

DESCRIPTION
This function runs the external program cmd and waits until it is finished. Standard /bin/sh completions/redirections/etc. can be used.

SEE ALSO
Process.create_process, Process.popen, Process.exec and Process.spawn

FUNCTION
Process.spawn - spawn a process

SYNTAX
int spawn(string cmd);
int spawn(string cmd, object stdin);
int spawn(string cmd, object stdin, object stdout);
int spawn(string cmd, object stdin, object stdout, object stderr);

DESCRIPTION
This function spawns a process but does not wait for it to finish. Optionally, clones of Stdio.File can be sent to it to specify where stdin, stdout and stderr of the spawned processes should go.

SEE ALSO
Process.popen, fork, Process.exec, Stdio.File->pipe and Stdio.File->dup2

FUNCTION
Process.exece - execute a program

SYNTAX
int exece(string file, array(string) args);
int exece(string file, array(string) args, mapping(string:string) env);

DESCRIPTION
This function transforms the Pike process into a process running the program specified in the argument file with the argument args. If the mapping env is present, it will completely replace all environment variables before the new program is executed. This function only returns if something went wrong during exece(), and in that case it returns zero.

NOTE
The Pike driver _dies_ when this function is called. You must use fork() if you wish to execute a program and still run the Pike driver.

EXAMPLE
exece("/bin/ls", ({"-l"}));
exece("/bin/sh", ({"-c", "echo $HOME"}), (["HOME":"/not/home"]));

SEE ALSO
fork and Stdio.File->pipe

FUNCTION
Process.exec - simple way to use exece()

SYNTAX
int exec(string file, string ... args);

DESCRIPTION
This function destroys the Pike parser and runs the program file instead with the arguments. If no there are no '/' in the filename, the variable PATH will be consulted when looking for the program. This function does not return except when the exec fails for some reason.

EXAMPLE
exec("/bin/echo","hello","world");

CLASS
Process.Spawn - spawn off another program with control structure

SYNTAX
object Process.Spawn(string program, void|array(string) args, void|mapping(string:string) env, void|string cwd);
or object Process.Spawn(string program, void|array(string) args, void|mapping(string:string) env, void|string cwd, array(void|object(Stdio.file)) fds, void|array(void|object(Stdio.file)) fds_to_close);

DESCRIPTION
Spawn off another program (program) and creates the control structure. This does not spawn off a shell to find the program, therefore must program be the full path the the program.

args is per default no argument(s),

env is reset to the given mapping, or kept if the argument is 0. fds is your stdin, stdout and stderr. Default is local pipes (see stdin et al). fds_to_close is file descriptors that are closed in the forked branch when the program is executed (ie, the other end of the pipes).

VARIABLE
Process.Spawn.stdin,
Process.Spawn.stdout,
Process.Spawn.stderr,
Process.Spawn.fd - pipes to the program

SYNTAX
object(Stdio.File) stdin;
object(Stdio.File) stdout;
object(Stdio.File) stderr;
array(void|object(Stdio.File)) fd;

DESCRIPTION
Pipes to the spawned program (if set). fd[0]==stdin, etc.

VARIABLE
Process.Spawn.pid - spawned program pid

SYNTAX
int pid;

DESCRIPTION
pid of the spawned program.

METHOD
Process.Spawn.wait - wait for the spawned program to finish

SYNTAX
void wait();

DESCRIPTION
Returns when the program has exited.

METHOD
Process.Spawn.kill - send a signal to the program

SYNTAX
int kill(int signal);

DESCRIPTION
Sends a signal to the program.
Previous section To contents Next section