reference/filesystem/functions/rename.xml
ea62fb83196997032641b50fe44420305466195e
...
...
@@ -10,14 +10,17 @@
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
12
<type>bool</type><methodname>rename</methodname>
13
-
<methodparam><type>string</type><parameter>oldname</parameter></methodparam>
14
-
<methodparam><type>string</type><parameter>newname</parameter></methodparam>
15
-
<methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
13
+
<methodparam><type>string</type><parameter>from</parameter></methodparam>
14
+
<methodparam><type>string</type><parameter>to</parameter></methodparam>
15
+
<methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></methodparam>
16
16
</methodsynopsis>
17
17
<para>
18
-
Attempts to rename <parameter>oldname</parameter> to
19
-
<parameter>newname</parameter>, moving it between directories if necessary.
20
-
If <parameter>newname</parameter> exists, it will be overwritten.
18
+
Attempts to rename <parameter>from</parameter> to
19
+
<parameter>to</parameter>, moving it between directories if necessary.
20
+
If renaming a file and <parameter>to</parameter> exists,
21
+
it will be overwritten. If renaming a directory and
22
+
<parameter>to</parameter> exists,
23
+
this function will emit a warning.
21
24
</para>
22
25
</refsect1>
23
26

...
...
@@ -26,24 +29,31 @@
26
29
<para>
27
30
<variablelist>
28
31
<varlistentry>
29
-
<term><parameter>oldname</parameter></term>
32
+
<term><parameter>from</parameter></term>
30
33
<listitem>
31
34
<para>
35
+
The old name.
32
36
</para>
33
37
<note>
34
38
<para>
35
-
The old name. The wrapper used in <parameter>oldname</parameter>
39
+
The wrapper used in <parameter>from</parameter>
36
40
<emphasis>must</emphasis> match the wrapper used in
37
-
<parameter>newname</parameter>.
41
+
<parameter>to</parameter>.
38
42
</para>
39
43
</note>
40
44
</listitem>
41
45
</varlistentry>
42
46
<varlistentry>
43
-
<term><parameter>newname</parameter></term>
47
+
<term><parameter>to</parameter></term>
44
48
<listitem>
45
49
<para>
46
50
The new name.
51
+
<note>
52
+
<simpara>
53
+
On Windows, if <parameter>to</parameter> already exists, it must be writable.
54
+
Otherwise <function>rename</function> fails and issues <constant>E_WARNING</constant>.
55
+
</simpara>
56
+
</note>
47
57
</para>
48
58
</listitem>
49
59
</varlistentry>
...
...
@@ -64,51 +74,6 @@
64
74
</para>
65
75
</refsect1>
66
76

67
-
<refsect1 role="changelog">
68
-
&reftitle.changelog;
69
-
<para>
70
-
<informaltable>
71
-
<tgroup cols="2">
72
-
<thead>
73
-
<row>
74
-
<entry>&Version;</entry>
75
-
<entry>&Description;</entry>
76
-
</row>
77
-
</thead>
78
-
<tbody>
79
-
<row>
80
-
<entry>5.3.1</entry>
81
-
<entry>
82
-
<function>rename</function> can now rename files across drives in
83
-
Windows.
84
-
</entry>
85
-
</row>
86
-
<row>
87
-
<entry>5.0.0</entry>
88
-
<entry>
89
-
<function>rename</function> can now also be used with
90
-
<emphasis>some</emphasis> URL wrappers. Refer to <xref
91
-
linkend="wrappers"/> for a listing of which wrappers
92
-
support <function>rename</function>.
93
-
</entry>
94
-
</row>
95
-
<row>
96
-
<entry>4.3.3</entry>
97
-
<entry>
98
-
<function>rename</function> may now be able to rename files across
99
-
partitions on *nix based systems, provided the appropriate permissions
100
-
are held. Warnings may be generated if the destination filesystem
101
-
doesn't permit <literal>chown()</literal> or
102
-
<literal>chmod()</literal> system calls to be made on files —
103
-
for example, if the destination filesystem is a FAT filesystem.
104
-
</entry>
105
-
</row>
106
-
</tbody>
107
-
</tgroup>
108
-
</informaltable>
109
-
</para>
110
-
</refsect1>
111
-

112
77
<refsect1 role="examples">
113
78
&reftitle.examples;
114
79
<para>
115
80