open3 0.1.2 → 0.2.1

data/lib/open3.rb

@@ -31,57 +31,189 @@
 
 require 'open3/version'
 
+# \Module \Open3 supports creating child processes
+# with access to their $stdin, $stdout, and $stderr streams.
+#
+# == What's Here
+#
+# Each of these methods executes a given command in a new process or subshell,
+# or multiple commands in new processes and/or subshells:
+#
+# - Each of these methods executes a single command in a process or subshell,
+#   accepts a string for input to $stdin,
+#   and returns string output from $stdout, $stderr, or both:
+#
+#   - Open3.capture2: Executes the command;
+#     returns the string from $stdout.
+#   - Open3.capture2e: Executes the command;
+#     returns the string from merged $stdout and $stderr.
+#   - Open3.capture3: Executes the command;
+#     returns strings from $stdout and $stderr.
+#
+# - Each of these methods executes a single command in a process or subshell,
+#   and returns pipes for $stdin, $stdout, and/or $stderr:
+#
+#   - Open3.popen2: Executes the command;
+#     returns pipes for $stdin and $stdout.
+#   - Open3.popen2e: Executes the command;
+#     returns pipes for $stdin and merged $stdout and $stderr.
+#   - Open3.popen3: Executes the command;
+#     returns pipes for $stdin, $stdout, and $stderr.
+#
+# - Each of these methods executes one or more commands in processes and/or subshells,
+#   returns pipes for the first $stdin, the last $stdout, or both:
+#
+#   - Open3.pipeline_r: Returns a pipe for the last $stdout.
+#   - Open3.pipeline_rw: Returns pipes for the first $stdin and the last $stdout.
+#   - Open3.pipeline_w: Returns a pipe for the first $stdin.
+#   - Open3.pipeline_start: Does not wait for processes to complete.
+#   - Open3.pipeline: Waits for processes to complete.
+#
+# Each of the methods above accepts:
+#
+# - An optional hash of environment variable names and values;
+#   see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+# - A required string argument that is a +command_line+ or +exe_path+;
+#   see {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
+# - An optional hash of execution options;
+#   see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+#
 module Open3
 
-  # 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.
+  # :call-seq:
+  #   Open3.popen3([env, ] command_line, options = {}) -> [stdin, stdout, stderr, wait_thread]
+  #   Open3.popen3([env, ] exe_path, *args, options = {}) -> [stdin, stdout, stderr, wait_thread]
+  #   Open3.popen3([env, ] command_line, options = {}) {|stdin, stdout, stderr, wait_thread| ... } -> object
+  #   Open3.popen3([env, ] exe_path, *args, options = {}) {|stdin, stdout, stderr, wait_thread| ... } -> object
+  #
+  # Basically a wrapper for
+  # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
+  # that:
+  #
+  # - Creates a child process, by calling Process.spawn with the given arguments.
+  # - Creates streams +stdin+, +stdout+, and +stderr+,
+  #   which are the standard input, standard output, and standard error streams
+  #   in the child process.
+  # - Creates thread +wait_thread+ that waits for the child process to exit;
+  #   the thread has method +pid+, which returns the process ID
+  #   of the child process.
+  #
+  # With no block given, returns the array
+  # <tt>[stdin, stdout, stderr, wait_thread]</tt>.
+  # The caller should close each of the three returned streams.
+  #
+  #   stdin, stdout, stderr, wait_thread = Open3.popen3('echo')
+  #   # => [#<IO:fd 8>, #<IO:fd 10>, #<IO:fd 12>, #<Process::Waiter:0x00007f58d5428f58 run>]
+  #   stdin.close
+  #   stdout.close
+  #   stderr.close
+  #   wait_thread.pid   # => 2210481
+  #   wait_thread.value # => #<Process::Status: pid 2210481 exit 0>
+  #
+  # With a block given, calls the block with the four variables
+  # (three streams and the wait thread)
+  # and returns the block's return value.
+  # The caller need not close the streams:
+  #
+  #   Open3.popen3('echo') do |stdin, stdout, stderr, wait_thread|
+  #     p stdin
+  #     p stdout
+  #     p stderr
+  #     p wait_thread
+  #     p wait_thread.pid
+  #     p wait_thread.value
+  #   end
   #
-  # Block form:
+  # Output:
   #
-  #   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.
-  #   }
+  #   #<IO:fd 6>
+  #   #<IO:fd 7>
+  #   #<IO:fd 9>
+  #   #<Process::Waiter:0x00007f58d53606e8 sleep>
+  #   2211047
+  #   #<Process::Status: pid 2211047 exit 0>
   #
-  # Non-block form:
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
-  #   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.
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
+  #
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in the call to Process.spawn;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+  #
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in the call to Process.spawn;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+  #
+  # The single required argument is one of the following:
+  #
+  # - +command_line+ if it is a string,
+  #   and if it begins with a shell reserved word or special built-in,
+  #   or if it contains one or more metacharacters.
+  # - +exe_path+ otherwise.
+  #
+  # <b>Argument +command_line+</b>
   #
-  # 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:
+  # \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:
   #
-  #   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| ... }
+  #   Open3.popen3('if true; then echo "Foo"; fi') {|*args| p args } # Shell reserved word.
+  #   Open3.popen3('echo') {|*args| p args }                         # Built-in.
+  #   Open3.popen3('date > date.tmp') {|*args| p args }              # Contains meta character.
   #
-  # If the last parameter, opts, is a Hash, it is recognized as an option for Process.spawn.
+  # Output (similar for each call above):
   #
-  #   Open3.popen3("pwd", :chdir=>"/") {|i,o,e,t|
-  #     p o.read.chomp #=> "/"
-  #   }
+  #   [#<IO:(closed)>, #<IO:(closed)>, #<IO:(closed)>, #<Process::Waiter:0x00007f58d52f28c8 dead>]
   #
-  # wait_thr.value waits for the termination of the process.
-  # The block form also waits for the process when it returns.
+  # The command line may also contain arguments and options for the command:
+  #
+  #   Open3.popen3('echo "Foo"') { |i, o, e, t| o.gets }
+  #   "Foo\n"
+  #
+  # <b>Argument +exe_path+</b>
+  #
+  # Argument +exe_path+ is one of the following:
+  #
+  # - The string path to an executable to be called.
+  # - A 2-element array containing the path to an executable
+  #   and the string to be used as the name of the executing process.
+  #
+  # Example:
   #
-  # Closing stdin, stdout and stderr does not wait for the process to complete.
+  #   Open3.popen3('/usr/bin/date') { |i, o, e, t| o.gets }
+  #   # => "Wed Sep 27 02:56:44 PM CDT 2023\n"
   #
-  # 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.
+  # Ruby invokes the executable directly, with no shell and no shell expansion:
+  #
+  #   Open3.popen3('doesnt_exist') { |i, o, e, t| o.gets } # Raises Errno::ENOENT
+  #
+  # If one or more +args+ is given, each is an argument or option
+  # to be passed to the executable:
+  #
+  #   Open3.popen3('echo', 'C #') { |i, o, e, t| o.gets }
+  #   # => "C #\n"
+  #   Open3.popen3('echo', 'hello', 'world') { |i, o, e, t| o.gets }
+  #   # => "hello world\n"
+  #
+  # Take care to avoid deadlocks.
+  # Output streams +stdout+ and +stderr+ have fixed-size buffers,
+  # so reading extensively from one but not the other can cause a deadlock
+  # when the unread buffer fills.
+  # To avoid that, +stdout+ and +stderr+ should be read simultaneously
+  # (using threads or IO.select).
+  #
+  # Related:
+  #
+  # - Open3.popen2: Makes the standard input and standard output streams
+  #   of the child process available as separate streams,
+  #   with no access to the standard error stream.
+  # - Open3.popen2e: Makes the standard input and the merge
+  #   of the standard output and standard error streams
+  #   of the child process available as separate streams.
   #
   def popen3(*cmd, &block)
     if Hash === cmd.last
@@ -104,45 +236,131 @@ module Open3
   end
   module_function :popen3
 
-  # Open3.popen2 is similar to Open3.popen3 except that it doesn't create a pipe for
-  # the standard error stream.
+  # :call-seq:
+  #   Open3.popen2([env, ] command_line, options = {}) -> [stdin, stdout, wait_thread]
+  #   Open3.popen2([env, ] exe_path, *args, options = {}) -> [stdin, stdout, wait_thread]
+  #   Open3.popen2([env, ] command_line, options = {}) {|stdin, stdout, wait_thread| ... } -> object
+  #   Open3.popen2([env, ] exe_path, *args, options = {}) {|stdin, stdout, wait_thread| ... } -> object
+  #
+  # Basically a wrapper for
+  # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
+  # that:
+  #
+  # - Creates a child process, by calling Process.spawn with the given arguments.
+  # - Creates streams +stdin+ and +stdout+,
+  #   which are the standard input and standard output streams
+  #   in the child process.
+  # - Creates thread +wait_thread+ that waits for the child process to exit;
+  #   the thread has method +pid+, which returns the process ID
+  #   of the child process.
+  #
+  # With no block given, returns the array
+  # <tt>[stdin, stdout, wait_thread]</tt>.
+  # The caller should close each of the two returned streams.
+  #
+  #   stdin, stdout, wait_thread = Open3.popen2('echo')
+  #   # => [#<IO:fd 6>, #<IO:fd 7>, #<Process::Waiter:0x00007f58d52dbe98 run>]
+  #   stdin.close
+  #   stdout.close
+  #   wait_thread.pid   # => 2263572
+  #   wait_thread.value # => #<Process::Status: pid 2263572 exit 0>
+  #
+  # With a block given, calls the block with the three variables
+  # (two streams and the wait thread)
+  # and returns the block's return value.
+  # The caller need not close the streams:
+  #
+  #   Open3.popen2('echo') do |stdin, stdout, wait_thread|
+  #     p stdin
+  #     p stdout
+  #     p wait_thread
+  #     p wait_thread.pid
+  #     p wait_thread.value
+  #   end
   #
-  # Block form:
+  # Output:
   #
-  #   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.
-  #   }
+  #   #<IO:fd 6>
+  #   #<IO:fd 7>
+  #   #<Process::Waiter:0x00007f58d59a34b0 sleep>
+  #   2263636
+  #   #<Process::Status: pid 2263636 exit 0>
   #
-  # Non-block form:
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
-  #   stdin, stdout, wait_thr = Open3.popen2([env,] cmd... [, opts])
-  #   ...
-  #   stdin.close  # stdin and stdout should be closed explicitly in this form.
-  #   stdout.close
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
+  #
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in the call to Process.spawn;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+  #
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in the call to Process.spawn;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+  #
+  # The single required argument is one of the following:
+  #
+  # - +command_line+ if it is a string,
+  #   and if it begins with a shell reserved word or special built-in,
+  #   or if it contains one or more metacharacters.
+  # - +exe_path+ otherwise.
   #
-  # See Process.spawn for the optional hash arguments _env_ and _opts_.
+  # <b>Argument +command_line+</b>
+  #
+  # \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:
+  #
+  #   Open3.popen2('if true; then echo "Foo"; fi') {|*args| p args } # Shell reserved word.
+  #   Open3.popen2('echo') {|*args| p args }                         # Built-in.
+  #   Open3.popen2('date > date.tmp') {|*args| p args }              # Contains meta character.
+  #
+  # Output (similar for each call above):
+  #
+  #   # => [#<IO:(closed)>, #<IO:(closed)>, #<Process::Waiter:0x00007f7577dfe410 dead>]
+  #
+  # The command line may also contain arguments and options for the command:
+  #
+  #   Open3.popen2('echo "Foo"') { |i, o, t| o.gets }
+  #   "Foo\n"
+  #
+  # <b>Argument +exe_path+</b>
+  #
+  # Argument +exe_path+ is one of the following:
+  #
+  # - The string path to an executable to be called.
+  # - A 2-element array containing the path to an executable
+  #   and the string to be used as the name of the executing process.
   #
   # 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('/usr/bin/date') { |i, o, t| o.gets }
+  #   # => "Thu Sep 28 09:41:06 AM CDT 2023\n"
+  #
+  # Ruby invokes the executable directly, with no shell and no shell expansion:
+  #
+  #   Open3.popen2('doesnt_exist') { |i, o, t| o.gets } # Raises Errno::ENOENT
+  #
+  # If one or more +args+ is given, each is an argument or option
+  # to be passed to the executable:
+  #
+  #   Open3.popen2('echo', 'C #') { |i, o, t| o.gets }
+  #   # => "C #\n"
+  #   Open3.popen2('echo', 'hello', 'world') { |i, o, t| o.gets }
+  #   # => "hello world\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 #=> "*"
-  #   }
+  # Related:
+  #
+  # - Open3.popen2e: Makes the standard input and the merge
+  #   of the standard output and standard error streams
+  #   of the child process available as separate streams.
+  # - Open3.popen3: Makes the standard input, standard output,
+  #   and standard error streams
+  #   of the child process available as separate streams.
   #
   def popen2(*cmd, &block)
     if Hash === cmd.last
@@ -162,36 +380,130 @@ module Open3
   end
   module_function :popen2
 
-  # Open3.popen2e is similar to Open3.popen3 except that it merges
-  # the standard output stream and the standard error stream.
+  # :call-seq:
+  #   Open3.popen2e([env, ] command_line, options = {}) -> [stdin, stdout_and_stderr, wait_thread]
+  #   Open3.popen2e([env, ] exe_path, *args, options = {}) -> [stdin, stdout_and_stderr, wait_thread]
+  #   Open3.popen2e([env, ] command_line, options = {}) {|stdin, stdout_and_stderr, wait_thread| ... } -> object
+  #   Open3.popen2e([env, ] exe_path, *args, options = {}) {|stdin, stdout_and_stderr, wait_thread| ... } -> object
+  #
+  # Basically a wrapper for
+  # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
+  # that:
+  #
+  # - Creates a child process, by calling Process.spawn with the given arguments.
+  # - Creates streams +stdin+, +stdout_and_stderr+,
+  #   which are the standard input and the merge of the standard output
+  #   and standard error streams in the child process.
+  # - Creates thread +wait_thread+ that waits for the child process to exit;
+  #   the thread has method +pid+, which returns the process ID
+  #   of the child process.
+  #
+  # With no block given, returns the array
+  # <tt>[stdin, stdout_and_stderr, wait_thread]</tt>.
+  # The caller should close each of the two returned streams.
+  #
+  #   stdin, stdout_and_stderr, wait_thread = Open3.popen2e('echo')
+  #   # => [#<IO:fd 6>, #<IO:fd 7>, #<Process::Waiter:0x00007f7577da4398 run>]
+  #   stdin.close
+  #   stdout_and_stderr.close
+  #   wait_thread.pid   # => 2274600
+  #   wait_thread.value # => #<Process::Status: pid 2274600 exit 0>
+  #
+  # With a block given, calls the block with the three variables
+  # (two streams and the wait thread)
+  # and returns the block's return value.
+  # The caller need not close the streams:
+  #
+  #   Open3.popen2e('echo') do |stdin, stdout_and_stderr, wait_thread|
+  #     p stdin
+  #     p stdout_and_stderr
+  #     p wait_thread
+  #     p wait_thread.pid
+  #     p wait_thread.value
+  #   end
   #
-  # Block form:
+  # Output:
   #
-  #   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.
-  #   }
+  #   #<IO:fd 6>
+  #   #<IO:fd 7>
+  #   #<Process::Waiter:0x00007f75777578c8 sleep>
+  #   2274763
+  #   #<Process::Status: pid 2274763 exit 0>
   #
-  # Non-block form:
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
-  #   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
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
+  #
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in the call to Process.spawn;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+  #
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in the call to Process.spawn;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+  #
+  # The single required argument is one of the following:
+  #
+  # - +command_line+ if it is a string,
+  #   and if it begins with a shell reserved word or special built-in,
+  #   or if it contains one or more metacharacters.
+  # - +exe_path+ otherwise.
+  #
+  # <b>Argument +command_line+</b>
+  #
+  # \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:
+  #
+  #   Open3.popen2e('if true; then echo "Foo"; fi') {|*args| p args } # Shell reserved word.
+  #   Open3.popen2e('echo') {|*args| p args }                         # Built-in.
+  #   Open3.popen2e('date > date.tmp') {|*args| p args }              # Contains meta character.
+  #
+  # Output (similar for each call above):
+  #
+  #   # => [#<IO:(closed)>, #<IO:(closed)>, #<Process::Waiter:0x00007f7577d8a1f0 dead>]
   #
-  # See Process.spawn for the optional hash arguments _env_ and _opts_.
+  # The command line may also contain arguments and options for the command:
+  #
+  #   Open3.popen2e('echo "Foo"') { |i, o_and_e, t| o_and_e.gets }
+  #   "Foo\n"
+  #
+  # <b>Argument +exe_path+</b>
+  #
+  # Argument +exe_path+ is one of the following:
+  #
+  # - The string path to an executable to be called.
+  # - A 2-element array containing the path to an executable
+  #   and the string to be used as the name of the executing process.
   #
   # Example:
-  #   # check gcc warnings
-  #   source = "foo.c"
-  #   Open3.popen2e("gcc", "-Wall", source) {|i,oe,t|
-  #     oe.each {|line|
-  #       if /warning/ =~ line
-  #         ...
-  #       end
-  #     }
-  #   }
+  #
+  #   Open3.popen2e('/usr/bin/date') { |i, o_and_e, t| o_and_e.gets }
+  #   # => "Thu Sep 28 01:58:45 PM CDT 2023\n"
+  #
+  # Ruby invokes the executable directly, with no shell and no shell expansion:
+  #
+  #   Open3.popen2e('doesnt_exist') { |i, o_and_e, t| o_and_e.gets } # Raises Errno::ENOENT
+  #
+  # If one or more +args+ is given, each is an argument or option
+  # to be passed to the executable:
+  #
+  #   Open3.popen2e('echo', 'C #') { |i, o_and_e, t| o_and_e.gets }
+  #   # => "C #\n"
+  #   Open3.popen2e('echo', 'hello', 'world') { |i, o_and_e, t| o_and_e.gets }
+  #   # => "hello world\n"
+  #
+  # Related:
+  #
+  # - Open3.popen2: Makes the standard input and standard output streams
+  #   of the child process available as separate streams,
+  #   with no access to the standard error stream.
+  # - Open3.popen3: Makes the standard input, standard output,
+  #   and standard error streams
+  #   of the child process available as separate streams.
   #
   def popen2e(*cmd, &block)
     if Hash === cmd.last
@@ -238,44 +550,100 @@ module Open3
     private :popen_run
   end
 
-  # Open3.capture3 captures the standard output and the standard error of a command.
+  # :call-seq:
+  #   Open3.capture3([env, ] command_line, options = {}) -> [stdout_s, stderr_s, status]
+  #   Open3.capture3([env, ] exe_path, *args, options = {}) -> [stdout_s, stderr_s, status]
   #
-  #   stdout_str, stderr_str, status = Open3.capture3([env,] cmd... [, opts])
+  # Basically a wrapper for Open3.popen3 that:
   #
-  # The arguments env, cmd and opts are passed to Open3.popen3 except
-  # <code>opts[:stdin_data]</code> and <code>opts[:binmode]</code>.  See Process.spawn.
+  # - Creates a child process, by calling Open3.popen3 with the given arguments
+  #   (except for certain entries in hash +options+; see below).
+  # - Returns as strings +stdout_s+ and +stderr_s+ the standard output
+  #   and standard error of the child process.
+  # - Returns as +status+ a <tt>Process::Status</tt> object
+  #   that represents the exit status of the child process.
   #
-  # If <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
+  # Returns the array <tt>[stdout_s, stderr_s, status]</tt>:
   #
-  # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
+  #   stdout_s, stderr_s, status = Open3.capture3('echo "Foo"')
+  #   # => ["Foo\n", "", #<Process::Status: pid 2281954 exit 0>]
   #
-  # Examples:
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
-  #   # dot is a command of graphviz.
-  #   graph = <<'End'
-  #     digraph g {
-  #       a -> b
-  #     }
-  #   End
-  #   drawn_graph, dot_log = Open3.capture3("dot -v", :stdin_data=>graph)
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
   #
-  #   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>
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in the call to Open3.popen3;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
   #
-  #   # 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
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in the call to Open3.popen3;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+  #
+  # The hash +options+ is given;
+  # two options have local effect in method Open3.capture3:
+  #
+  # - If entry <tt>options[:stdin_data]</tt> exists, the entry is removed
+  #   and its string value is sent to the command's standard input:
+  #
+  #     Open3.capture3('tee', stdin_data: 'Foo')
+  #     # => ["Foo", "", #<Process::Status: pid 2319575 exit 0>]
+  #
+  # - If entry <tt>options[:binmode]</tt> exists, the entry is removed and
+  #   the internal streams are set to binary mode.
+  #
+  # The single required argument is one of the following:
+  #
+  # - +command_line+ if it is a string,
+  #   and if it begins with a shell reserved word or special built-in,
+  #   or if it contains one or more metacharacters.
+  # - +exe_path+ otherwise.
+  #
+  # <b>Argument +command_line+</b>
+  #
+  # \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:
+  #
+  #   Open3.capture3('if true; then echo "Foo"; fi') # Shell reserved word.
+  #   # => ["Foo\n", "", #<Process::Status: pid 2282025 exit 0>]
+  #   Open3.capture3('echo')                         # Built-in.
+  #   # => ["\n", "", #<Process::Status: pid 2282092 exit 0>]
+  #   Open3.capture3('date > date.tmp')              # Contains meta character.
+  #   # => ["", "", #<Process::Status: pid 2282110 exit 0>]
+  #
+  # The command line may also contain arguments and options for the command:
+  #
+  #   Open3.capture3('echo "Foo"')
+  #   # => ["Foo\n", "", #<Process::Status: pid 2282092 exit 0>]
+  #
+  # <b>Argument +exe_path+</b>
+  #
+  # Argument +exe_path+ is one of the following:
+  #
+  # - The string path to an executable to be called.
+  # - A 2-element array containing the path to an executable
+  #   and the string to be used as the name of the executing process.
+  #
+  # Example:
+  #
+  #   Open3.capture3('/usr/bin/date')
+  #   # => ["Thu Sep 28 05:03:51 PM CDT 2023\n", "", #<Process::Status: pid 2282300 exit 0>]
+  #
+  # Ruby invokes the executable directly, with no shell and no shell expansion:
+  #
+  #   Open3.capture3('doesnt_exist') # Raises Errno::ENOENT
+  #
+  # If one or more +args+ is given, each is an argument or option
+  # to be passed to the executable:
+  #
+  #   Open3.capture3('echo', 'C #')
+  #   # => ["C #\n", "", #<Process::Status: pid 2282368 exit 0>]
+  #   Open3.capture3('echo', 'hello', 'world')
+  #   # => ["hello world\n", "", #<Process::Status: pid 2282372 exit 0>]
   #
   def capture3(*cmd)
     if Hash === cmd.last
@@ -309,34 +677,100 @@ module Open3
   end
   module_function :capture3
 
-  # Open3.capture2 captures the standard output of a command.
+  # :call-seq:
+  #   Open3.capture2([env, ] command_line, options = {}) -> [stdout_s, status]
+  #   Open3.capture2([env, ] exe_path, *args, options = {}) -> [stdout_s, status]
+  #
+  # Basically a wrapper for Open3.popen3 that:
+  #
+  # - Creates a child process, by calling Open3.popen3 with the given arguments
+  #   (except for certain entries in hash +options+; see below).
+  # - Returns as string +stdout_s+ the standard output of the child process.
+  # - Returns as +status+ a <tt>Process::Status</tt> object
+  #   that represents the exit status of the child process.
+  #
+  # Returns the array <tt>[stdout_s, status]</tt>:
+  #
+  #   stdout_s, status = Open3.capture2('echo "Foo"')
+  #   # => ["Foo\n", #<Process::Status: pid 2326047 exit 0>]
+  #
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
+  #
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
   #
-  #   stdout_str, status = Open3.capture2([env,] cmd... [, opts])
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in the call to Open3.popen3;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
   #
-  # The arguments env, cmd and opts are passed to Open3.popen3 except
-  # <code>opts[:stdin_data]</code> and <code>opts[:binmode]</code>.  See Process.spawn.
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in the call to Open3.popen3;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
   #
-  # If <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
+  # The hash +options+ is given;
+  # two options have local effect in method Open3.capture2:
   #
-  # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
+  # - If entry <tt>options[:stdin_data]</tt> exists, the entry is removed
+  #   and its string value is sent to the command's standard input:
+  #
+  #     Open3.capture2('tee', stdin_data: 'Foo')
+  #
+  #     # => ["Foo", #<Process::Status: pid 2326087 exit 0>]
+  #
+  # - If entry <tt>options[:binmode]</tt> exists, the entry is removed and
+  #   the internal streams are set to binary mode.
+  #
+  # The single required argument is one of the following:
+  #
+  # - +command_line+ if it is a string,
+  #   and if it begins with a shell reserved word or special built-in,
+  #   or if it contains one or more metacharacters.
+  # - +exe_path+ otherwise.
+  #
+  # <b>Argument +command_line+</b>
+  #
+  # \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:
+  #
+  #   Open3.capture2('if true; then echo "Foo"; fi') # Shell reserved word.
+  #   # => ["Foo\n", #<Process::Status: pid 2326131 exit 0>]
+  #   Open3.capture2('echo')                         # Built-in.
+  #   # => ["\n", #<Process::Status: pid 2326139 exit 0>]
+  #   Open3.capture2('date > date.tmp')              # Contains meta character.
+  #   # => ["", #<Process::Status: pid 2326174 exit 0>]
+  #
+  # The command line may also contain arguments and options for the command:
+  #
+  #   Open3.capture2('echo "Foo"')
+  #   # => ["Foo\n", #<Process::Status: pid 2326183 exit 0>]
+  #
+  # <b>Argument +exe_path+</b>
+  #
+  # Argument +exe_path+ is one of the following:
+  #
+  # - The string path to an executable to be called.
+  # - A 2-element array containing the path to an executable
+  #   and the string to be used as the name of the executing process.
   #
   # 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('/usr/bin/date')
+  #   # => ["Fri Sep 29 01:00:39 PM CDT 2023\n", #<Process::Status: pid 2326222 exit 0>]
+  #
+  # Ruby invokes the executable directly, with no shell and no shell expansion:
+  #
+  #   Open3.capture2('doesnt_exist') # Raises Errno::ENOENT
+  #
+  # If one or more +args+ is given, each is an argument or option
+  # to be passed to the executable:
+  #
+  #   Open3.capture2('echo', 'C #')
+  #   # => ["C #\n", #<Process::Status: pid 2326267 exit 0>]
+  #   Open3.capture2('echo', 'hello', 'world')
+  #   # => ["hello world\n", #<Process::Status: pid 2326299 exit 0>]
   #
   def capture2(*cmd)
     if Hash === cmd.last
@@ -370,21 +804,100 @@ module Open3
   end
   module_function :capture2
 
-  # Open3.capture2e captures the standard output and the standard error of a command.
+  # :call-seq:
+  #   Open3.capture2e([env, ] command_line, options = {}) -> [stdout_and_stderr_s, status]
+  #   Open3.capture2e([env, ] exe_path, *args, options = {}) -> [stdout_and_stderr_s, status]
+  #
+  # Basically a wrapper for Open3.popen3 that:
+  #
+  # - Creates a child process, by calling Open3.popen3 with the given arguments
+  #   (except for certain entries in hash +options+; see below).
+  # - Returns as string +stdout_and_stderr_s+ the merged standard output
+  #   and standard error of the child process.
+  # - Returns as +status+ a <tt>Process::Status</tt> object
+  #   that represents the exit status of the child process.
+  #
+  # Returns the array <tt>[stdout_and_stderr_s, status]</tt>:
+  #
+  #   stdout_and_stderr_s, status = Open3.capture2e('echo "Foo"')
+  #   # => ["Foo\n", #<Process::Status: pid 2371692 exit 0>]
+  #
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
+  #
+  # Unlike Process.spawn, this method waits for the child process to exit
+  # before returning, so the caller need not do so.
+  #
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in the call to Open3.popen3;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+  #
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in the call to Open3.popen3;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+  #
+  # The hash +options+ is given;
+  # two options have local effect in method Open3.capture2e:
+  #
+  # - If entry <tt>options[:stdin_data]</tt> exists, the entry is removed
+  #   and its string value is sent to the command's standard input:
   #
-  #   stdout_and_stderr_str, status = Open3.capture2e([env,] cmd... [, opts])
+  #     Open3.capture2e('tee', stdin_data: 'Foo')
+  #     # => ["Foo", #<Process::Status: pid 2371732 exit 0>]
   #
-  # The arguments env, cmd and opts are passed to Open3.popen3 except
-  # <code>opts[:stdin_data]</code> and <code>opts[:binmode]</code>.  See Process.spawn.
+  # - If entry <tt>options[:binmode]</tt> exists, the entry is removed and
+  #   the internal streams are set to binary mode.
   #
-  # If <code>opts[:stdin_data]</code> is specified, it is sent to the command's standard input.
+  # The single required argument is one of the following:
   #
-  # If <code>opts[:binmode]</code> is true, internal pipes are set to binary mode.
+  # - +command_line+ if it is a string,
+  #   and if it begins with a shell reserved word or special built-in,
+  #   or if it contains one or more metacharacters.
+  # - +exe_path+ otherwise.
+  #
+  # <b>Argument +command_line+</b>
+  #
+  # \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:
+  #
+  #   Open3.capture2e('if true; then echo "Foo"; fi') # Shell reserved word.
+  #   # => ["Foo\n", #<Process::Status: pid 2371740 exit 0>]
+  #   Open3.capture2e('echo')                         # Built-in.
+  #   # => ["\n", #<Process::Status: pid 2371774 exit 0>]
+  #   Open3.capture2e('date > date.tmp')              # Contains meta character.
+  #   # => ["", #<Process::Status: pid 2371812 exit 0>]
+  #
+  # The command line may also contain arguments and options for the command:
+  #
+  #   Open3.capture2e('echo "Foo"')
+  #   # => ["Foo\n", #<Process::Status: pid 2326183 exit 0>]
+  #
+  # <b>Argument +exe_path+</b>
+  #
+  # Argument +exe_path+ is one of the following:
+  #
+  # - The string path to an executable to be called.
+  # - A 2-element array containing the path to an executable
+  #   and the string to be used as the name of the executing process.
   #
   # Example:
   #
-  #   # capture make log
-  #   make_log, s = Open3.capture2e("make")
+  #   Open3.capture2e('/usr/bin/date')
+  #   # => ["Sat Sep 30 09:01:46 AM CDT 2023\n", #<Process::Status: pid 2371820 exit 0>]
+  #
+  # Ruby invokes the executable directly, with no shell and no shell expansion:
+  #
+  #   Open3.capture2e('doesnt_exist') # Raises Errno::ENOENT
+  #
+  # If one or more +args+ is given, each is an argument or option
+  # to be passed to the executable:
+  #
+  #   Open3.capture2e('echo', 'C #')
+  #   # => ["C #\n", #<Process::Status: pid 2371856 exit 0>]
+  #   Open3.capture2e('echo', 'hello', 'world')
+  #   # => ["hello world\n", #<Process::Status: pid 2371894 exit 0>]
   #
   def capture2e(*cmd)
     if Hash === cmd.last
@@ -418,48 +931,86 @@ module Open3
   end
   module_function :capture2e
 
-  # Open3.pipeline_rw starts a list of commands as a pipeline with pipes
-  # which connect to stdin of the first command and stdout of the last command.
-  #
-  #   Open3.pipeline_rw(cmd1, cmd2, ... [, opts]) {|first_stdin, last_stdout, wait_threads|
-  #     ...
-  #   }
+  # :call-seq:
+  #   Open3.pipeline_rw([env, ] *cmds, options = {}) -> [first_stdin, last_stdout, wait_threads]
   #
-  #   first_stdin, last_stdout, wait_threads = Open3.pipeline_rw(cmd1, cmd2, ... [, opts])
-  #   ...
-  #   first_stdin.close
-  #   last_stdout.close
+  # Basically a wrapper for
+  # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
+  # that:
   #
-  # Each cmd is a string or an array.
-  # If it is an array, the elements are passed to Process.spawn.
+  # - Creates a child process for each of the given +cmds+
+  #   by calling Process.spawn.
+  # - Pipes the +stdout+ from each child to the +stdin+ of the next child,
+  #   or, for the first child, from the caller's +stdin+,
+  #   or, for the last child, to the caller's +stdout+.
   #
-  #   cmd:
-  #     commandline                              command line string which is passed to a shell
-  #     [env, commandline, opts]                 command line string which is passed to a shell
-  #     [env, cmdname, arg1, ..., opts]          command name and one or more arguments (no shell)
-  #     [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
+  # The method does not wait for child processes to exit,
+  # so the caller must do so.
   #
-  #   Note that env and opts are optional, as for Process.spawn.
+  # With no block given, returns a 3-element array containing:
   #
-  # The options to pass to Process.spawn are constructed by merging
-  # +opts+, the last hash element of the array, and
-  # specifications for the pipes between each of the commands.
+  # - The +stdin+ stream of the first child process.
+  # - The +stdout+ stream of the last child process.
+  # - An array of the wait threads for all of the child processes.
   #
   # Example:
   #
-  #   Open3.pipeline_rw("tr -dc A-Za-z", "wc -c") {|i, o, ts|
-  #     i.puts "All persons more than a mile high to leave the court."
-  #     i.close
-  #     p o.gets #=> "42\n"
-  #   }
-  #
-  #   Open3.pipeline_rw("sort", "cat -n") {|stdin, stdout, wait_thrs|
-  #     stdin.puts "foo"
-  #     stdin.puts "bar"
-  #     stdin.puts "baz"
-  #     stdin.close     # send EOF to sort.
-  #     p stdout.read   #=> "     1\tbar\n     2\tbaz\n     3\tfoo\n"
-  #   }
+  #   first_stdin, last_stdout, wait_threads = Open3.pipeline_rw('sort', 'cat -n')
+  #   # => [#<IO:fd 20>, #<IO:fd 21>, [#<Process::Waiter:0x000055e8de29ab40 sleep>, #<Process::Waiter:0x000055e8de29a690 sleep>]]
+  #   first_stdin.puts("foo\nbar\nbaz")
+  #   first_stdin.close # Send EOF to sort.
+  #   puts last_stdout.read
+  #   wait_threads.each do |wait_thread|
+  #     wait_thread.join
+  #   end
+  #
+  # Output:
+  #
+  #   1	bar
+  #   2	baz
+  #   3	foo
+  #
+  # With a block given, calls the block with the +stdin+ stream of the first child,
+  # the +stdout+ stream  of the last child,
+  # and an array of the wait processes:
+  #
+  #   Open3.pipeline_rw('sort', 'cat -n') do |first_stdin, last_stdout, wait_threads|
+  #     first_stdin.puts "foo\nbar\nbaz"
+  #     first_stdin.close # send EOF to sort.
+  #     puts last_stdout.read
+  #     wait_threads.each do |wait_thread|
+  #       wait_thread.join
+  #     end
+  #   end
+  #
+  # Output:
+  #
+  #   1	bar
+  #   2	baz
+  #   3	foo
+  #
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
+  #
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in each call to Process.spawn;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+  #
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in each call to Process.spawn;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+  #
+  # Each remaining argument in +cmds+ is one of:
+  #
+  # - A +command_line+: a string that begins with a shell reserved word
+  #   or special built-in, or contains one or more metacharacters.
+  # - An +exe_path+: the string path to an executable to be called.
+  # - An array containing a +command_line+ or an +exe_path+,
+  #   along with zero or more string arguments for the command.
+  #
+  # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
+  #
   def pipeline_rw(*cmds, &block)
     if Hash === cmds.last
       opts = cmds.pop.dup
@@ -478,43 +1029,77 @@ module Open3
   end
   module_function :pipeline_rw
 
-  # Open3.pipeline_r starts a list of commands as a pipeline with a pipe
-  # which connects to stdout of the last command.
+  # :call-seq:
+  #   Open3.pipeline_r([env, ] *cmds, options = {}) -> [last_stdout, wait_threads]
   #
-  #   Open3.pipeline_r(cmd1, cmd2, ... [, opts]) {|last_stdout, wait_threads|
-  #     ...
-  #   }
+  # Basically a wrapper for
+  # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
+  # that:
   #
-  #   last_stdout, wait_threads = Open3.pipeline_r(cmd1, cmd2, ... [, opts])
-  #   ...
-  #   last_stdout.close
+  # - Creates a child process for each of the given +cmds+
+  #   by calling Process.spawn.
+  # - Pipes the +stdout+ from each child to the +stdin+ of the next child,
+  #   or, for the last child, to the caller's +stdout+.
   #
-  # Each cmd is a string or an array.
-  # If it is an array, the elements are passed to Process.spawn.
+  # The method does not wait for child processes to exit,
+  # so the caller must do so.
   #
-  #   cmd:
-  #     commandline                              command line string which is passed to a shell
-  #     [env, commandline, opts]                 command line string which is passed to a shell
-  #     [env, cmdname, arg1, ..., opts]          command name and one or more arguments (no shell)
-  #     [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
+  # With no block given, returns a 2-element array containing:
   #
-  #   Note that env and opts are optional, as for Process.spawn.
+  # - The +stdout+ stream of the last child process.
+  # - An array of the wait threads for all of the child processes.
   #
   # Example:
   #
-  #   Open3.pipeline_r("zcat /var/log/apache2/access.log.*.gz",
-  #                    [{"LANG"=>"C"}, "grep", "GET /favicon.ico"],
-  #                    "logresolve") {|o, ts|
-  #     o.each_line {|line|
-  #       ...
-  #     }
-  #   }
+  #   last_stdout, wait_threads = Open3.pipeline_r('ls', 'grep R')
+  #   # => [#<IO:fd 5>, [#<Process::Waiter:0x000055e8de2f9898 dead>, #<Process::Waiter:0x000055e8de2f94b0 sleep>]]
+  #   puts last_stdout.read
+  #   wait_threads.each do |wait_thread|
+  #     wait_thread.join
+  #   end
+  #
+  # Output:
+  #
+  #   Rakefile
+  #   README.md
+  #
+  # With a block given, calls the block with the +stdout+ stream
+  # of the last child process,
+  # and an array of the wait processes:
+  #
+  #   Open3.pipeline_r('ls', 'grep R') do |last_stdout, wait_threads|
+  #     puts last_stdout.read
+  #     wait_threads.each do |wait_thread|
+  #       wait_thread.join
+  #     end
+  #   end
+  #
+  # Output:
+  #
+  #   Rakefile
+  #   README.md
+  #
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
+  #
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in each call to Process.spawn;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+  #
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in each call to Process.spawn;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
   #
-  #   Open3.pipeline_r("yes", "head -10") {|o, ts|
-  #     p o.read      #=> "y\ny\ny\ny\ny\ny\ny\ny\ny\ny\n"
-  #     p ts[0].value #=> #<Process::Status: pid 24910 SIGPIPE (signal 13)>
-  #     p ts[1].value #=> #<Process::Status: pid 24913 exit 0>
-  #   }
+  # Each remaining argument in +cmds+ is one of:
+  #
+  # - A +command_line+: a string that begins with a shell reserved word
+  #   or special built-in, or contains one or more metacharacters.
+  # - An +exe_path+: the string path to an executable to be called.
+  # - An array containing a +command_line+ or an +exe_path+,
+  #   along with zero or more string arguments for the command.
+  #
+  # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
   #
   def pipeline_r(*cmds, &block)
     if Hash === cmds.last
@@ -530,33 +1115,82 @@ module Open3
   end
   module_function :pipeline_r
 
-  # Open3.pipeline_w starts a list of commands as a pipeline with a pipe
-  # which connects to stdin of the first command.
+
+  # :call-seq:
+  #   Open3.pipeline_w([env, ] *cmds, options = {}) -> [first_stdin, wait_threads]
   #
-  #   Open3.pipeline_w(cmd1, cmd2, ... [, opts]) {|first_stdin, wait_threads|
-  #     ...
-  #   }
+  # Basically a wrapper for
+  # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
+  # that:
   #
-  #   first_stdin, wait_threads = Open3.pipeline_w(cmd1, cmd2, ... [, opts])
-  #   ...
-  #   first_stdin.close
+  # - Creates a child process for each of the given +cmds+
+  #   by calling Process.spawn.
+  # - Pipes the +stdout+ from each child to the +stdin+ of the next child,
+  #   or, for the first child, pipes the caller's +stdout+ to the child's +stdin+.
   #
-  # Each cmd is a string or an array.
-  # If it is an array, the elements are passed to Process.spawn.
+  # The method does not wait for child processes to exit,
+  # so the caller must do so.
   #
-  #   cmd:
-  #     commandline                              command line string which is passed to a shell
-  #     [env, commandline, opts]                 command line string which is passed to a shell
-  #     [env, cmdname, arg1, ..., opts]          command name and one or more arguments (no shell)
-  #     [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
+  # With no block given, returns a 2-element array containing:
   #
-  #   Note that env and opts are optional, as for Process.spawn.
+  # - The +stdin+ stream of the first child process.
+  # - An array of the wait threads for all of the child processes.
   #
   # Example:
   #
-  #   Open3.pipeline_w("bzip2 -c", :out=>"/tmp/hello.bz2") {|i, ts|
-  #     i.puts "hello"
-  #   }
+  #   first_stdin, wait_threads = Open3.pipeline_w('sort', 'cat -n')
+  #   # => [#<IO:fd 7>, [#<Process::Waiter:0x000055e8de928278 run>, #<Process::Waiter:0x000055e8de923e80 run>]]
+  #   first_stdin.puts("foo\nbar\nbaz")
+  #   first_stdin.close # Send EOF to sort.
+  #   wait_threads.each do |wait_thread|
+  #     wait_thread.join
+  #   end
+  #
+  # Output:
+  #
+  #   1	bar
+  #   2	baz
+  #   3	foo
+  #
+  # With a block given, calls the block with the +stdin+ stream
+  # of the first child process,
+  # and an array of the wait processes:
+  #
+  #   Open3.pipeline_w('sort', 'cat -n') do |first_stdin, wait_threads|
+  #     first_stdin.puts("foo\nbar\nbaz")
+  #     first_stdin.close # Send EOF to sort.
+  #     wait_threads.each do |wait_thread|
+  #       wait_thread.join
+  #     end
+  #   end
+  #
+  # Output:
+  #
+  #   1	bar
+  #   2	baz
+  #   3	foo
+  #
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
+  #
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in each call to Process.spawn;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+  #
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in each call to Process.spawn;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+  #
+  # Each remaining argument in +cmds+ is one of:
+  #
+  # - A +command_line+: a string that begins with a shell reserved word
+  #   or special built-in, or contains one or more metacharacters.
+  # - An +exe_path+: the string path to an executable to be called.
+  # - An array containing a +command_line+ or an +exe_path+,
+  #   along with zero or more string arguments for the command.
+  #
+  # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
   #
   def pipeline_w(*cmds, &block)
     if Hash === cmds.last
@@ -573,49 +1207,67 @@ module Open3
   end
   module_function :pipeline_w
 
-  # Open3.pipeline_start starts a list of commands as a pipeline.
-  # No pipes are created for stdin of the first command and
-  # stdout of the last command.
+  # :call-seq:
+  #   Open3.pipeline_start([env, ] *cmds, options = {}) -> [wait_threads]
   #
-  #   Open3.pipeline_start(cmd1, cmd2, ... [, opts]) {|wait_threads|
-  #     ...
-  #   }
+  # Basically a wrapper for
+  # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
+  # that:
   #
-  #   wait_threads = Open3.pipeline_start(cmd1, cmd2, ... [, opts])
-  #   ...
+  # - Creates a child process for each of the given +cmds+
+  #   by calling Process.spawn.
+  # - Does not wait for child processes to exit.
   #
-  # Each cmd is a string or an array.
-  # If it is an array, the elements are passed to Process.spawn.
+  # With no block given, returns an array of the wait threads
+  # for all of the child processes.
   #
-  #   cmd:
-  #     commandline                              command line string which is passed to a shell
-  #     [env, commandline, opts]                 command line string which is passed to a shell
-  #     [env, cmdname, arg1, ..., opts]          command name and one or more arguments (no shell)
-  #     [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
+  # Example:
   #
-  #   Note that env and opts are optional, as for Process.spawn.
+  #   wait_threads = Open3.pipeline_start('ls', 'grep R')
+  #   # => [#<Process::Waiter:0x000055e8de9d2bb0 run>, #<Process::Waiter:0x000055e8de9d2890 run>]
+  #   wait_threads.each do |wait_thread|
+  #     wait_thread.join
+  #   end
   #
-  # Example:
+  # Output:
+  #
+  #   Rakefile
+  #   README.md
+  #
+  # With a block given, calls the block with an array of the wait processes:
+  #
+  #   Open3.pipeline_start('ls', 'grep R') do |wait_threads|
+  #     wait_threads.each do |wait_thread|
+  #       wait_thread.join
+  #     end
+  #   end
+  #
+  # Output:
+  #
+  #   Rakefile
+  #   README.md
   #
-  #   # Run xeyes in 10 seconds.
-  #   Open3.pipeline_start("xeyes") {|ts|
-  #     sleep 10
-  #     t = ts[0]
-  #     Process.kill("TERM", t.pid)
-  #     p t.value #=> #<Process::Status: pid 911 SIGTERM (signal 15)>
-  #   }
-  #
-  #   # Convert pdf to ps and send it to a printer.
-  #   # Collect error message of pdftops and lpr.
-  #   pdf_file = "paper.pdf"
-  #   printer = "printer-name"
-  #   err_r, err_w = IO.pipe
-  #   Open3.pipeline_start(["pdftops", pdf_file, "-"],
-  #                        ["lpr", "-P#{printer}"],
-  #                        :err=>err_w) {|ts|
-  #     err_w.close
-  #     p err_r.read # error messages of pdftops and lpr.
-  #   }
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
+  #
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in each call to Process.spawn;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+  #
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in each call to Process.spawn;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+  #
+  # Each remaining argument in +cmds+ is one of:
+  #
+  # - A +command_line+: a string that begins with a shell reserved word
+  #   or special built-in, or contains one or more metacharacters.
+  # - An +exe_path+: the string path to an executable to be called.
+  # - An array containing a +command_line+ or an +exe_path+,
+  #   along with zero or more string arguments for the command.
+  #
+  # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
   #
   def pipeline_start(*cmds, &block)
     if Hash === cmds.last
@@ -633,57 +1285,51 @@ module Open3
   end
   module_function :pipeline_start
 
-  # Open3.pipeline starts a list of commands as a pipeline.
-  # It waits for the completion of the commands.
-  # No pipes are created for stdin of the first command and
-  # stdout of the last command.
+  # :call-seq:
+  #   Open3.pipeline([env, ] *cmds, options = {}) -> array_of_statuses
   #
-  #   status_list = Open3.pipeline(cmd1, cmd2, ... [, opts])
+  # Basically a wrapper for
+  # {Process.spawn}[https://docs.ruby-lang.org/en/master/Process.html#method-c-spawn]
+  # that:
   #
-  # Each cmd is a string or an array.
-  # If it is an array, the elements are passed to Process.spawn.
+  # - Creates a child process for each of the given +cmds+
+  #   by calling Process.spawn.
+  # - Pipes the +stdout+ from each child to the +stdin+ of the next child,
+  #   or, for the last child, to the caller's +stdout+.
+  # - Waits for the child processes to exit.
+  # - Returns an array of Process::Status objects (one for each child).
   #
-  #   cmd:
-  #     commandline                              command line string which is passed to a shell
-  #     [env, commandline, opts]                 command line string which is passed to a shell
-  #     [env, cmdname, arg1, ..., opts]          command name and one or more arguments (no shell)
-  #     [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
+  # Example:
   #
-  #   Note that env and opts are optional, as Process.spawn.
+  #   wait_threads = Open3.pipeline('ls', 'grep R')
+  #   # => [#<Process::Status: pid 2139200 exit 0>, #<Process::Status: pid 2139202 exit 0>]
   #
-  # Example:
+  # Output:
+  #
+  #   Rakefile
+  #   README.md
+  #
+  # Like Process.spawn, this method has potential security vulnerabilities
+  # if called with untrusted input;
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
+  #
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in each call to Process.spawn;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+  #
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in each call to Process.spawn'
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+  #
+  # Each remaining argument in +cmds+ is one of:
+  #
+  # - A +command_line+: a string that begins with a shell reserved word
+  #   or special built-in, or contains one or more metacharacters.
+  # - An +exe_path+: the string path to an executable to be called.
+  # - An array containing a +command_line+ or an +exe_path+,
+  #   along with zero or more string arguments for the command.
   #
-  #   fname = "/usr/share/man/man1/ruby.1.gz"
-  #   p Open3.pipeline(["zcat", fname], "nroff -man", "less")
-  #   #=> [#<Process::Status: pid 11817 exit 0>,
-  #   #    #<Process::Status: pid 11820 exit 0>,
-  #   #    #<Process::Status: pid 11828 exit 0>]
-  #
-  #   fname = "/usr/share/man/man1/ls.1.gz"
-  #   Open3.pipeline(["zcat", fname], "nroff -man", "colcrt")
-  #
-  #   # convert PDF to PS and send to a printer by lpr
-  #   pdf_file = "paper.pdf"
-  #   printer = "printer-name"
-  #   Open3.pipeline(["pdftops", pdf_file, "-"],
-  #                  ["lpr", "-P#{printer}"])
-  #
-  #   # count lines
-  #   Open3.pipeline("sort", "uniq -c", :in=>"names.txt", :out=>"count")
-  #
-  #   # cyclic pipeline
-  #   r,w = IO.pipe
-  #   w.print "ibase=14\n10\n"
-  #   Open3.pipeline("bc", "tee /dev/tty", :in=>r, :out=>w)
-  #   #=> 14
-  #   #   18
-  #   #   22
-  #   #   30
-  #   #   42
-  #   #   58
-  #   #   78
-  #   #   106
-  #   #   202
+  # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
   #
   def pipeline(*cmds)
     if Hash === cmds.last