Document shell-command-to-string security considerations

* lisp/simple.el (shell-command-to-string): Document security
considerations in docstring.

diff --git a/lisp/simple.el b/lisp/simple.el
index a128ff41051e31ecdb62d4104ba35b7df9732021..12d760a198f7d8a3d04ad66e4e5624a15e5f0d48 100644 (file)
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -5060,7 +5060,15 @@ characters."
     exit-status))
 
 (defun shell-command-to-string (command)
-  "Execute shell command COMMAND and return its output as a string."
+  "Execute shell command COMMAND and return its output as a string.
+Use `shell-quote-argument' to quote dangerous characters in
+COMMAND before passing it as an argument to this function.
+
+Use this function only when a shell interpreter is needed.  In
+other cases, consider alternatives such as `call-process' or
+`process-lines', which do not invoke the shell.  Prefer built-in
+functions like `mv' to the external command \"mv\".  For more
+information, see Info node ‘(elisp)Security Considerations’."
   (with-output-to-string
     (with-current-buffer standard-output
       (shell-command command t))))