From 1d80ad6a391610bb9225127d388ec96dd31c20ba Mon Sep 17 00:00:00 2001 From: zzak Date: Fri, 31 May 2013 08:58:06 +0000 Subject: [PATCH] * process.c: Improve Process::exec documentation git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@41003 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 4 +++ process.c | 86 +++++++++++++++++++++++++++++++++---------------------- 2 files changed, 55 insertions(+), 35 deletions(-) diff --git a/ChangeLog b/ChangeLog index 1585d5fbfb..fff4e3295f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +Fri May 31 17:57:21 2013 Zachary Scott + + * process.c: Improve Process::exec documentation + Fri May 31 17:26:42 2013 Nobuyoshi Nakada * vm_eval.c (rb_funcallv): add better names of rb_funcall2. diff --git a/process.c b/process.c index d90da1af77..b1270959ce 100644 --- a/process.c +++ b/process.c @@ -2330,55 +2330,71 @@ static int rb_exec_without_timer_thread(const struct rb_execarg *eargp, char *er * call-seq: * exec([env,] command... [,options]) * - * Replaces the current process by running the given external _command_. - * _command..._ is one of following forms. + * Replaces the current process by running the given external _command_, which + * can take one of the following forms: * - * 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) + * [exec(commandline)] + * command line string which is passed to the standard shell + * [exec(cmdname, arg1, ...)] + * command name and one or more arguments (no shell) + * [exec([cmdname, argv0], arg1, ...)] + * command name, argv[0] and zero or more arguments (no shell) * - * If single string is given as the command, - * it is taken as a command line that is subject to shell expansion before being executed. + * In the first form, the string is taken as a command line that is subject to + * shell expansion before being executed. + * + * The standard shell always means "/bin/sh" on Unix-like systems, + * same as ENV["RUBYSHELL"] + * (or ENV["COMSPEC"] on Windows NT series), and similar. + * + * If the string from the first form (exec("command")) follows + * these simple rules: + * + * * no meta characters + * * no shell reserved word and no special built-in + * * Ruby invokes the command directly without shell + * + * You can force shell invocation by adding ";" to the string (because ";" is + * a meta character). * - * The standard shell means always "/bin/sh" on Unix-like systems, - * ENV["RUBYSHELL"] or ENV["COMSPEC"] on Windows NT series, and - * similar. - * If _commandline_ is simple enough, - * no meta characters, no shell reserved word and no special built-in, - * Ruby invokes the command directly without shell. - * You can force shell invocation by adding ";" for _commandline_ (because ";" is a meta character). * Note that this behavior is observable by pid obtained - * (return value of spawn() and IO#pid for IO.popen) is the pid of the invoked command, not shell. + * (return value of spawn() and IO#pid for IO.popen) is the pid of the invoked + * command, not shell. * - * If two or more +string+ given, - * the first is taken as a command name and - * the rest are passed as parameters to command with no shell expansion. + * In the second form (exec("command1", "arg1", ...)), the first + * is taken as a command name and the rest are passed as parameters to command + * with no shell expansion. * - * If a two-element array at the beginning of the command, - * the first element is the command to be executed, - * and the second argument is used as the argv[0] value, - * which may show up in process listings. + * In the third form (exec(["command", "argv0"], "arg1", ...)), + * starting a two-element array at the beginning of the command, the first + * element is the command to be executed, and the second argument is used as + * the argv[0] value, which may show up in process listings. * - * In order to execute the command, one of the exec(2) - * system calls is used, so the running command may inherit some of the environment + * In order to execute the command, one of the exec(2) system + * calls are used, so the running command may inherit some of the environment * of the original program (including open file descriptors). - * This behavior is modified by env and options. - * See spawn for details. * - * Raises SystemCallError if the command couldn't execute (typically - * Errno::ENOENT when it was not found). + * This behavior is modified by the given +env+ and +options+ parameters. See + * ::spawn for details. * - * This method modifies process attributes according to _options_ - * (details described in spawn) - * before exec(2) system call. - * The modified attributes may be retained when exec(2) system call fails. - * For example, hard resource limits is not restorable. - * If it is not acceptable, consider to create a child process using spawn or system. + * If the command fails to execute (typically Errno::ENOENT when + * it was not found) a SystemCallError exception is raised. + * + * This method modifies process attributes according to given +options+ before + * exec(2) system call. See ::spawn for more details about the + * given +options+. + * + * The modified attributes may be retained when exec(2) system + * call fails. + * + * For example, hard resource limits are not restorable. + * + * Consider to create a child process using ::spawn or Kernel#system if this + * is not acceptable. * * exec "echo *" # echoes list of files in current directory * # never get here * - * * exec "echo", "*" # echoes an asterisk * # never get here */