Skip to content

Commit adf1322

Browse files
kocsismatekocsismate
committed
Update the signature of dba_open() and dba_popen()
1 parent ef24d91 commit adf1322

File tree

2 files changed

+101
-29
lines changed

2 files changed

+101
-29
lines changed

‎reference/dba/functions/dba-open.xml

Lines changed: 39 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,17 @@
1111
<type class="union"><type>resource</type><type>false</type></type><methodname>dba_open</methodname>
1212
<methodparam><type>string</type><parameter>path</parameter></methodparam>
1313
<methodparam><type>string</type><parameter>mode</parameter></methodparam>
14-
<methodparam choice="opt"><type>string</type><parameter>handler</parameter></methodparam>
15-
<methodparam rep="repeat"><type>string</type><parameter>args</parameter></methodparam>
14+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>handler</parameter><initializer>&null;</initializer></methodparam>
15+
<methodparam choice="opt"><type>int</type><parameter>permission</parameter><initializer>0644</initializer></methodparam>
16+
<methodparam choice="opt"><type>int</type><parameter>map_size</parameter><initializer>0</initializer></methodparam>
1617
</methodsynopsis>
1718
<para>
1819
<function>dba_open</function> establishes a database instance for
1920
<parameter>path</parameter> with <parameter>mode</parameter> using
2021
<parameter>handler</parameter>.
2122
</para>
2223
</refsect1>
24+
2325
<refsect1 role="parameters">
2426
&reftitle.parameters;
2527
<para>
@@ -156,40 +158,57 @@
156158
The name of the <link linkend="dba.requirements">handler</link> which
157159
shall be used for accessing <parameter>path</parameter>. It is passed
158160
all optional parameters given to <function>dba_open</function> and
159-
can act on behalf of them.
161+
can act on behalf of them. If <parameter>handler</parameter> is &null;,
162+
then either the default handler is invoked, or &false; is returned
163+
along with triggering an <literal>E_WARNING</literal>.
160164
</para>
161165
</listitem>
162166
</varlistentry>
163167
<varlistentry>
164-
<term><parameter>args</parameter></term>
168+
<term><parameter>permission</parameter></term>
165169
<listitem>
166170
<para>
167-
Optional &string; parameters which are passed to the driver.
171+
Optional &integer; parameter which is passed to the driver. It has the same meaning as
172+
the <parameter>permissions</parameter> parameter of <function>chmod</function>,
173+
and defaults to <literal>0644</literal>.
168174
</para>
169175
<para>
170176
The <literal>cdb</literal>, <literal>cdb_make</literal>, <literal>flatfile</literal>,
171177
<literal>inifile</literal>, <literal>qdbm</literal> and <literal>tcadb</literal> drivers
172-
do not support additional parameters.
178+
do not support the <parameter>permission</parameter> parameter.
173179
</para>
174180
<para>
175181
The <literal>db1</literal>, <literal>db2</literal>, <literal>db3</literal>,
176182
<literal>db4</literal>, <literal>dbm</literal>, <literal>gdbm</literal>,
177-
and <literal>ndbm</literal> drivers supports a single additional parameter <literal>$filemode</literal>,
178-
which has the same meaning as the <literal>$mode</literal> parameter of <function>chmod</function>,
179-
and defaults to <literal>0644</literal>.
183+
<literal>ndbm</literal>, and <literal>lmdb</literal> drivers support the
184+
<parameter>permission</parameter> parameter.
180185
</para>
186+
</listitem>
187+
</varlistentry>
188+
<varlistentry>
189+
<term><parameter>map_size</parameter></term>
190+
<listitem>
181191
<para>
182-
The <literal>lmdb</literal> driver accepts two additional parameters. The first
183-
allows to specify the <literal>$filemode</literal> (see description above), and the
184-
second to specify the <literal>$mapsize</literal>, where the value should be a multiple
185-
of the page size of the OS, or zero, to use the default mapsize. The <literal>$mapsize</literal>
192+
Optional &integer; parameter which is passed to the driver. Its value should be a multiple of the
193+
page size of the OS, or zero, to use the default map size. The <parameter>map_size</parameter>
186194
parameter is supported as of PHP 7.3.14 and 7.4.2, respectively.
187195
</para>
196+
<para>
197+
The <literal>cdb</literal>, <literal>cdb_make</literal>, <literal>flatfile</literal>,
198+
<literal>inifile</literal>, <literal>qdbm</literal>, <literal>tcadb</literal>,
199+
<literal>db1</literal>, <literal>db2</literal>, <literal>db3</literal>,
200+
<literal>db4</literal>, <literal>dbm</literal>, <literal>gdbm</literal>,
201+
and <literal>ndbm</literal> drivers don't support the <parameter>map_size</parameter> parameter.
202+
</para>
203+
<para>
204+
The <literal>lmdb</literal> driver accepts the <parameter>map_size</parameter> parameter.
205+
</para>
188206
</listitem>
189207
</varlistentry>
190208
</variablelist>
191209
</para>
192210
</refsect1>
211+
193212
<refsect1 role="returnvalues">
194213
&reftitle.returnvalues;
195214
<para>
@@ -208,10 +227,16 @@
208227
</row>
209228
</thead>
210229
<tbody>
230+
<row>
231+
<entry>8.1.0</entry>
232+
<entry>
233+
<parameter>handler</parameter> is now nullable.
234+
</entry>
235+
</row>
211236
<row>
212237
<entry>7.3.14, 7.4.2</entry>
213238
<entry>
214-
The <literal>lmdb</literal> driver now supports an additional <literal>$mapsize</literal>
239+
The <literal>lmdb</literal> driver now supports an additional <parameter>map_size</parameter>
215240
parameter.
216241
</entry>
217242
</row>
@@ -230,7 +255,6 @@
230255
</para>
231256
</refsect1>
232257
</refentry>
233-
234258
<!-- Keep this comment at the end of the file
235259
Local variables:
236260
mode: sgml

‎reference/dba/functions/dba-popen.xml

Lines changed: 62 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,17 @@
1111
<type class="union"><type>resource</type><type>false</type></type><methodname>dba_popen</methodname>
1212
<methodparam><type>string</type><parameter>path</parameter></methodparam>
1313
<methodparam><type>string</type><parameter>mode</parameter></methodparam>
14-
<methodparam choice="opt"><type>string</type><parameter>handler</parameter></methodparam>
15-
<methodparam rep="repeat"><type>mixed</type><parameter>args</parameter></methodparam>
14+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>handler</parameter><initializer>&null;</initializer></methodparam>
15+
<methodparam choice="opt"><type>int</type><parameter>permission</parameter><initializer>0644</initializer></methodparam>
16+
<methodparam choice="opt"><type>int</type><parameter>map_size</parameter><initializer>0</initializer></methodparam>
1617
</methodsynopsis>
1718
<para>
1819
<function>dba_popen</function> establishes a persistent database instance
1920
for <parameter>path</parameter> with <parameter>mode</parameter> using
2021
<parameter>handler</parameter>.
2122
</para>
2223
</refsect1>
24+
2325
<refsect1 role="parameters">
2426
&reftitle.parameters;
2527
<para>
@@ -50,46 +52,93 @@
5052
The name of the <link linkend="dba.requirements">handler</link> which
5153
shall be used for accessing <parameter>path</parameter>. It is passed
5254
all optional parameters given to <function>dba_popen</function> and
53-
can act on behalf of them.
55+
can act on behalf of them. If <parameter>handler</parameter> is &null;,
56+
then either the default handler is invoked, or &false; is returned
57+
along with triggering an <literal>E_WARNING</literal>.
5458
</para>
5559
</listitem>
5660
</varlistentry>
5761
<varlistentry>
58-
<term><parameter>args</parameter></term>
62+
<term><parameter>permission</parameter></term>
5963
<listitem>
6064
<para>
61-
Optional &string; parameters which are passed to the driver.
65+
Optional &integer; parameter which is passed to the driver. It has the same meaning as
66+
the <parameter>permissions</parameter> parameter of <function>chmod</function>,
67+
and defaults to <literal>0644</literal>.
6268
</para>
6369
<para>
6470
The <literal>cdb</literal>, <literal>cdb_make</literal>, <literal>flatfile</literal>,
6571
<literal>inifile</literal>, <literal>qdbm</literal> and <literal>tcadb</literal> drivers
66-
do not support additional parameters.
72+
do not support the <parameter>permission</parameter> parameter.
6773
</para>
6874
<para>
6975
The <literal>db1</literal>, <literal>db2</literal>, <literal>db3</literal>,
7076
<literal>db4</literal>, <literal>dbm</literal>, <literal>gdbm</literal>,
71-
and <literal>ndbm</literal> drivers supports a single additional parameter <literal>$filemode</literal>,
72-
which has the same meaning as the <literal>$mode</literal> parameter of <function>chmod</function>,
73-
and defaults to <literal>0644</literal>.
77+
<literal>ndbm</literal>, and <literal>lmdb</literal> drivers support the
78+
<parameter>permission</parameter> parameter.
7479
</para>
80+
</listitem>
81+
</varlistentry>
82+
<varlistentry>
83+
<term><parameter>map_size</parameter></term>
84+
<listitem>
7585
<para>
76-
The <literal>lmdb</literal> driver accepts two additional parameters. The first
77-
allows to specify the <literal>$filemode</literal> (see description above), and the
78-
second to specify the <literal>$mapsize</literal>, where the value should be a multiple
79-
of the page size of the OS, or zero, to use the default mapsize. The <literal>$mapsize</literal>
86+
Optional &integer; parameter which is passed to the driver. Its value should be a multiple of the
87+
page size of the OS, or zero, to use the default mapsize. The <parameter>map_size</parameter>
8088
parameter is supported as of PHP 7.3.14 and 7.4.2, respectively.
8189
</para>
90+
<para>
91+
The <literal>cdb</literal>, <literal>cdb_make</literal>, <literal>flatfile</literal>,
92+
<literal>inifile</literal>, <literal>qdbm</literal>, <literal>tcadb</literal>,
93+
<literal>db1</literal>, <literal>db2</literal>, <literal>db3</literal>,
94+
<literal>db4</literal>, <literal>dbm</literal>, <literal>gdbm</literal>,
95+
and <literal>ndbm</literal> drivers don't support the <parameter>map_size</parameter> parameter.
96+
</para>
97+
<para>
98+
The <literal>lmdb</literal> driver accepts the <parameter>map_size</parameter> parameter.
99+
</para>
82100
</listitem>
83101
</varlistentry>
84102
</variablelist>
85103
</para>
86104
</refsect1>
105+
87106
<refsect1 role="returnvalues">
88107
&reftitle.returnvalues;
89108
<para>
90109
Returns a positive handle on success&return.falseforfailure;.
91110
</para>
92111
</refsect1>
112+
113+
<refsect1 role="changelog">
114+
&reftitle.changelog;
115+
<informaltable>
116+
<tgroup cols="2">
117+
<thead>
118+
<row>
119+
<entry>&Version;</entry>
120+
<entry>&Description;</entry>
121+
</row>
122+
</thead>
123+
<tbody>
124+
<row>
125+
<entry>8.1.0</entry>
126+
<entry>
127+
<parameter>handler</parameter> is now nullable.
128+
</entry>
129+
</row>
130+
<row>
131+
<entry>7.3.14, 7.4.2</entry>
132+
<entry>
133+
The <literal>lmdb</literal> driver now supports an additional <parameter>map_size</parameter>
134+
parameter.
135+
</entry>
136+
</row>
137+
</tbody>
138+
</tgroup>
139+
</informaltable>
140+
</refsect1>
141+
93142
<refsect1 role="seealso">
94143
&reftitle.seealso;
95144
<para>
@@ -100,7 +149,6 @@
100149
</para>
101150
</refsect1>
102151
</refentry>
103-
104152
<!-- Keep this comment at the end of the file
105153
Local variables:
106154
mode: sgml

0 commit comments

Comments
 (0)