class Process
inherits Reference
¶
Constants¶
PATH_DELIMITER = {% if flag?(:windows) %} ';' {% else %} ':' {% end %}
¶
{% if flag?(:windows) %} ';' {% else %} ':' {% end %}
Class methods¶
.chroot(path : String) : Nil
¶
(path : String) : Nil
Changes the root directory and the current working directory for the current process.
Available only on Unix-like operating systems.
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")
.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) : NoReturn
¶
(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) : NoReturn
Replaces the current process with a new one. This function never returns.
Available only on Unix-like operating systems.
Raises IO::Error if executing the command fails (for example if the executable doesn't exist).
.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.
.exists?(pid : Int) : Bool
¶
(pid : Int) : Bool
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.
.exit(status = 0) : NoReturn
¶
(status = 0) : NoReturn
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.
.find_executable(name : Path | String, path : String? = ENV["PATH"]?, pwd : Path | String = Dir.current) : String?
¶
(name : Path | String, path : String? = ENV["PATH"]?, pwd : Path | String = Dir.current) : String?
Searches an executable, checking for an absolute path, a path relative to pwd or absolute path, then eventually searching in directories declared in path.
.parse_arguments(line : String) : Array(String)
¶
(line : String) : Array(String)
Split a line string into the array of tokens in the same way the POSIX shell.
Process.parse_arguments(%q["foo bar" '\hello/' Fizz\ Buzz]) # => ["foo bar", "\\hello/", "Fizz Buzz"]
See https://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_03
.pgid(pid : Int) : Int64
¶
(pid : Int) : Int64
Returns the process group identifier of the process identified by pid.
.ppid : Int64
¶
: Int64
Returns the process identifier of the parent process of the current process.
.quote(args : Enumerable(String)) : String
¶
(args : Enumerable(String)) : String
Converts a sequence of strings to one joined string with each argument shell-quoted.
This is then safe to pass as part of the command when using shell: true or system().
Note
The actual return value is system-dependent, so it mustn't be relied on in other contexts.
See also: quote_posix.
files = ["my file.txt", "another.txt"]
`grep -E 'fo+' -- #{Process.quote(files)}`
.quote_posix(args : Enumerable(String)) : String
¶
(args : Enumerable(String)) : String
Converts a sequence of strings to one joined string with each argument shell-quoted.
This is then safe to pass to a POSIX shell.
files = ["my file.txt", "another.txt"]
Process.quote_posix(files) # => "'my file.txt' another.txt"
.quote_posix(arg : String) : String
¶
(arg : String) : String
Shell-quotes one item, same as quote_posix({arg}).
.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
¶
(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.
Raises IO::Error if executing the command fails (for example if the executable doesn't exist).
.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
¶
(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
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.
Raises IO::Error if executing the command fails (for example if the executable doesn't exist).
.signal(signal : Signal, pid : Int) : Nil
¶
(signal : Signal, pid : Int) : Nil
Sends signal to the process identified by pid.
.times : Tms
¶
: Tms
Returns a Tms for the current process. For the children times, only those
of terminated children are returned on Unix; they are zero on Windows.
.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)
¶
(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.
If shell is false, the command is the path to the executable to run, along with a list of args.
If shell is true, the command should be the full command line
including space-separated args.
* On POSIX this uses /bin/sh to process the command string. args are
also passed to the shell, and you need to include the string "${@}" in
the command to safely insert them there.
* On Windows this is implemented by passing the string as-is to the
process, and passing args is not supported.
Raises IO::Error if executing the command fails (for example if the executable doesn't exist).
Methods¶
#error : IO::FileDescriptor
¶
: IO::FileDescriptor
A pipe to this process' error. Raises if a pipe wasn't asked when creating the process.
#error? : IO::FileDescriptor?
¶
: IO::FileDescriptor?
A pipe to this process' error. Raises if a pipe wasn't asked when creating the process.
#exists?
¶
Whether the process is still registered in the system.
Note that this returns true for processes in the zombie or similar state.
#input : IO::FileDescriptor
¶
: IO::FileDescriptor
A pipe to this process' input. Raises if a pipe wasn't asked when creating the process.
#input? : IO::FileDescriptor?
¶
: IO::FileDescriptor?
A pipe to this process' input. Raises if a pipe wasn't asked when creating the process.
#output : IO::FileDescriptor
¶
: IO::FileDescriptor
A pipe to this process' output. Raises if a pipe wasn't asked when creating the process.
#output? : IO::FileDescriptor?
¶
: IO::FileDescriptor?
A pipe to this process' output. Raises if a pipe wasn't asked when creating the process.