reference/exec/functions/shell-exec.xml
7973fd533364af4dd6282ca9e7bee2dffec39b1c
...
...
@@ -1,7 +1,7 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
3
<!-- splitted from ./en/functions/exec.xml, last change in rev 1.2 -->
4
-
<refentry xml:id='function.shell-exec' xmlns="http://docbook.org/ns/docbook">
4
+
<refentry xml:id="function.shell-exec" xmlns="http://docbook.org/ns/docbook">
5
5
<refnamediv>
6
6
<refname>shell_exec</refname>
7
7
<refpurpose>Execute command via shell and return the complete output as a string</refpurpose>
...
...
@@ -10,13 +10,19 @@
10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
12
<methodsynopsis>
13
-
<type>string</type><methodname>shell_exec</methodname>
14
-
<methodparam><type>string</type><parameter>cmd</parameter></methodparam>
13
+
<type class="union"><type>string</type><type>false</type><type>null</type></type><methodname>shell_exec</methodname>
14
+
<methodparam><type>string</type><parameter>command</parameter></methodparam>
15
15
</methodsynopsis>
16
16
<para>
17
-
This function is identical to the <link
18
-
linkend="language.operators.execution">backtick operator</link>.
17
+
This function is identical to the <link linkend="language.operators.execution">backtick operator</link>.
19
18
</para>
19
+
<note>
20
+
<para>
21
+
On Windows, the underlying pipe is opened in text mode which can cause the
22
+
function to fail for binary output. Consider to use <function>popen</function>
23
+
instead for such cases.
24
+
</para>
25
+
</note>
20
26
</refsect1>
21
27

22
28
<refsect1 role="parameters">
...
...
@@ -24,7 +30,7 @@
24
30
<para>
25
31
<variablelist>
26
32
<varlistentry>
27
-
<term><parameter>cmd</parameter></term>
33
+
<term><parameter>command</parameter></term>
28
34
<listitem>
29
35
<para>
30
36
The command that will be executed.
...
...
@@ -38,7 +44,24 @@
38
44
<refsect1 role="returnvalues">
39
45
&reftitle.returnvalues;
40
46
<para>
41
-
The output from the executed command.
47
+
A &string; containing the output from the executed command, &false; if the pipe
48
+
cannot be established or &null; if an error occurs or the command produces no output.
49
+
</para>
50
+
<note>
51
+
<para>
52
+
This function can return &null; both when an error occurs or the program
53
+
produces no output. It is not possible to detect execution failures using
54
+
this function. <function>exec</function> should be used when access to the
55
+
program exit code is required.
56
+
</para>
57
+
</note>
58
+
</refsect1>
59
+

60
+
<refsect1 role="errors">
61
+
&reftitle.errors;
62
+
<para>
63
+
An <constant>E_WARNING</constant> level error is generated
64
+
when the pipe cannot be established.
42
65
</para>
43
66
</refsect1>
44
67

...
...
@@ -59,15 +82,6 @@ echo "<pre>$output</pre>";
59
82
</para>
60
83
</refsect1>
61
84

62
-
<refsect1 role="notes">
63
-
&reftitle.notes;
64
-
<note>
65
-
<para>
66
-
&sm.disabled;
67
-
</para>
68
-
</note>
69
-
</refsect1>
70
-

71
85
<refsect1 role="seealso">
72
86
&reftitle.seealso;
73
87
<para>
...
...
@@ -78,7 +92,6 @@ echo "<pre>$output</pre>";
78
92
</para>
79
93
</refsect1>
80
94
</refentry>
81
-

82
95
<!-- Keep this comment at the end of the file
83
96
Local variables:
84
97
mode: sgml
85
98