[asterisk-commits] kpfleming: branch 10 r370384 - in /branches/10: ./ funcs/func_shell.c

[SVN commits to the Asterisk project]

Author: kpfleming
Date: Mon Jul 23 16:09:53 2012
New Revision: 370384

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=370384
Log:
Improve documentation for the SHELL() dialplan function.
........

Merged revisions 370383 from http://svn.asterisk.org/svn/asterisk/branches/1.8

Modified:
    branches/10/   (props changed)
    branches/10/funcs/func_shell.c

Propchange: branches/10/
------------------------------------------------------------------------------
Binary property 'branch-1.8-merged' - no diff available.

Modified: branches/10/funcs/func_shell.c
URL: http://svnview.digium.com/svn/asterisk/branches/10/funcs/func_shell.c?view=diff&rev=370384&r1=370383&r2=370384
==============================================================================
--- branches/10/funcs/func_shell.c (original)
+++ branches/10/funcs/func_shell.c Mon Jul 23 16:09:53 2012
@@ -1,7 +1,7 @@
 /*
  * Asterisk -- An open source telephony toolkit.
  *
- * Copyright (C) 2006, Digium, Inc.
+ * Copyright (C) 2006-2012, Digium, Inc.
  *
  * See http://www.asterisk.org for more information about
  * the Asterisk project. Please do not directly contact
@@ -16,9 +16,9 @@
 
 /*! \file
  *
- * SHELL function to return the value of a system call.
- * 
- * \note Inspiration and Guidance from Russell! Thank You! 
+ * SHELL function to return the output generated by a command issued to the system shell.
+ *
+ * \note Inspiration and Guidance from Russell! Thank You!
  *
  * \author Brandon Kruse <bkruse at digium.com>
  *
@@ -79,23 +79,22 @@
 /*** DOCUMENTATION
 	<function name="SHELL" language="en_US">
 		<synopsis>
-			Executes a command as if you were at a shell.
+			Executes a command using the system shell and captures its output.
 		</synopsis>
 		<syntax>
 			<parameter name="command" required="true">
-				<para>This is the argument to the function, the command you want to pass to the shell.</para>
+				<para>The command that the shell should execute.</para>
 			</parameter>
 		</syntax>
 		<description>
-			<para>Returns the value from a system command</para>
+			<para>Collects the output generated by a command executed by the system shell</para>
 			<para>Example:  <literal>Set(foo=${SHELL(echo \bar\)})</literal></para>
-			<note><para>When using the SHELL() dialplan function, your \SHELL\ is /bin/sh,
-			which may differ as to the underlying shell, depending upon your production
-			platform.  Also keep in mind that if you are using a common path, you should
-			be mindful of race conditions that could result from two calls running
-			SHELL() simultaneously.</para></note>
+			<note><para>The command supplied to this function will be executed by the
+			system's shell, typically specified in the SHELL environment variable. There
+			are many different system shells available with somewhat different behaviors,
+			so the output generated by this function may vary between platforms.</para></note>
 		</description>
- 
+
 	</function>
  ***/
 static struct ast_custom_function shell_function = {
@@ -113,5 +112,4 @@
 	return ast_custom_function_register(&shell_function);
 }
 
-AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Returns the output of a shell command");
-
+AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Collects the output generated by a command executed by the system shell");