W3cubDocs

/Crystal

class Process

Defined in:

kernel.cr
process.cr:1
process.cr:14
process/executable_path.cr:5
process/executable_path.cr:62
process/shell.cr

Constant Summary

PATH_DELIMITER = {% if flag?(:windows) %} ';' {% else %} ':' {% end %}

Constructors

.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

.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) : NoReturn
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) : Bool
Returns true if the process identified by pid is valid for a currently registered process, false otherwise.
.exit(status = 0) : NoReturn
Terminate the current process immediately.
.find_executable(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.
.kill(signal : Signal, *pids : Int)

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

DEPRECATED Use #signal instead
.pgid(pid : Int) : Int64
Returns the process group identifier of the process identified by pid.
.pgid : Int64
Returns the process group identifier of the current process.
.pid : Int64
Returns the process identifier of the current process.
.ppid : Int64
Returns the process identifier of the parent process of the current process.
.quote(arg : String) : String
Shell-quotes one item, same as .quote({arg}).
.quote(args : Enumerable(String)) : String
Converts a sequence of strings to one joined string with each argument shell-quoted.
.quote_posix(args : Enumerable(String)) : String
Converts a sequence of strings to one joined string with each argument shell-quoted.
.quote_posix(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
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, &)
Executes a process, yields the block, and then waits for it to finish.
.signal(signal : Signal, pid : Int) : Nil
Sends signal to the process identified by pid.
.times : Tms
Returns a Tms for the current process.

Instance Method Summary

#close
Closes any system resources (e.g.
#error : IO::FileDescriptor
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.
#finalize
#input : IO::FileDescriptor
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

DEPRECATED Use #signal instead
#output : IO::FileDescriptor
A pipe to this process's output.
#output? : IO::FileDescriptor?
A pipe to this process's output.
#pid : Int64
Returns the process identifier of this process.
#signal(signal : Signal)
Sends signal to this process.
#terminate
Asks this process to terminate gracefully
#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`

, , , , , , ,

Constructor methods inherited from class `Reference`

Instance methods inherited from class `Object`

, , , , , , , , , , , , , , , , , , , , , , , , , ,

Class methods inherited from class `Object`

Constructor Detail

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)Source

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.

Class Method Detail

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

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")

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) : NoReturnSource

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

Available only on Unix-like operating systems.

def self.executable_pathSource

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) : Bool Source

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) : NoReturnSource

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 | String, path : String? = ENV["PATH"]?, pwd : Path | String = Dir.current) : String?Source

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)Source

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

DEPRECATED Use #signal instead

def self.pgid(pid : Int) : Int64 Source

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

def self.pgid : Int64 Source

Returns the process group identifier of the current process.

def self.pid : Int64 Source

Returns the process identifier of the current process.

def self.ppid : Int64 Source

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

def self.quote(arg : String) : String Source

Shell-quotes one item, same as .quote({arg}).

def self.quote(args : Enumerable(String)) : String Source

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)}`

def self.quote_posix(args : Enumerable(String)) : String Source

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"

def self.quote_posix(arg : String) : String Source

Shell-quotes one item, same as .quote_posix({arg}).

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 Source

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, &)Source

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.signal(signal : Signal, pid : Int) : Nil Source

Sends signal to the process identified by pid.

def self.times : Tms Source

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.

Instance Method Detail

def closeSource

Closes any system resources (e.g. pipes) held for the child process.

def error : IO::FileDescriptor Source

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

def error? : IO::FileDescriptor?Source

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

def exists?Source

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

def finalizeSource

def input : IO::FileDescriptor Source

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

def input? : IO::FileDescriptor?Source

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

def kill(sig = Signal::TERM)Source

def output : IO::FileDescriptor Source

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

def output? : IO::FileDescriptor?Source

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

def pid : Int64 Source

Returns the process identifier of this process.

def signal(signal : Signal)Source

Sends signal to this process.

def terminateSource

Asks this process to terminate gracefully

def terminated?Source

Whether this process is already terminated.

def wait : Process::Status Source

Waits for this process to complete and closes any pipes.

© 2012–2020 Manas Technology Solutions.
Licensed under the Apache License, Version 2.0.
https://crystal-lang.org/api/0.35.1/Process.html

class Process

Defined in:

Constant Summary

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class Reference

Constructor methods inherited from class Reference

Instance methods inherited from class Object

Class methods inherited from class Object