Wed Jan 8 2020 09:49:47

Asterisk developer's documentation


func_shell.c
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2006-2012, Digium, Inc.
5  *
6  * See http://www.asterisk.org for more information about
7  * the Asterisk project. Please do not directly contact
8  * any of the maintainers of this project for assistance;
9  * the project provides a web site, mailing lists and IRC
10  * channels for your use.
11  *
12  * This program is free software, distributed under the terms of
13  * the GNU General Public License Version 2. See the LICENSE file
14  * at the top of the source tree.
15  */
16 
17 /*! \file
18  *
19  * SHELL function to return the output generated by a command issued to the system shell.
20  *
21  * \note Inspiration and Guidance from Russell! Thank You!
22  *
23  * \author Brandon Kruse <bkruse@digium.com>
24  *
25  * \ingroup functions
26  */
27 
28 /*** MODULEINFO
29  <support_level>core</support_level>
30  ***/
31 
32 #include "asterisk.h"
33 
34 ASTERISK_FILE_VERSION(__FILE__, "$Revision: 403913 $")
35 
36 #include "asterisk/module.h"
37 #include "asterisk/channel.h"
38 #include "asterisk/pbx.h"
39 #include "asterisk/utils.h"
40 #include "asterisk/app.h"
41 
42 static int shell_helper(struct ast_channel *chan, const char *cmd, char *data,
43  char *buf, size_t len)
44 {
45  int res = 0;
46 
47  if (ast_strlen_zero(data)) {
48  ast_log(LOG_WARNING, "Missing Argument! Example: Set(foo=${SHELL(echo \"bar\")})\n");
49  return -1;
50  }
51 
52  if (chan) {
54  }
55 
56  if (len >= 1) {
57  FILE *ptr;
58  char plbuff[4096];
59 
60  ptr = popen(data, "r");
61  if (ptr) {
62  while (fgets(plbuff, sizeof(plbuff), ptr)) {
63  strncat(buf, plbuff, len - strlen(buf) - 1);
64  }
65  pclose(ptr);
66  } else {
67  ast_log(LOG_WARNING, "Failed to execute shell command '%s'\n", data);
68  res = -1;
69  }
70  }
71 
72  if (chan) {
74  }
75 
76  return res;
77 }
78 
79 /*** DOCUMENTATION
80  <function name="SHELL" language="en_US">
81  <synopsis>
82  Executes a command using the system shell and captures its output.
83  </synopsis>
84  <syntax>
85  <parameter name="command" required="true">
86  <para>The command that the shell should execute.</para>
87  </parameter>
88  </syntax>
89  <description>
90  <para>Collects the output generated by a command executed by the system shell</para>
91  <para>Example: <literal>Set(foo=${SHELL(echo bar)})</literal></para>
92  <note>
93  <para>The command supplied to this function will be executed by the
94  system's shell, typically specified in the SHELL environment variable. There
95  are many different system shells available with somewhat different behaviors,
96  so the output generated by this function may vary between platforms.</para>
97 
98  <para>If <literal>live_dangerously</literal> in <literal>asterisk.conf</literal>
99  is set to <literal>no</literal>, this function can only be executed from the
100  dialplan, and not directly from external protocols.</para>
101  </note>
102  </description>
103 
104  </function>
105  ***/
107  .name = "SHELL",
108  .read = shell_helper,
109 };
110 
111 static int unload_module(void)
112 {
113  return ast_custom_function_unregister(&shell_function);
114 }
115 
116 static int load_module(void)
117 {
118  return ast_custom_function_register_escalating(&shell_function, AST_CFE_READ);
119 }
120 
121 AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Collects the output generated by a command executed by the system shell");
static int unload_module(void)
Definition: func_shell.c:111
Main Channel structure associated with a channel.
Definition: channel.h:742
#define AST_MODULE_INFO_STANDARD(keystr, desc)
Definition: module.h:396
Asterisk main include file. File version handling, generic pbx functions.
int ast_autoservice_start(struct ast_channel *chan)
Automatically service a channel for us...
Definition: autoservice.c:179
static struct ast_custom_function shell_function
Definition: func_shell.c:106
#define LOG_WARNING
Definition: logger.h:144
int ast_custom_function_unregister(struct ast_custom_function *acf)
Unregister a custom function.
Definition: pbx.c:3814
Utility functions.
#define ast_custom_function_register_escalating(acf, escalation)
Register a custom function which requires escalated privileges.
Definition: pbx.h:1173
General Asterisk PBX channel definitions.
static int load_module(void)
Definition: func_shell.c:116
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:63
Data structure associated with a custom dialplan function.
Definition: pbx.h:95
Core PBX routines and definitions.
int ast_autoservice_stop(struct ast_channel *chan)
Stop servicing a channel for us...
Definition: autoservice.c:238
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
Application convenience functions, designed to give consistent look and feel to Asterisk apps...
const char * name
Definition: pbx.h:96
static int shell_helper(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t len)
Definition: func_shell.c:42
#define ASTERISK_GPL_KEY
The text the key() function should return.
Definition: module.h:38
#define ASTERISK_FILE_VERSION(file, version)
Register/unregister a source code file with the core.
Definition: asterisk.h:180