<?xml version="1.0" encoding="utf-8"?>

<!-- $Revision$ -->

<!-- EN-Revision: a89c6d71c7b65e3de84f26230fbf72c9b8948adf Maintainer: daijie Status: ready -->

<!-- CREDITS: Luffy, mowangjuanzi -->

<refentry xml:id="function.dl" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>dl</refname>

<refpurpose>运行时载入一个 PHP 扩展</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type>bool</type><methodname>dl</methodname>

<methodparam><type>string</type><parameter>extension_filename</parameter></methodparam>

</methodsynopsis>

<para>

载入指定参数 <parameter>extension_filename</parameter> 的 PHP 扩展。

</para>

<para>

使用 <function>extension_loaded</function> 来测试指定的扩展是否已经激活。

这既能用于内建的扩展也可以用于动态加载的扩展（既可以通过 &php.ini; 也可以通过 <function>dl</function>）。

</para>

<warning>

<simpara>

此函数仅适用于 <acronym>CLI</acronym> 和嵌入式 <acronym>SAPI</acronym>，以及从命令行运行时的

<acronym>CGI</acronym> <acronym>SAPI</acronym>。

</simpara>

</warning>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>extension_filename</parameter></term>

<listitem>

<para>

此参数<emphasis>仅仅</emphasis>是要加载的扩展的文件名，依赖于你的平台。

比如，<link linkend="ref.sockets">sockets</link>（作为共享模块编译，而不是默认的！）在 Unix 平台上称为 <filename>sockets.so</filename> 而 在 Windows 平台上是 <filename>php_sockets.dll</filename>。

</para>

<para>

扩展加载的目录依赖于你的平台：

</para>

<para>

Windows - 如果没有在 &php.ini; 里明确设置，扩展默认会从 <filename>C:\php5\</filename> 加载。

</para>

<para>

Unix - 如果没有在 &php.ini; 里明确设置，默认的扩展目录依赖于

<itemizedlist>

<listitem>

<simpara>

PHP 是否通过 <literal>--enable-debug</literal> 选项构建

</simpara>

</listitem>

<listitem>

<simpara>

PHP 是否以 ZTS （Zend 线程安全）支持构建

</simpara>

</listitem>

<listitem>

<simpara>

当前的内部 <literal>ZEND_MODULE_API_NO</literal>（Zend 内部模块 API 数字，基本上是主要模块修改时的日期）

</simpara>

</listitem>

</itemizedlist>

考虑到上述，目录默认为 <literal>&lt;install-dir&gt;/lib/php/extensions/ &lt;debug-or-not&gt;-&lt;zts-or-not&gt;-ZEND_MODULE_API_NO</literal>，例如

<filename>/usr/local/php/lib/php/extensions/debug-non-zts-20010901</filename>

或

<filename>/usr/local/php/lib/php/extensions/no-debug-zts-20010901</filename>。

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

&return.success; 如果加载模块的功能是无效或者禁用的（可以关闭 <link linkend="ini.enable-dl">enable_dl</link> 设置）将导致一个 <constant>E_ERROR</constant> 并中断执行。

如果因为指定的库无法加载而导致 <function>dl</function> 失败，除了返回 &false;，还会产生一个 <constant>E_WARNING</constant> 的消息。

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title><function>dl</function> 示例</title>

<programlisting role="php">

<![CDATA[

<?php

// 加载一个扩展的示例，基于操作系统

if (!extension_loaded('sqlite')) {

if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {

dl('php_sqlite.dll');

} else {

dl('sqlite.so');

}

}

// 或者，使用常量 PHP_SHLIB_SUFFIX

if (!extension_loaded('sqlite')) {

$prefix = (PHP_SHLIB_SUFFIX === 'dll') ? 'php_' : '';

dl($prefix . 'sqlite.' . PHP_SHLIB_SUFFIX);

}

?>

]]>

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

在某些 Unix 平台上，<function>dl</function> 是大小写敏感的。

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><link linkend="ini.extension">扩展加载指令</link></member>

<member><function>extension_loaded</function></member>

</simplelist>

</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->