multiline commands in qx//

On Mon, 21 Jul 1997 15:50:03 EDT, Ilya Zakharevich wrote:
>In article <199707202332.TAA05144@aatma.engin.umich.edu>,
>Gurusamy Sarathy  <gsar@engin.umich.edu> wrote:
>> +the system's command shell for parsing (this is C</bin/sh -c> on Unix
>> +platforms, but varies on other platforms).  If there are none, the
>> +argument is split into words and passed directly to execvp(), which is
>> +more efficient.  Note: exec() and system() do not flush your output
>> +buffer, so you may need to set C<$|> to avoid lost output.  Examples:
>
>"If there are none" should be changed to "if command contains no shell
>metacharacters".

Here's a newer version of that doc patch.  Ignore the old one.

p5p-msgid: 199707212350.TAA18496@aatma.engin.umich.edu

2 files changed, 35 insertions, 7 deletions

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index a28487ac1d..cc9fa00238 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1032,17 +1032,19 @@ in case 6.
 
 The exec() function executes a system command I<AND NEVER RETURNS>,
 unless the command does not exist and is executed directly instead of
-via C</bin/sh -c> (see below).  Use system() instead of exec() if you
-want it to return.
+via your system's command shell (see below).  Use system() instead of
+exec() if you want it to return.
 
 If there is more than one argument in LIST, or if LIST is an array with
 more than one value, calls execvp(3) with the arguments in LIST.  If
 there is only one scalar argument, the argument is checked for shell
-metacharacters.  If there are any, the entire argument is passed to
-C</bin/sh -c> for parsing.  If there are none, the argument is split
-into words and passed directly to execvp(), which is more efficient.
-Note: exec() and system() do not flush your output buffer, so you may
-need to set C<$|> to avoid lost output.  Examples:
+metacharacters, and if there are any, the entire argument is passed to
+the system's command shell for parsing (this is C</bin/sh -c> on Unix
+platforms, but varies on other platforms).  If there are no shell
+metacharacters in the argument, it is split into words and passed
+directly to execvp(), which is more efficient.  Note: exec() and
+system() do not flush your output buffer, so you may need to set C<$|>
+to avoid lost output.  Examples:
 
     exec '/bin/echo', 'Your arguments are: ', @ARGV;
     exec "sort $outfile | uniq";
@@ -1061,6 +1063,10 @@ or, more directly,
 
     exec {'/bin/csh'} '-sh';	# pretend it's a login shell
 
+When the arguments get executed via the system shell, results will
+be subject to its quirks and capabilities.  See L<perlop/"`STRING`">
+for details.
+
 =item exists EXPR
 
 Returns TRUE if the specified hash key exists in its hash array, even
@@ -3480,6 +3486,10 @@ signals and core dumps.
     }
     $ok = ($rc != 0);
 
+When the arguments get executed via the system shell, results will
+be subject to its quirks and capabilities.  See L<perlop/"`STRING`">
+for details.
+
 =item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
 
 =item syswrite FILEHANDLE,SCALAR,LENGTH
diff --git a/pod/perlop.pod b/pod/perlop.pod
index 32a0827cb3..2709a9eaa2 100644
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -808,6 +808,24 @@ with $/ or $INPUT_RECORD_SEPARATOR).
 
     $today = qx{ date };
 
+Note that how the string gets evaluated is entirely subject to the
+command interpreter on your system.  On most platforms, you will have
+to protect shell metacharacters if you want them treated literally.
+On some platforms (notably DOS-like ones), the shell may not be
+capable of dealing with multiline commands, so putting newlines in
+the string may not get you what you want.  You may be able to evaluate
+multiple commands in a single line by separating them with the command
+separator character, if your shell supports that (e.g. C<;> on many Unix
+shells; C<&> on the Windows NT C<cmd> shell).
+
+Beware that some command shells may place restrictions on the length
+of the command line.  You must ensure your strings don't exceed this
+limit after any necessary interpolations.  See the platform-specific
+release notes for more details about your particular environment.
+
+Also realize that using this operator frequently leads to unportable
+programs.
+
 See L<"I/O Operators"> for more discussion.
 
 =item qw/STRING/