From: Wolfgang Bumiller <w.bumiller@proxmox.com>
Date: Tue, 15 Sep 2015 08:01:32 +0000 (+0200)
Subject: document run_command
X-Git-Url: https://git.proxmox.com/?p=pve-common.git;a=commitdiff_plain;h=bd9c3a3654b284992e3a470252fc7354fa744671

document run_command
---

diff --git a/src/PVE/Tools.pm b/src/PVE/Tools.pm
index 577a8bc..4c35abc 100644
--- a/src/PVE/Tools.pm
+++ b/src/PVE/Tools.pm
@@ -241,6 +241,19 @@ sub safe_read_from {
     return $input;
 }
 
+# The $cmd parameter can be:
+#  -) a string
+#    This is generally executed by passing it to the shell with the -c option.
+#    However, it can be executed in one of two ways, depending on whether
+#    there's a pipe involved:
+#      *) with pipe: passed explicitly to bash -c, prefixed with:
+#          set -o pipefail &&
+#      *) without a pipe: passed to perl's open3 which uses 'sh -c'
+#      (Note that this may result in two different syntax requirements!)
+#      FIXME?
+#  -) an array of arguments (strings)
+#    Will be executed without interference from a shell. (Parameters are passed
+#    as is, no escape sequences of strings will be touched.)
 sub run_command {
     my ($cmd, %param) = @_;