Process -

# class Process

- Process
- Reference
- Object

## Defined in:

## Constant Summary

ORIGINAL_STDERR = `IO::FileDescriptor.new(2, blocking: true)`
ORIGINAL_STDIN = `IO::FileDescriptor.new(0, blocking: true)`
ORIGINAL_STDOUT = `IO::FileDescriptor.new(1, blocking: true)`
PATH_DELIMITER = `{% if flag?(:windows) %} ';' {% else %} ':' {% end %}`

## Constructors

- .fork : Process?

  Duplicates the current process.

- .fork(&block) : Process

  Runs the given block inside a new process and returns a `Process` representing the new child process.

- .new(command : String, args = nil, env : Env = nil, clear_env : Bool = false, shell : Bool = false, input : Stdio = Redirect::Close, output : Stdio = Redirect::Close, error : Stdio = Redirect::Close, chdir : String? = nil)

  Creates a process, executes it, but doesn't wait for it to complete.

## Class Method Summary

- .after_fork_child_callbacks

  Hooks are defined here due to load order problems.

- .chroot(path : String) : Nil

  Changes the root directory and the current working directory for the current process.

- .exec(command : String, args = nil, env : Env = nil, clear_env : Bool = false, shell : Bool = false, input : ExecStdio = Redirect::Inherit, output : ExecStdio = Redirect::Inherit, error : ExecStdio = Redirect::Inherit, chdir : String? = nil)

  Replaces the current process with a new one.

- .executable_path

  Returns an absolute path to the executable file of the currently running program.

- .exists?(pid : Int)

  Returns `true` if the process identified by pid is valid for a currently registered process, `false` otherwise.

- .exit(status = 0)

  Terminate the current process immediately.

- .find_executable(name, path = ENV["PATH"]?, pwd = Dir.current)

  Searches an executable, checking for an absolute path, a path relative to pwd or absolute path, then eventually searching in directories declared in path.

- .kill(signal : Signal, *pids : Int)

  Sends a signal to the processes identified by the given pids.

- .pgid : LibC::PidT

  Returns the process group identifier of the current process.

- .pgid(pid : Int32) : LibC::PidT

  Returns the process group identifier of the process identified by pid.

- .pid : LibC::PidT

  Returns the process identifier of the current process.

- .ppid : LibC::PidT

  Returns the process identifier of the parent process of the current process.

- .run(command : String, args = nil, env : Env = nil, clear_env : Bool = false, shell : Bool = false, input : Stdio = Redirect::Close, output : Stdio = Redirect::Close, error : Stdio = Redirect::Close, chdir : String? = nil) : Process::Status

  Executes a process and waits for it to complete.

- .run(command : String, args = nil, env : Env = nil, clear_env : Bool = false, shell : Bool = false, input : Stdio = Redirect::Pipe, output : Stdio = Redirect::Pipe, error : Stdio = Redirect::Pipe, chdir : String? = nil, &block)

  Executes a process, yields the block, and then waits for it to finish.

- .times : Tms

  Returns a `Tms` for the current process.

## Instance Method Summary

- #close

  Closes any pipes to the child process.

- #error

  A pipe to this process's error.

- #error? : IO::FileDescriptor?

  A pipe to this process's error.

- #exists?

  Whether the process is still registered in the system.

- #input

  A pipe to this process's input.

- #input? : IO::FileDescriptor?

  A pipe to this process's input.

- #kill(sig = Signal::TERM)

  See also: `Process.kill`

- #output

  A pipe to this process's output.

- #output? : IO::FileDescriptor?

  A pipe to this process's output.

- #pid : Int32
- #terminated?

  Whether this process is already terminated.

- #wait : Process::Status

  Waits for this process to complete and closes any pipes.

### Instance methods inherited from class `Reference`

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference)
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

### Constructor methods inherited from class `Reference`

new new

### Instance methods inherited from class `Object`

!=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, class class, dup dup, hash(hasher)
hash hash, inspect(io : IO) : Nil
inspect : String inspect, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&block) tap, to_json(io : IO)
to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json, to_s : String
to_s(io : IO) : Nil to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&block) try, unsafe_as(type : T.class) forall T unsafe_as

### Constructor methods inherited from class `Object`

from_json(string_or_io, root : String) : self
from_json(string_or_io) : self from_json, from_yaml(string_or_io : String | IO) : self from_yaml

## Constructor Detail

def self.fork : Process? #

Duplicates the current process. Returns a `Process` representing the new child process in the current process and `nil` inside the new child process.

def self.fork(&block) : Process #

Runs the given block inside a new process and returns a `Process` representing the new child process.

def self.new(command : String, args = nil, env : Env = nil, clear_env : Bool = false, shell : Bool = false, input : Stdio = Redirect::Close, output : Stdio = Redirect::Close, error : Stdio = Redirect::Close, chdir : String? = nil) #

Creates a process, executes it, but doesn't wait for it to complete.

To wait for it to finish, invoke `#wait`.

By default the process is configured without input, output or error.

## Class Method Detail

def self.after_fork_child_callbacks #

Hooks are defined here due to load order problems.

def self.chroot(path : String) : Nil #

Changes the root directory and the current working directory for the current process.

Security: `.chroot` on its own is not an effective means of mitigation. At minimum the process needs to also drop privileges as soon as feasible after the `.chroot`. Changes to the directory hierarchy or file descriptors passed via `recvmsg(2)` from outside the `.chroot` jail may allow a restricted process to escape, even if it is unprivileged.

    Process.chroot("/var/empty")

def self.exec(command : String, args = nil, env : Env = nil, clear_env : Bool = false, shell : Bool = false, input : ExecStdio = Redirect::Inherit, output : ExecStdio = Redirect::Inherit, error : ExecStdio = Redirect::Inherit, chdir : String? = nil) #

Replaces the current process with a new one. This function never returns.

def self.executable_path #

Returns an absolute path to the executable file of the currently running program. This is in opposition to `PROGRAM_NAME` which may be a relative or absolute path, just the executable file name or a symlink.

The executable path will be canonicalized (all symlinks and relative paths will be expanded).

Returns `nil` if the file can't be found.

def self.exists?(pid : Int) #

Returns `true` if the process identified by pid is valid for a currently registered process, `false` otherwise. Note that this returns `true` for a process in the zombie or similar state.

def self.exit(status = 0) #

Terminate the current process immediately. All open files, pipes and sockets are flushed and closed, all child processes are inherited by PID 1. This does not run any handlers registered with `at_exit`, use `::exit` for that.

status is the exit status of the current process.

def self.find_executable(name, path = ENV["PATH"]?, pwd = Dir.current) #

Searches an executable, checking for an absolute path, a path relative to pwd or absolute path, then eventually searching in directories declared in path.

def self.kill(signal : Signal, *pids : Int) #

Sends a signal to the processes identified by the given pids.

def self.pgid : LibC::PidT #

Returns the process group identifier of the current process.

def self.pgid(pid : Int32) : LibC::PidT #

Returns the process group identifier of the process identified by pid.

def self.pid : LibC::PidT #

Returns the process identifier of the current process.

def self.ppid : LibC::PidT #

Returns the process identifier of the parent process of the current process.

def self.run(command : String, args = nil, env : Env = nil, clear_env : Bool = false, shell : Bool = false, input : Stdio = Redirect::Close, output : Stdio = Redirect::Close, error : Stdio = Redirect::Close, chdir : String? = nil) : Process::Status #

Executes a process and waits for it to complete.

By default the process is configured without input, output or error.

def self.run(command : String, args = nil, env : Env = nil, clear_env : Bool = false, shell : Bool = false, input : Stdio = Redirect::Pipe, output : Stdio = Redirect::Pipe, error : Stdio = Redirect::Pipe, chdir : String? = nil, &block) #

Executes a process, yields the block, and then waits for it to finish.

By default the process is configured to use pipes for input, output and error. These will be closed automatically at the end of the block.

Returns the block's value.

def self.times : Tms #

Returns a `Tms` for the current process. For the children times, only those of terminated children are returned.

## Instance Method Detail

def close #

Closes any pipes to the child process.

def error #

A pipe to this process's error. Raises if a pipe wasn't asked when creating the process.

def error? : IO::FileDescriptor? #

A pipe to this process's error. Raises if a pipe wasn't asked when creating the process.

def exists? #

Whether the process is still registered in the system. Note that this returns `true` for processes in the zombie or similar state.

def input #

A pipe to this process's input. Raises if a pipe wasn't asked when creating the process.

def input? : IO::FileDescriptor? #

A pipe to this process's input. Raises if a pipe wasn't asked when creating the process.

def kill(sig = Signal::TERM) #

See also: `Process.kill`

def output #

A pipe to this process's output. Raises if a pipe wasn't asked when creating the process.

def output? : IO::FileDescriptor? #

A pipe to this process's output. Raises if a pipe wasn't asked when creating the process.

def pid : Int32 #
def terminated? #

Whether this process is already terminated.

def wait : Process::Status #

Waits for this process to complete and closes any pipes.