Compute square root of a non negative number. This method is internally used by Math.sqrt.
Calculates the error function of x.
Domain: (-INFINITY, INFINITY)
Codomain: (-1, 1)
Math.erf(0) #=> 0.0
Calculates the complementary error function of x.
Domain: (-INFINITY, INFINITY)
Codomain: (0, 2)
Math.erfc(0) #=> 1.0
Open stdin, stdout, and stderr streams and start external executable. In addition, a thread to wait for the started process is created. The thread has a pid method and a thread variable :pid which is the pid of the started process.
Block form:
Open3.popen3([env,] cmd... [, opts]) {|stdin, stdout, stderr, wait_thr|
pid = wait_thr.pid # pid of the started process.
...
exit_status = wait_thr.value # Process::Status object returned.
}
Non-block form:
stdin, stdout, stderr, wait_thr = Open3.popen3([env,] cmd... [, opts]) pid = wait_thr[:pid] # pid of the started process ... stdin.close # stdin, stdout and stderr should be closed explicitly in this form. stdout.close stderr.close exit_status = wait_thr.value # Process::Status object returned.
The parameters env, cmd, and opts are passed to Process.spawn. A commandline string and a list of argument strings can be accepted as follows:
Open3.popen3("echo abc") {|i, o, e, t| ... }
Open3.popen3("echo", "abc") {|i, o, e, t| ... }
Open3.popen3(["echo", "argv0"], "abc") {|i, o, e, t| ... }
If the last parameter, opts, is a Hash, it is recognized as an option for Process.spawn.
Open3.popen3("pwd", :chdir=>"/") {|i,o,e,t| p o.read.chomp #=> "/" }
wait_thr.value waits for the termination of the process. The block form also waits for the process when it returns.
Closing stdin, stdout and stderr does not wait for the process to complete.
You should be careful to avoid deadlocks. Since pipes are fixed length buffers, Open3.popen3(“prog”) {|i, o, e, t| o.read } deadlocks if the program generates too much output on stderr. You should read stdout and stderr simultaneously (using threads or IO.select). However, if you don’t need stderr output, you can use Open3.popen2. If merged stdout and stderr output is not a problem, you can use Open3.popen2e. If you really need stdout and stderr output as separate strings, you can consider Open3.capture3.
Open stdin, stdout, and stderr streams and start external executable. In addition, a thread to wait for the started process is created. The thread has a pid method and a thread variable :pid which is the pid of the started process.
Block form:
Open3.popen3([env,] cmd... [, opts]) {|stdin, stdout, stderr, wait_thr|
pid = wait_thr.pid # pid of the started process.
...
exit_status = wait_thr.value # Process::Status object returned.
}
Non-block form:
stdin, stdout, stderr, wait_thr = Open3.popen3([env,] cmd... [, opts]) pid = wait_thr[:pid] # pid of the started process ... stdin.close # stdin, stdout and stderr should be closed explicitly in this form. stdout.close stderr.close exit_status = wait_thr.value # Process::Status object returned.
The parameters env, cmd, and opts are passed to Process.spawn. A commandline string and a list of argument strings can be accepted as follows:
Open3.popen3("echo abc") {|i, o, e, t| ... }
Open3.popen3("echo", "abc") {|i, o, e, t| ... }
Open3.popen3(["echo", "argv0"], "abc") {|i, o, e, t| ... }
If the last parameter, opts, is a Hash, it is recognized as an option for Process.spawn.
Open3.popen3("pwd", :chdir=>"/") {|i,o,e,t| p o.read.chomp #=> "/" }
wait_thr.value waits for the termination of the process. The block form also waits for the process when it returns.
Closing stdin, stdout and stderr does not wait for the process to complete.
You should be careful to avoid deadlocks. Since pipes are fixed length buffers, Open3.popen3(“prog”) {|i, o, e, t| o.read } deadlocks if the program generates too much output on stderr. You should read stdout and stderr simultaneously (using threads or IO.select). However, if you don’t need stderr output, you can use Open3.popen2. If merged stdout and stderr output is not a problem, you can use Open3.popen2e. If you really need stdout and stderr output as separate strings, you can consider Open3.capture3.
Open3.popen2 is similar to Open3.popen3 except that it doesn’t create a pipe for the standard error stream.
Block form:
Open3.popen2([env,] cmd... [, opts]) {|stdin, stdout, wait_thr|
pid = wait_thr.pid # pid of the started process.
...
exit_status = wait_thr.value # Process::Status object returned.
}
Non-block form:
stdin, stdout, wait_thr = Open3.popen2([env,] cmd... [, opts]) ... stdin.close # stdin and stdout should be closed explicitly in this form. stdout.close
See Process.spawn for the optional hash arguments env and opts.
Example:
Open3.popen2("wc -c") {|i,o,t| i.print "answer to life the universe and everything" i.close p o.gets #=> "42\n" } Open3.popen2("bc -q") {|i,o,t| i.puts "obase=13" i.puts "6 * 9" p o.gets #=> "42\n" } Open3.popen2("dc") {|i,o,t| i.print "42P" i.close p o.read #=> "*" }
Open3.popen2 is similar to Open3.popen3 except that it doesn’t create a pipe for the standard error stream.
Block form:
Open3.popen2([env,] cmd... [, opts]) {|stdin, stdout, wait_thr|
pid = wait_thr.pid # pid of the started process.
...
exit_status = wait_thr.value # Process::Status object returned.
}
Non-block form:
stdin, stdout, wait_thr = Open3.popen2([env,] cmd... [, opts]) ... stdin.close # stdin and stdout should be closed explicitly in this form. stdout.close
See Process.spawn for the optional hash arguments env and opts.
Example:
Open3.popen2("wc -c") {|i,o,t| i.print "answer to life the universe and everything" i.close p o.gets #=> "42\n" } Open3.popen2("bc -q") {|i,o,t| i.puts "obase=13" i.puts "6 * 9" p o.gets #=> "42\n" } Open3.popen2("dc") {|i,o,t| i.print "42P" i.close p o.read #=> "*" }
Open3.popen2e is similar to Open3.popen3 except that it merges the standard output stream and the standard error stream.
Block form:
Open3.popen2e([env,] cmd... [, opts]) {|stdin, stdout_and_stderr, wait_thr|
pid = wait_thr.pid # pid of the started process.
...
exit_status = wait_thr.value # Process::Status object returned.
}
Non-block form:
stdin, stdout_and_stderr, wait_thr = Open3.popen2e([env,] cmd... [, opts]) ... stdin.close # stdin and stdout_and_stderr should be closed explicitly in this form. stdout_and_stderr.close
See Process.spawn for the optional hash arguments env and opts.
Example:
# check gcc warnings
source = "foo.c"
Open3.popen2e("gcc", "-Wall", source) {|i,oe,t|
oe.each {|line|
if /warning/ =~ line
...
end
}
}
Open3.popen2e is similar to Open3.popen3 except that it merges the standard output stream and the standard error stream.
Block form:
Open3.popen2e([env,] cmd... [, opts]) {|stdin, stdout_and_stderr, wait_thr|
pid = wait_thr.pid # pid of the started process.
...
exit_status = wait_thr.value # Process::Status object returned.
}
Non-block form:
stdin, stdout_and_stderr, wait_thr = Open3.popen2e([env,] cmd... [, opts]) ... stdin.close # stdin and stdout_and_stderr should be closed explicitly in this form. stdout_and_stderr.close
See Process.spawn for the optional hash arguments env and opts.
Example:
# check gcc warnings
source = "foo.c"
Open3.popen2e("gcc", "-Wall", source) {|i,oe,t|
oe.each {|line|
if /warning/ =~ line
...
end
}
}
Open3.capture3 captures the standard output and the standard error of a command.
stdout_str, stderr_str, status = Open3.capture3([env,] cmd... [, opts])
The arguments env, cmd and opts are passed to Open3.popen3 except opts[:stdin_data] and opts[:binmode]. See Process.spawn.
If opts[:stdin_data] is specified, it is sent to the command’s standard input.
If opts[:binmode] is true, internal pipes are set to binary mode.
Examples:
# dot is a command of graphviz. graph = <<'End' digraph g { a -> b } End drawn_graph, dot_log = Open3.capture3("dot -v", :stdin_data=>graph) o, e, s = Open3.capture3("echo abc; sort >&2", :stdin_data=>"foo\nbar\nbaz\n") p o #=> "abc\n" p e #=> "bar\nbaz\nfoo\n" p s #=> #<Process::Status: pid 32682 exit 0> # generate a thumbnail image using the convert command of ImageMagick. # However, if the image is really stored in a file, # system("convert", "-thumbnail", "80", "png:#{filename}", "png:-") is better # because of reduced memory consumption. # But if the image is stored in a DB or generated by the gnuplot Open3.capture2 example, # Open3.capture3 should be considered. # image = File.read("/usr/share/openclipart/png/animals/mammals/sheep-md-v0.1.png", :binmode=>true) thumbnail, err, s = Open3.capture3("convert -thumbnail 80 png:- png:-", :stdin_data=>image, :binmode=>true) if s.success? STDOUT.binmode; print thumbnail end
Open3.capture3 captures the standard output and the standard error of a command.
stdout_str, stderr_str, status = Open3.capture3([env,] cmd... [, opts])
The arguments env, cmd and opts are passed to Open3.popen3 except opts[:stdin_data] and opts[:binmode]. See Process.spawn.
If opts[:stdin_data] is specified, it is sent to the command’s standard input.
If opts[:binmode] is true, internal pipes are set to binary mode.
Examples:
# dot is a command of graphviz. graph = <<'End' digraph g { a -> b } End drawn_graph, dot_log = Open3.capture3("dot -v", :stdin_data=>graph) o, e, s = Open3.capture3("echo abc; sort >&2", :stdin_data=>"foo\nbar\nbaz\n") p o #=> "abc\n" p e #=> "bar\nbaz\nfoo\n" p s #=> #<Process::Status: pid 32682 exit 0> # generate a thumbnail image using the convert command of ImageMagick. # However, if the image is really stored in a file, # system("convert", "-thumbnail", "80", "png:#{filename}", "png:-") is better # because of reduced memory consumption. # But if the image is stored in a DB or generated by the gnuplot Open3.capture2 example, # Open3.capture3 should be considered. # image = File.read("/usr/share/openclipart/png/animals/mammals/sheep-md-v0.1.png", :binmode=>true) thumbnail, err, s = Open3.capture3("convert -thumbnail 80 png:- png:-", :stdin_data=>image, :binmode=>true) if s.success? STDOUT.binmode; print thumbnail end
Open3.capture2 captures the standard output of a command.
stdout_str, status = Open3.capture2([env,] cmd... [, opts])
The arguments env, cmd and opts are passed to Open3.popen3 except opts[:stdin_data] and opts[:binmode]. See Process.spawn.
If opts[:stdin_data] is specified, it is sent to the command’s standard input.
If opts[:binmode] is true, internal pipes are set to binary mode.
Example:
# factor is a command for integer factorization. o, s = Open3.capture2("factor", :stdin_data=>"42") p o #=> "42: 2 3 7\n" # generate x**2 graph in png using gnuplot. gnuplot_commands = <<"End" set terminal png plot x**2, "-" with lines 1 14 2 1 3 8 4 5 e End image, s = Open3.capture2("gnuplot", :stdin_data=>gnuplot_commands, :binmode=>true)
Open3.capture2 captures the standard output of a command.
stdout_str, status = Open3.capture2([env,] cmd... [, opts])
The arguments env, cmd and opts are passed to Open3.popen3 except opts[:stdin_data] and opts[:binmode]. See Process.spawn.
If opts[:stdin_data] is specified, it is sent to the command’s standard input.
If opts[:binmode] is true, internal pipes are set to binary mode.
Example:
# factor is a command for integer factorization. o, s = Open3.capture2("factor", :stdin_data=>"42") p o #=> "42: 2 3 7\n" # generate x**2 graph in png using gnuplot. gnuplot_commands = <<"End" set terminal png plot x**2, "-" with lines 1 14 2 1 3 8 4 5 e End image, s = Open3.capture2("gnuplot", :stdin_data=>gnuplot_commands, :binmode=>true)
Open3.capture2e captures the standard output and the standard error of a command.
stdout_and_stderr_str, status = Open3.capture2e([env,] cmd... [, opts])
The arguments env, cmd and opts are passed to Open3.popen3 except opts[:stdin_data] and opts[:binmode]. See Process.spawn.
If opts[:stdin_data] is specified, it is sent to the command’s standard input.
If opts[:binmode] is true, internal pipes are set to binary mode.
Example:
# capture make log make_log, s = Open3.capture2e("make")
Open3.capture2e captures the standard output and the standard error of a command.
stdout_and_stderr_str, status = Open3.capture2e([env,] cmd... [, opts])
The arguments env, cmd and opts are passed to Open3.popen3 except opts[:stdin_data] and opts[:binmode]. See Process.spawn.
If opts[:stdin_data] is specified, it is sent to the command’s standard input.
If opts[:binmode] is true, internal pipes are set to binary mode.
Example:
# capture make log make_log, s = Open3.capture2e("make")
Retrieve the PathSupport object that RubyGems uses to lookup files.
Initialize the filesystem paths to use from env. env is a hash-like object (typically ENV) that is queried for ‘GEM_HOME’, ‘GEM_PATH’, and ‘GEM_SPEC_CACHE’ Keys for the env hash should be Strings, and values of the hash should be Strings or nil.
Prints the amount of time the supplied block takes to run using the debug UI output.
Raises a TypeError to prevent cloning.
Perform an operation in a block, raising an error if it takes longer than sec seconds to complete.
sec
Number of seconds to wait for the block to terminate. Any number may be used, including Floats to specify fractional seconds. A value of 0 or nil will execute the block without any timeout.
klass
Exception Class to raise if the block fails to terminate in sec seconds. Omitting will use the default, Timeout::Error
message
Error message to raise with Exception Class. Omitting will use the default, “execution expired”
Returns the result of the block if the block completed before sec seconds, otherwise throws an exception, based on the value of klass.
The exception thrown to terminate the given block cannot be rescued inside the block unless klass is given explicitly.
Note that this is both a method of module Timeout, so you can include Timeout into your classes so they have a timeout method, as well as a module method, so you can call it directly as Timeout.timeout().
Perform an operation in a block, raising an error if it takes longer than sec seconds to complete.
sec
Number of seconds to wait for the block to terminate. Any number may be used, including Floats to specify fractional seconds. A value of 0 or nil will execute the block without any timeout.
klass
Exception Class to raise if the block fails to terminate in sec seconds. Omitting will use the default, Timeout::Error
message
Error message to raise with Exception Class. Omitting will use the default, “execution expired”
Returns the result of the block if the block completed before sec seconds, otherwise throws an exception, based on the value of klass.
The exception thrown to terminate the given block cannot be rescued inside the block unless klass is given explicitly.
Note that this is both a method of module Timeout, so you can include Timeout into your classes so they have a timeout method, as well as a module method, so you can call it directly as Timeout.timeout().
spawn executes specified command and return its pid.
pid = spawn("tar xf ruby-2.0.0-p195.tar.bz2") Process.wait pid pid = spawn(RbConfig.ruby, "-eputs'Hello, world!'") Process.wait pid
This method is similar to Kernel#system but it doesn’t wait for the command to finish.
The parent process should use Process.wait to collect the termination status of its child or use Process.detach to register disinterest in their status; otherwise, the operating system may accumulate zombie processes.
spawn has bunch of options to specify process attributes:
env: hash
name => val : set the environment variable
name => nil : unset the environment variable
the keys and the values except for +nil+ must be strings.
command...:
commandline : command line string which is passed to the standard shell
cmdname, arg1, ... : command name and one or more arguments (This form does not use the shell. See below for caveats.)
[cmdname, argv0], arg1, ... : command name, argv[0] and zero or more arguments (no shell)
options: hash
clearing environment variables:
:unsetenv_others => true : clear environment variables except specified by env
:unsetenv_others => false : don't clear (default)
process group:
:pgroup => true or 0 : make a new process group
:pgroup => pgid : join the specified process group
:pgroup => nil : don't change the process group (default)
create new process group: Windows only
:new_pgroup => true : the new process is the root process of a new process group
:new_pgroup => false : don't create a new process group (default)
resource limit: resourcename is core, cpu, data, etc. See Process.setrlimit.
:rlimit_resourcename => limit
:rlimit_resourcename => [cur_limit, max_limit]
umask:
:umask => int
redirection:
key:
FD : single file descriptor in child process
[FD, FD, ...] : multiple file descriptor in child process
value:
FD : redirect to the file descriptor in parent process
string : redirect to file with open(string, "r" or "w")
[string] : redirect to file with open(string, File::RDONLY)
[string, open_mode] : redirect to file with open(string, open_mode, 0644)
[string, open_mode, perm] : redirect to file with open(string, open_mode, perm)
[:child, FD] : redirect to the redirected file descriptor
:close : close the file descriptor in child process
FD is one of follows
:in : the file descriptor 0 which is the standard input
:out : the file descriptor 1 which is the standard output
:err : the file descriptor 2 which is the standard error
integer : the file descriptor of specified the integer
io : the file descriptor specified as io.fileno
file descriptor inheritance: close non-redirected non-standard fds (3, 4, 5, ...) or not
:close_others => true : don't inherit
current directory:
:chdir => str
The 'cmdname, arg1, ...' form does not use the shell. However,
on different OSes, different things are provided as built-in
commands. An example of this is 'echo', which is a built-in
on Windows, but is a normal program on Linux and Mac OS X.
This means that `Process.spawn 'echo', '%Path%'` will display
the contents of the `%Path%` environment variable on Windows,
but `Process.spawn 'echo', '$PATH'` prints the literal '$PATH'.
If a hash is given as env, the environment is updated by env before exec(2) in the child process. If a pair in env has nil as the value, the variable is deleted.
# set FOO as BAR and unset BAZ. pid = spawn({"FOO"=>"BAR", "BAZ"=>nil}, command)
If a hash is given as options, it specifies process group, create new process group, resource limit, current directory, umask and redirects for the child process. Also, it can be specified to clear environment variables.
The :unsetenv_others key in options specifies to clear environment variables, other than specified by env.
pid = spawn(command, :unsetenv_others=>true) # no environment variable pid = spawn({"FOO"=>"BAR"}, command, :unsetenv_others=>true) # FOO only
The :pgroup key in options specifies a process group. The corresponding value should be true, zero, a positive integer, or nil. true and zero cause the process to be a process leader of a new process group. A non-zero positive integer causes the process to join the provided process group. The default value, nil, causes the process to remain in the same process group.
pid = spawn(command, :pgroup=>true) # process leader pid = spawn(command, :pgroup=>10) # belongs to the process group 10
The :new_pgroup key in options specifies to pass CREATE_NEW_PROCESS_GROUP flag to CreateProcessW() that is Windows API. This option is only for Windows. true means the new process is the root process of the new process group. The new process has CTRL+C disabled. This flag is necessary for Process.kill(:SIGINT, pid) on the subprocess. :new_pgroup is false by default.
pid = spawn(command, :new_pgroup=>true) # new process group pid = spawn(command, :new_pgroup=>false) # same process group
The :rlimit_foo key specifies a resource limit. foo should be one of resource types such as core. The corresponding value should be an integer or an array which have one or two integers: same as cur_limit and max_limit arguments for Process.setrlimit.
cur, max = Process.getrlimit(:CORE) pid = spawn(command, :rlimit_core=>[0,max]) # disable core temporary. pid = spawn(command, :rlimit_core=>max) # enable core dump pid = spawn(command, :rlimit_core=>0) # never dump core.
The :umask key in options specifies the umask.
pid = spawn(command, :umask=>077)
The :in, :out, :err, an integer, an IO and an array key specifies a redirection. The redirection maps a file descriptor in the child process.
For example, stderr can be merged into stdout as follows:
pid = spawn(command, :err=>:out) pid = spawn(command, 2=>1) pid = spawn(command, STDERR=>:out) pid = spawn(command, STDERR=>STDOUT)
The hash keys specifies a file descriptor in the child process started by spawn. :err, 2 and STDERR specifies the standard error stream (stderr).
The hash values specifies a file descriptor in the parent process which invokes spawn. :out, 1 and STDOUT specifies the standard output stream (stdout).
In the above example, the standard output in the child process is not specified. So it is inherited from the parent process.
The standard input stream (stdin) can be specified by :in, 0 and STDIN.
A filename can be specified as a hash value.
pid = spawn(command, :in=>"/dev/null") # read mode pid = spawn(command, :out=>"/dev/null") # write mode pid = spawn(command, :err=>"log") # write mode pid = spawn(command, [:out, :err]=>"/dev/null") # write mode pid = spawn(command, 3=>"/dev/null") # read mode
For stdout and stderr (and combination of them), it is opened in write mode. Otherwise read mode is used.
For specifying flags and permission of file creation explicitly, an array is used instead.
pid = spawn(command, :in=>["file"]) # read mode is assumed pid = spawn(command, :in=>["file", "r"]) pid = spawn(command, :out=>["log", "w"]) # 0644 assumed pid = spawn(command, :out=>["log", "w", 0600]) pid = spawn(command, :out=>["log", File::WRONLY|File::EXCL|File::CREAT, 0600])
The array specifies a filename, flags and permission. The flags can be a string or an integer. If the flags is omitted or nil, File::RDONLY is assumed. The permission should be an integer. If the permission is omitted or nil, 0644 is assumed.
If an array of IOs and integers are specified as a hash key, all the elements are redirected.
# stdout and stderr is redirected to log file. # The file "log" is opened just once. pid = spawn(command, [:out, :err]=>["log", "w"])
Another way to merge multiple file descriptors is [:child, fd]. [:child, fd] means the file descriptor in the child process. This is different from fd. For example, :err=>:out means redirecting child stderr to parent stdout. But :err=>[:child, :out] means redirecting child stderr to child stdout. They differ if stdout is redirected in the child process as follows.
# stdout and stderr is redirected to log file. # The file "log" is opened just once. pid = spawn(command, :out=>["log", "w"], :err=>[:child, :out])
[:child, :out] can be used to merge stderr into stdout in IO.popen. In this case, IO.popen redirects stdout to a pipe in the child process and [:child, :out] refers the redirected stdout.
io = IO.popen(["sh", "-c", "echo out; echo err >&2", :err=>[:child, :out]]) p io.read #=> "out\nerr\n"
The :chdir key in options specifies the current directory.
pid = spawn(command, :chdir=>"/var/tmp")
spawn closes all non-standard unspecified descriptors by default. The “standard” descriptors are 0, 1 and 2. This behavior is specified by :close_others option. :close_others doesn’t affect the standard descriptors which are closed only if :close is specified explicitly.
pid = spawn(command, :close_others=>true) # close 3,4,5,... (default) pid = spawn(command, :close_others=>false) # don't close 3,4,5,...
:close_others is true by default for spawn and IO.popen.
Note that fds which close-on-exec flag is already set are closed regardless of :close_others option.
So IO.pipe and spawn can be used as IO.popen.
# similar to r = IO.popen(command) r, w = IO.pipe pid = spawn(command, :out=>w) # r, w is closed in the child process. w.close
:close is specified as a hash value to close a fd individually.
f = open(foo) system(command, f=>:close) # don't inherit f.
If a file descriptor need to be inherited, io=>io can be used.
# valgrind has --log-fd option for log destination. # log_w=>log_w indicates log_w.fileno inherits to child process. log_r, log_w = IO.pipe pid = spawn("valgrind", "--log-fd=#{log_w.fileno}", "echo", "a", log_w=>log_w) log_w.close p log_r.read
It is also possible to exchange file descriptors.
pid = spawn(command, :out=>:err, :err=>:out)
The hash keys specify file descriptors in the child process. The hash values specifies file descriptors in the parent process. So the above specifies exchanging stdout and stderr. Internally, spawn uses an extra file descriptor to resolve such cyclic file descriptor mapping.
See Kernel.exec for the standard shell.
Equivalent to setpgid(0,0). Not available on all platforms.