reference/dba/functions/dba-open.xml
e4faf426c06f29bef4b1fbd7043d56f4756a0a50
...
...
@@ -8,11 +8,13 @@
8
8
<refsect1 role="description">
9
9
&reftitle.description;
10
10
<methodsynopsis>
11
-
<type>resource</type><methodname>dba_open</methodname>
11
+
<type class="union"><type>resource</type><type>false</type></type><methodname>dba_open</methodname>
12
12
<methodparam><type>string</type><parameter>path</parameter></methodparam>
13
13
<methodparam><type>string</type><parameter>mode</parameter></methodparam>
14
-
<methodparam choice="opt"><type>string</type><parameter>handler</parameter></methodparam>
15
-
<methodparam choice="opt"><type>mixed</type><parameter>...</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>
17
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>flags</parameter><initializer>&null;</initializer></methodparam>
16
18
</methodsynopsis>
17
19
<para>
18
20
<function>dba_open</function> establishes a database instance for
...
...
@@ -20,6 +22,7 @@
20
22
<parameter>handler</parameter>.
21
23
</para>
22
24
</refsect1>
25
+

23
26
<refsect1 role="parameters">
24
27
&reftitle.parameters;
25
28
<para>
...
...
@@ -140,7 +143,7 @@
140
143
</tgroup>
141
144
</table>
142
145
<simplelist>
143
-
<member>ok: the second call will be successfull.</member>
146
+
<member>ok: the second call will be successful.</member>
144
147
<member>wait: the second call waits until <function>dba_close</function> is called for the first.</member>
145
148
<member>false: the second call returns false.</member>
146
149
<member>illegal: you must not mix <literal>"l"</literal> and <literal>"d"</literal> modifiers for <parameter>mode</parameter> parameter.</member>
...
...
@@ -156,46 +159,104 @@
156
159
The name of the <link linkend="dba.requirements">handler</link> which
157
160
shall be used for accessing <parameter>path</parameter>. It is passed
158
161
all optional parameters given to <function>dba_open</function> and
159
-
can act on behalf of them.
162
+
can act on behalf of them. If <parameter>handler</parameter> is &null;,
163
+
then the default handler is invoked.
164
+
</para>
165
+
</listitem>
166
+
</varlistentry>
167
+
<varlistentry>
168
+
<term><parameter>permission</parameter></term>
169
+
<listitem>
170
+
<para>
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>.
174
+
</para>
175
+
<para>
176
+
The <literal>db1</literal>, <literal>db2</literal>, <literal>db3</literal>,
177
+
<literal>db4</literal>, <literal>dbm</literal>, <literal>gdbm</literal>,
178
+
<literal>ndbm</literal>, and <literal>lmdb</literal> drivers support the
179
+
<parameter>permission</parameter> parameter.
180
+
</para>
181
+
</listitem>
182
+
</varlistentry>
183
+
<varlistentry>
184
+
<term><parameter>map_size</parameter></term>
185
+
<listitem>
186
+
<para>
187
+
Optional &integer; parameter which is passed to the driver. Its value should be a multiple of the
188
+
page size of the OS, or zero, to use the default map size.
189
+
</para>
190
+
<para>
191
+
Only the <literal>lmdb</literal> driver accepts the <parameter>map_size</parameter> parameter.
192
+
</para>
193
+
</listitem>
194
+
</varlistentry>
195
+
<varlistentry>
196
+
<term><parameter>flags</parameter></term>
197
+
<listitem>
198
+
<para>
199
+
Flags to pass to the database drivers. If &null; the default flags will be provided.
200
+
Currently, only the LMDB driver supports the following flags
201
+
<constant>DBA_LMDB_USE_SUB_DIR</constant> and
202
+
<constant>DBA_LMDB_NO_SUB_DIR</constant>.
160
203
</para>
161
204
</listitem>
162
205
</varlistentry>
163
206
</variablelist>
164
207
</para>
165
208
</refsect1>
209
+

166
210
<refsect1 role="returnvalues">
167
211
&reftitle.returnvalues;
168
212
<para>
169
213
Returns a positive handle on success&return.falseforfailure;.
170
214
</para>
171
215
</refsect1>
172
-
<refsect1 role="changelog">
173
-
&reftitle.changelog;
216
+

217
+
<refsect1 role="errors">
218
+
&reftitle.errors;
174
219
<para>
175
-
<informaltable>
176
-
<tgroup cols="2">
177
-
<thead>
178
-
<row>
179
-
<entry>&Version;</entry>
180
-
<entry>&Description;</entry>
181
-
</row>
182
-
</thead>
183
-
<tbody>
184
-
<row>
185
-
<entry>4.3.0</entry>
186
-
<entry>
187
-
It's possible to open database files over network connection. However
188
-
in cases a socket connection will be used (as with http or ftp) the
189
-
connection will be locked instead of the resource itself. This is important
190
-
to know since in such cases locking is simply ignored on the resource
191
-
and other solutions have to be found.
192
-
</entry>
193
-
</row>
194
-
</tbody>
195
-
</tgroup>
196
-
</informaltable>
220
+
&false; is returned and an <constant>E_WARNING</constant> level error is issued when
221
+
<parameter>handler</parameter> is &null;, but there is no default handler.
197
222
</para>
198
223
</refsect1>
224
+

225
+
<refsect1 role="changelog">
226
+
&reftitle.changelog;
227
+
<informaltable>
228
+
<tgroup cols="2">
229
+
<thead>
230
+
<row>
231
+
<entry>&Version;</entry>
232
+
<entry>&Description;</entry>
233
+
</row>
234
+
</thead>
235
+
<tbody>
236
+
<row>
237
+
<entry>8.2.0</entry>
238
+
<entry>
239
+
<parameter>flags</parameter> is added.
240
+
</entry>
241
+
</row>
242
+
<row>
243
+
<entry>8.2.0</entry>
244
+
<entry>
245
+
<parameter>handler</parameter> is now nullable.
246
+
</entry>
247
+
</row>
248
+
<row>
249
+
<entry>7.3.14, 7.4.2</entry>
250
+
<entry>
251
+
The <literal>lmdb</literal> driver now supports an additional <parameter>map_size</parameter>
252
+
parameter.
253
+
</entry>
254
+
</row>
255
+
</tbody>
256
+
</tgroup>
257
+
</informaltable>
258
+
</refsect1>
259
+

199
260
<refsect1 role="seealso">
200
261
&reftitle.seealso;
201
262
<para>
...
...
@@ -206,7 +267,6 @@
206
267
</para>
207
268
</refsect1>
208
269
</refentry>
209
-

210
270
<!-- Keep this comment at the end of the file
211
271
Local variables:
212
272
mode: sgml
213
273