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('exit')                                  # => 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 file to be called:

  Example:

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

  Output:

  Thu Aug 31 10:06:48 AM CDT 2023

  A path or command name containing spaces without arguments cannot be distinguished from command_line above, so you must quote or escape the entire command name using a shell in platform dependent manner, or use the array form below.

  If exe_path does not contain any path separator, an executable file is searched from directories specified with the PATH environment variable. What the word “executable” means here is depending on platforms.

  Even if the file considered “executable”, its content may not be in proper executable format. In that case, Ruby tries to run it by using /bin/sh on a Unix-like system, like system(3) does.

  File.write('shell_command', 'echo $SHELL', perm: 0o755)
  system('./shell_command')        # prints "/bin/sh" or something.

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

  Example:

  pid = spawn(['sleep', 'Hello!'], '1') # 2-element array.
  p `ps -p #{pid} -o command=`

  Output:

  "Hello! 1\n"

Arguments args

If command_line does not contain shell meta characters except for spaces and tabs, or exe_path is given, Ruby invokes the executable directly. This form does not use the shell:

spawn("doesnt_exist")       # Raises Errno::ENOENT
spawn("doesnt_exist", "\n") # Raises Errno::ENOENT

spawn("doesnt_exist\n")     # => false
# sh: 1: doesnot_exist: not found

The error message is from a shell and would vary depending on your system.

If one or more args is given after exe_path, each is an argument or option to be passed to the executable:

Example:

system('echo', '<', 'C*', '|', '$SHELL', '>')   # => true

Output:

< C* | $SHELL >

However, there are exceptions on Windows. See Execution Shell on Windows.

If you want to invoke a path containing spaces with no arguments without shell, you will need to use a 2-element array exe_path.

Example:

path = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
spawn(path) # Raises Errno::ENOENT; No such file or directory - /Applications/Google
spawn([path] * 2)

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; the entire string command_line is passed as an argument to shell option -c.

The shell performs normal shell expansion on the command line:

Example:

system('echo $SHELL: C*') # => true

Output:

/bin/bash: CONTRIBUTING.md COPYING COPYING.ja

Execution Shell on Windows

On Windows, the shell invoked is determined by environment variable RUBYSHELL, if defined, or COMSPEC otherwise; the entire string command_line is passed as an argument to -c option for RUBYSHELL, as well as /bin/sh, and /c option for COMSPEC. The shell is invoked automatically in the following cases:

• The command is a built-in of cmd.exe, such as echo.

• The executable file is a batch file; its name ends with .bat or .cmd.

Note that the command will still be invoked as command_line form even when called in exe_path form, because cmd.exe does not accept a script name like /bin/sh does but only works with /c option.

The standard shell cmd.exe performs environment variable expansion but does not have globbing functionality:

Example:

system("echo %COMSPEC%: C*")' # => true

Output:

C:\WINDOWS\system32\cmd.exe: C*

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.