From eb3d94f4baff70d2e120c9472a3851a4aa9c90d9 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Thu, 31 Aug 2023 08:06:11 -0500 Subject: [PATCH] [DOC] RDoc for Kernel#system (#8309) --- process.c | 148 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 112 insertions(+), 36 deletions(-) diff --git a/process.c b/process.c index 377da3829a..0161ddb455 100644 --- a/process.c +++ b/process.c @@ -3068,7 +3068,7 @@ NORETURN(static VALUE f_exec(int c, const VALUE *a, VALUE _)); * * CONTRIBUTING.md COPYING COPYING.ja * - * Raises an exception if the new process fails to execute. + * Raises an exception if the new process could not execute. * * Argument +exe_path+ * @@ -3101,7 +3101,7 @@ NORETURN(static VALUE f_exec(int c, const VALUE *a, VALUE _)); * C* * hello world * - * Raises an exception if the new process fails to execute. + * Raises an exception if the new process could not execute. */ static VALUE @@ -4679,56 +4679,132 @@ rb_spawn(int argc, const VALUE *argv) /* * call-seq: - * system([env,] command... [,options], exception: false) -> true, false or nil + * system([env, ] command_line, options = {}, exception: false) -> true, false, or nil + * system([env, ] exe_path, *args, options = {}, exception: false) -> true, false, or nil * - * Executes _command..._ in a subshell. - * _command..._ is one of following forms. + * Creates a new child process by doing one of the following + * in that process: + * + * - Passing string +command_line+ to the shell. + * - Invoking the executable at +exe_path+. * * This method has potential security vulnerabilities if called with untrusted input; * see {Command Injection}[rdoc-ref:command_injection.rdoc]. * - * [commandline] - * command line string which is passed to the standard shell - * [cmdname, arg1, ...] - * command name and one or more arguments (no shell) - * [[cmdname, argv0], arg1, ...] - * command name, argv[0] and zero or more arguments (no shell) + * Returns: * - * system returns +true+ if the command gives zero exit status, - * +false+ for non zero exit status. - * Returns +nil+ if command execution fails. - * An error status is available in $?. + * - +true+ if the command exits with status zero. + * - +false+ if the exit status is a non-zero integer. + * - +nil+ if the command could not execute. * - * If the exception: true argument is passed, the method - * raises an exception instead of returning +false+ or +nil+. + * Raises an exception (instead of returning +false+ or +nil+) + * if keyword argument +exception+ is set to +true+. * - * The arguments are processed in the same way as - * for Kernel#spawn. + * Assigns the command's error status to $?. * - * The hash arguments, env and options, are same as #exec and #spawn. - * See Kernel#spawn for details. + * The new process is created using the + * {system system call}[https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/functions/system.html]; + * it may inherit some of its environment from the calling program + * (possibly including open file descriptors). * - * system("echo *") - * system("echo", "*") + * Argument +env+, if given, is a hash that affects +ENV+ for the new process; + * see {Execution Environment}[rdoc-ref:Process@Execution+Environment]. * - * produces: + * Argument +options+ is a hash of options for the new process; + * see {Execution Options}[rdoc-ref:Process@Execution+Options]. * - * config.h main.rb - * * + * The first required argument is one of the following: * - * Error handling: + * - +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. * - * system("cat nonexistent.txt") - * # => false - * system("catt nonexistent.txt") - * # => nil + * Argument +command_line+ * - * system("cat nonexistent.txt", exception: true) - * # RuntimeError (Command failed with exit 1: cat) - * system("catt nonexistent.txt", exception: true) - * # Errno::ENOENT (No such file or directory - catt) + * \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: * - * See Kernel#exec for the standard shell. + * system('echo') # => true # Built-in. + * system('if true; then echo "Foo"; fi') # => true # Shell reserved word. + * system('date > /tmp/date.tmp') # => true # Contains meta character. + * system('date > /nop/date.tmp') # => false + * system('date > /nop/date.tmp', exception: true) # Raises RuntimeError. + * + * Assigns the command's error status to $?: + * + * system('echo') # => true # Built-in. + * $? # => # + * system('date > /nop/date.tmp') # => false + * $? # => # + * + * The command line may also contain arguments and options for the command: + * + * system('echo "Foo"') # => true + * + * Output: + * + * Foo + * + * On a Unix-like system, the shell is /bin/sh; + * otherwise the shell is determined by environment variable + * ENV['RUBYSHELL'], if defined, or ENV['COMSPEC'] otherwise. + * + * Except for the +COMSPEC+ case, + * the entire string +command_line+ is passed as an argument + * to {shell option -c}[https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/utilities/sh.html]. + * + * The shell performs normal shell expansion on the command line: + * + * system('echo C*') # => true + * + * Output: + * + * CONTRIBUTING.md COPYING COPYING.ja + * + * Raises an exception if the new process could not execute. + * + * Argument +exe_path+ + * + * 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: + * + * system('/usr/bin/date') # => true # Path to date on Unix-style system. + * system('foo') # => nil # Command failed. + * + * Output: + * + * Mon Aug 28 11:43:10 AM CDT 2023 + * + * Assigns the command's error status to $?: + * + * system('/usr/bin/date') # => true + * $? # => # + * system('foo') # => nil + * $? # => # + * + * Ruby invokes the executable directly, with no shell and no shell expansion: + * + * system('doesnt_exist') # => nil + * + * If one or more +args+ is given, each is an argument or option + * to be passed to the executable: + * + * system('echo', 'C*') # => true + * system('echo', 'hello', 'world') # => true + * + * Output: + * + * C* + * hello world + * + * Raises an exception if the new process could not execute. */ static VALUE