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.
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.
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.
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.
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"
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)
Optional trailing argument options is a hash of execution options.
: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"
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.
: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.
: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.
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.
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.
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
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*
::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.
::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.
::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.
::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.
::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.
Add a list of paths to the $LOAD_PATH at the proper place.
Converts this AvailableSet into a RequestSet that can be used to install gems.
If development is :none then no development dependencies are installed. Other options are :shallow for only direct development dependencies of the gems in this set or :all for all development dependencies.
It is ok to remove a gemspec from the dependency list?
If removing the gemspec creates breaks a currently ok dependency, then it is NOT ok to remove the gemspec.
Given a name and requirement, downloads this gem into cache and returns the filename. Returns nil if the gem cannot be located.
Turns email_address into an OpenSSL::X509::Name
Serializes the DH parameters to a PEM-encoding.
Note that any existing per-session public/private keys will not get encoded, just the Diffie-Hellman parameters will be encoded.
PEM-encoded parameters will look like:
-----BEGIN DH PARAMETERS----- [...] -----END DH PARAMETERS-----
See also public_to_pem (X.509 SubjectPublicKeyInfo) and private_to_pem (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) for serialization with the private or public key components.
Serializes a private or public key to a PEM-encoding.
Serializes it into an X.509 SubjectPublicKeyInfo. The parameters cipher and password are ignored.
A PEM-encoded key will look like:
-----BEGIN PUBLIC KEY----- [...] -----END PUBLIC KEY-----
Consider using public_to_pem instead. This serializes the key into an X.509 SubjectPublicKeyInfo regardless of whether it is a public key or a private key.
Serializes it into a traditional OpenSSL DSAPrivateKey.
A PEM-encoded key will look like:
-----BEGIN DSA PRIVATE KEY----- [...] -----END DSA PRIVATE KEY-----
Serializes it into a traditional OpenSSL DSAPrivateKey and encrypts it in OpenSSL’s traditional PEM encryption format. cipher must be a cipher name understood by OpenSSL::Cipher.new or an instance of OpenSSL::Cipher.
An encrypted PEM-encoded key will look like:
-----BEGIN DSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0 [...] -----END DSA PRIVATE KEY-----
Note that this format uses MD5 to derive the encryption key, and hence will not be available on FIPS-compliant systems.
This method is kept for compatibility. This should only be used when the traditional, non-standard OpenSSL format is required.
Consider using public_to_pem (X.509 SubjectPublicKeyInfo) or private_to_pem (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
Serializes a private or public key to a PEM-encoding.
Serializes it into an X.509 SubjectPublicKeyInfo. The parameters cipher and password are ignored.
A PEM-encoded key will look like:
-----BEGIN PUBLIC KEY----- [...] -----END PUBLIC KEY-----
Consider using public_to_pem instead. This serializes the key into an X.509 SubjectPublicKeyInfo regardless of whether the key is a public key or a private key.
Serializes it into a PKCS #1 RSAPrivateKey.
A PEM-encoded key will look like:
-----BEGIN RSA PRIVATE KEY----- [...] -----END RSA PRIVATE KEY-----
Serializes it into a PKCS #1 RSAPrivateKey and encrypts it in OpenSSL’s traditional PEM encryption format. cipher must be a cipher name understood by OpenSSL::Cipher.new or an instance of OpenSSL::Cipher.
An encrypted PEM-encoded key will look like:
-----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: AES-128-CBC,733F5302505B34701FC41F5C0746E4C0 [...] -----END RSA PRIVATE KEY-----
Note that this format uses MD5 to derive the encryption key, and hence will not be available on FIPS-compliant systems.
This method is kept for compatibility. This should only be used when the PKCS #1 RSAPrivateKey format is required.
Consider using public_to_pem (X.509 SubjectPublicKeyInfo) or private_to_pem (PKCS #8 PrivateKeyInfo or EncryptedPrivateKeyInfo) instead.
Returns a String representation of the Distinguished Name. format is one of:
If format is omitted, the largely broken and traditional OpenSSL format (X509_NAME_oneline() format) is chosen.
Use of this method is discouraged. None of the formats other than OpenSSL::X509::Name::RFC2253 is standardized and may show an inconsistent behavior through OpenSSL versions.
It is recommended to use to_utf8 instead, which is equivalent to calling name.to_s(OpenSSL::X509::Name::RFC2253).force_encoding("UTF-8").
Returns the PEM encoding of this SPKI.
returns the domain name as a string.
The domain name doesn’t have a trailing dot even if the name object is absolute.
Example:
p Resolv::DNS::Name.create("x.y.z.").to_s #=> "x.y.z" p Resolv::DNS::Name.create("x.y.z").to_s #=> "x.y.z"
The contents of the lock file.