Top Level Namespace

Module ::Process represents a process in the underlying operating system. Its methods support management of the current process and its child processes.

Process Creation

Each of the following methods executes a given command in a new process or subshell, or multiple commands in new processes and/or subshells. The choice of process or subshell depends on the form of the command; see Argument command_line or exe_path.

• Process.spawn, Kernel.spawn: Executes the command; returns the new pid without waiting for completion.

• Process.exec: Replaces the current process by executing the command.

In addition:

• Method Kernel.system executes a given command-line (string) in a subshell; returns true, false, or nil.

• Method Kernel.‘ executes a given command-line (string) in a subshell; returns its $stdout string.

• Module Open3 supports creating child processes with access to their $stdin, $stdout, and $stderr streams.

Execution Environment

Optional leading argument env is a hash of name/value pairs, where each name is a string and each value is a string or nil; each name/value pair is added to ::ENV in the new process.

Process.spawn(                'ruby -e "p ENV[\"Foo\"]"')
Process.spawn({'Foo' => '0'}, 'ruby -e "p ENV[\"Foo\"]"')

Output:

"0"

The effect is usually similar to that of calling ENV#update with argument env, where each named environment variable is created or updated (if the value is non-nil), or deleted (if the value is nil).

However, some modifications to the calling process may remain if the new process fails. For example, hard resource limits are not restored.

Argument command_line or exe_path

The required string argument is one of the following:

• command_line if it begins with a shell reserved word or special built-in, or if it contains one or more meta characters.

• exe_path otherwise.

Argument command_line

String argument command_line is a command line to be passed to a shell; it must begin with a shell reserved word, begin with a special built-in, or contain meta characters:

system('if true; then echo "Foo"; fi')          # => true  # Shell reserved word.
system('echo')                                  # => true  # Built-in.
system('date > /tmp/date.tmp')                  # => true  # Contains meta character.
system('date > /nop/date.tmp')                  # => false
system('date > /nop/date.tmp', exception: true) # Raises RuntimeError.

The command line may also contain arguments and options for the command:

system('echo "Foo"') # => true

Output:

Foo

See Execution Shell for details about the shell.

Argument exe_path

Argument exe_path is one of the following:

• The string path to an executable to be called.

• A 2-element array containing the path to an executable to be called, and the string to be used as the name of the executing process.

Example:

system('/usr/bin/date') # => true # Path to date on Unix-style system.
system('foo')           # => nil  # Command failed.

Output:

Mon Aug 28 11:43:10 AM CDT 2023

Execution Options

Optional trailing argument options is a hash of execution options.

Working Directory (:chdir)

By default, the working directory for the new process is the same as that of the current process:

Dir.chdir('/var')
Process.spawn('ruby -e "puts Dir.pwd"')

Output:

/var

Use option :chdir to set the working directory for the new process:

Process.spawn('ruby -e "puts Dir.pwd"', {chdir: '/tmp'})

Output:

/tmp

The working directory of the current process is not changed:

Dir.pwd # => "/var"

File Redirection (File Descriptor)

Use execution options for file redirection in the new process.

The key for such an option may be an integer file descriptor (fd), specifying a source, or an array of fds, specifying multiple sources.

An integer source fd may be specified as:

• n: Specifies file descriptor n.

There are these shorthand symbols for fds:

• :in: Specifies file descriptor 0 (STDIN).

• :out: Specifies file descriptor 1 (STDOUT).

• :err: Specifies file descriptor 2 (STDERR).

The value given with a source is one of:

• n: Redirects to fd n in the parent process.

• filepath: Redirects from or to the file at filepath via open(filepath, mode, 0644), where mode is 'r' for source :in, or 'w' for source :out or :err.

• [filepath]: Redirects from the file at filepath via open(filepath, 'r', 0644).

• [filepath, mode]: Redirects from or to the file at filepath via open(filepath, mode, 0644).

• [filepath, mode, perm]: Redirects from or to the file at filepath via open(filepath, mode, perm).

• [:child, fd]: Redirects to the redirected fd.

• :close: Closes the file descriptor in child process.

See Access Modes and {File Permissions}.

Environment Variables (:unsetenv_others)

By default, the new process inherits environment variables from the parent process; use execution option key :unsetenv_others with value true to clear environment variables in the new process.

Any changes specified by execution option env are made after the new process inherits or clears its environment variables; see Execution Environment.

File-Creation Access (:umask)

Use execution option :umask to set the file-creation access for the new process; see Access Modes:

command = 'ruby -e "puts sprintf(\"0%o\", File.umask)"'
options = {:umask => 0644}
Process.spawn(command, options)

Output:

0644

Process Groups (:pgroup and :new_pgroup)

By default, the new process belongs to the same process group as the parent process.

To specify a different process group. use execution option :pgroup with one of the following values:

• true: Create a new process group for the new process.

• pgid: Create the new process in the process group whose id is pgid.

On Windows only, use execution option :new_pgroup with value true to create a new process group for the new process.

Resource Limits

Use execution options to set resource limits.

The keys for these options are symbols of the form :rlimit_resource_name, where resource_name is the downcased form of one of the string resource names described at method Process.setrlimit. For example, key :rlimit_cpu corresponds to resource limit 'CPU'.

The value for such as key is one of:

• An integer, specifying both the current and maximum limits.

• A 2-element array of integers, specifying the current and maximum limits.

File Descriptor Inheritance

By default, the new process inherits file descriptors from the parent process.

Use execution option :close_others => true to modify that inheritance by closing non-standard fds (3 and greater) that are not otherwise redirected.

Execution Shell

On a Unix-like system, the shell invoked is /bin/sh; otherwise the shell invoked is determined by environment variable ENV['RUBYSHELL'], if defined, or ENV['COMSPEC'] otherwise.

Except for the COMSPEC case, the entire string command_line is passed as an argument to shell option -c.

The shell performs normal shell expansion on the command line:

spawn('echo C*') # => 799139
Process.wait     # => 799139

Output:

CONTRIBUTING.md COPYING COPYING.ja

What’s Here

Current-Process Getters

• .argv0: Returns the process name as a frozen string.

• .egid: Returns the effective group ID.

• .euid: Returns the effective user ID.

• .getpgrp: Return the process group ID.

• .getrlimit: Returns the resource limit.

• .gid: Returns the (real) group ID.

• .pid: Returns the process ID.

• .ppid: Returns the process ID of the parent process.

• .uid: Returns the (real) user ID.

Current-Process Setters

• .egid=: Sets the effective group ID.

• .euid=: Sets the effective user ID.

• .gid=: Sets the (real) group ID.

• .setproctitle: Sets the process title.

• .setpgrp: Sets the process group ID of the process to zero.

• .setrlimit: Sets a resource limit.

• .setsid: Establishes the process as a new session and process group leader, with no controlling tty.

• .uid=: Sets the user ID.

Current-Process Execution

• .abort: Immediately terminates the process.

• .daemon: Detaches the process from its controlling terminal and continues running it in the background as system daemon.

• .exec: Replaces the process by running a given external command.

• .exit: Initiates process termination by raising exception ::SystemExit (which may be caught).

• .exit!: Immediately exits the process.

• .warmup: Notifies the Ruby virtual machine that the boot sequence for the application is completed, and that the VM may begin optimizing the application.

Child Processes

• .detach: Guards against a child process becoming a zombie.

• .fork: Creates a child process.

• .kill: Sends a given signal to processes.

• .spawn: Creates a child process.

• .wait, .waitpid: Waits for a child process to exit; returns its process ID.

• .wait2, .waitpid2: Waits for a child process to exit; returns its process ID and status.

• .waitall: Waits for all child processes to exit; returns their process IDs and statuses.

Process Groups

• .getpgid: Returns the process group ID for a process.

• .getpriority: Returns the scheduling priority for a process, process group, or user.

• .getsid: Returns the session ID for a process.

• .groups: Returns an array of the group IDs in the supplemental group access list for this process.

• .groups=: Sets the supplemental group access list to the given array of group IDs.

• .initgroups: Initializes the supplemental group access list.

• .last_status: Returns the status of the last executed child process in the current thread.

• .maxgroups: Returns the maximum number of group IDs allowed in the supplemental group access list.

• .maxgroups=: Sets the maximum number of group IDs allowed in the supplemental group access list.

• .setpgid: Sets the process group ID of a process.

• .setpriority: Sets the scheduling priority for a process, process group, or user.

Timing

• .clock_getres: Returns the resolution of a system clock.

• .clock_gettime: Returns the time from a system clock.

• .times: Returns a ::Process::Tms object containing times for the current process and its child processes.