php-doc-en/language-snippets.ent

<!-- $Revision$ -->
<!-- Keep 'em sorted -->


<!-- Notes -->

<!ENTITY note.bin-safe '<note><simpara>This function is
binary-safe.</simpara></note>'>

<!ENTITY note.clearstatcache '<note><simpara>The results of this 
function are cached. See <function>clearstatcache</function> for 
more details.</simpara></note>'>

<!ENTITY note.context-support '<note><simpara>Context support was added
with PHP 5.0.0. For a description of <literal>contexts</literal>, refer to
<xref linkend="ref.stream"/>.</simpara></note>'>

<!ENTITY note.exec-bg '<note><para>If a program is started with this function,
in order for it to continue running in the background, the output of the
program must be redirected to a file or another output stream. Failing to do so
will cause PHP to hang until the execution of the program ends.</para></note>'>

<!ENTITY note.func-callback '<note><simpara>Instead of a function name, an
array containing an object reference and a method name can also be
supplied.</simpara></note>'>

<!ENTITY note.funcnoparam '<note><para>Because this function depends on the
current scope to determine parameter details, it cannot be used as a
function parameter. If this value must be passed, the results should be assigned
to a variable, and that variable should be passed.</para></note>'>

<!ENTITY note.line-endings '<note><simpara>If PHP is not properly recognizing
the line endings when reading files either on or created by a Macintosh
computer, enabling the
<link linkend="ini.auto-detect-line-endings">auto_detect_line_endings</link>
run-time configuration option may help resolve the problem.</simpara></note>'>

<!ENTITY note.no-remote '<note><simpara>This function will not work on 
<link linkend="features.remote-files">remote files</link> as the file to
be examined must be accessible via the server&apos;s filesystem.</simpara></note>'>

<!ENTITY note.not-bin-safe '<warning><simpara>This function
is not (yet) binary safe!</simpara></warning>'>

<!ENTITY note.no-key-association '<note><simpara>This function
assigns new keys to the elements in <parameter>array</parameter>.
It will remove any existing keys that may have been assigned, rather
than just reordering the keys.</simpara></note>'>

<!ENTITY note.no-windows '<note><simpara>This function is not
implemented on Windows platforms.</simpara></note>'>

<!ENTITY note.no-windows.extension '<note><simpara>This extension is not
available on Windows platforms.</simpara></note>'>

<!ENTITY note.randomseed '<note><simpara>As of PHP 4.2.0, there is no need 
to seed the random number generator with <function>srand</function> or 
<function>mt_srand</function> as this is now done automatically.
</simpara></note>'>

<!ENTITY note.registerglobals '<note><title>register_globals: important
note</title><para>As of PHP 4.2.0, the default value for the PHP directive
<link linkend="ini.register-globals">register_globals</link> is <emphasis>
off</emphasis>, and it was completely removed as of PHP 6.0.0. The PHP community
discourages developers from relying on this directive, and encouragees the use
of other means, such as the &link.superglobals;.</para></note>'>

<!ENTITY note.superglobals '<note><title>Superglobals: availability note
</title><para>Superglobal arrays such as <varname>$_GET</varname>,
<varname>$_POST</varname>, and <varname>$_SERVER</varname>, etc. are available
as of PHP 4.1.0. For more information, read the manual section on
&link.superglobals;</para></note>'>

<!ENTITY note.uses-ob '<note><para>This function uses internal output buffering
with this parameter so it can not be used inside an
<function>ob_start</function> callback function.</para></note>'>

<!-- Tips -->

<!ENTITY tip.fopen-wrapper '<tip><simpara>A URL can be used as a
filename with this function if the <link linkend="ini.allow-url-fopen"
>fopen wrappers</link> have been enabled.
See <function>fopen</function> for more details on how to specify
the filename and <xref linkend="wrappers"/> for a list of supported
URL protocols.</simpara></tip>'>

<!ENTITY tip.fopen-wrapper.stat '<tip><simpara>As of PHP 5.0.0, this function
can also be used with <emphasis>some</emphasis> URL wrappers.  Refer to 
<xref linkend="wrappers"/> for a listing of which wrappers support 
<function>stat</function> family of functionality.</simpara></tip>'>

<!ENTITY tip.ob-capture '<tip><simpara>As with anything that outputs
its result directly to the browser, the <link
linkend="ref.outcontrol">output-control functions</link> can be used to capture
the output of this function, and save it in a
<type>string</type> (for example).</simpara></tip>'>

<!ENTITY tip.userlandnaming '<tip><simpara>See also the
<xref linkend="userlandnaming" />.</simpara></tip>'>


<!-- Warnings -->

<!ENTITY warn.escapeshell '<warning><para>When allowing user-supplied data to be
passed to this function, use
<function>escapeshellarg</function> or <function>escapeshellcmd</function>
to ensure that users cannot trick the system into executing arbitrary
commands.</para></warning>'>

<!ENTITY warn.experimental '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This extension is
<emphasis>EXPERIMENTAL</emphasis>. The behaviour of this extension—including
the names of its functions and any other documentation surrounding this
extension—may change without notice in a future release of PHP.
This extension should be used at your own risk.</simpara></warning>'>

<!ENTITY warn.deprecated.removed-6-0-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This feature has been
<emphasis>DEPRECATED</emphasis> and <emphasis>REMOVED</emphasis> as of PHP 6.0.0.
Relying on this feature is highly discouraged.</simpara></warning>'>

<!ENTITY warn.deprecated.function.removed-5-3-0 '<warning
xmlns="http://docbook.org/ns/docbook"><simpara>This function has been
<emphasis>DEPRECATED</emphasis> and <emphasis>REMOVED</emphasis> as of PHP 5.3.0.</simpara></warning>'>

<!ENTITY warn.experimental.func '<warning xmlns="http://docbook.org/ns/docbook"><simpara>This function is
<emphasis>EXPERIMENTAL</emphasis>. The behaviour of this function, the
its name, and surrounding documentation may change without notice in a future
release of PHP. This function should be used at your own risk.
</simpara></warning>'>

<!ENTITY warn.imaprecodeyaz '<warning><simpara>The <link
linkend="ref.imap">IMAP</link>, <link linkend="ref.recode">recode</link>,
<link linkend="ref.yaz">YAZ</link> and <link linkend="ref.cyrus">Cyrus</link>
extensions cannot be used in conjuction, because they
share the same internal symbols.</simpara></warning>'>

<!ENTITY warn.install.cgi '<warning><para>A server deployed in CGI mode is open
to several possible vulnerabilities. Please read our
<link linkend="security.cgi-bin">CGI security section</link> to learn how to
defend yourself from such attacks.</para></warning>'>

<!ENTITY note.magicquotes.gpc '<note><title>directive note: magic_quotes_gpc
</title><para>The <link linkend="ini.magic-quotes-gpc">magic_quotes_gpc</link>
directive defaults to <literal>on</literal>. It essentially runs
<function>addslashes</function> on all GET, POST, and COOKIE data.
<function>stripslashes</function> may be used to remove them.</para></note>'>

<!ENTITY warn.no-win32-fopen-wrapper '<warning><para>Windows versions of PHP
prior to PHP 4.3.0 do not support access of remote files via this function,
even if <link linkend="ini.allow-url-fopen">allow_url_fopen</link> is enabled.
</para></warning>'>

<!ENTITY warn.ssl-non-standard '<warning><para>When using SSL, Microsoft IIS
will violate the protocol by closing the connection without sending a
<literal>close_notify</literal> indicator. PHP will report this as "SSL: Fatal
Protocol Error" when you reach the end of the data. To work around this, the
value of <link linkend="ini.error-reporting">error_reporting</link> should be
lowered to a level that does not include warnings.
PHP 4.3.7 and higher can detect buggy IIS server software when you open
the stream using the <literal>https://</literal> wrapper and will suppress the
warning. When using <function>fsockopen</function> to create an
<literal>ssl://</literal> socket, the developer is responsible for detecting
and suppressing this warning.</para></warning>'>

<!ENTITY warn.undocumented.func '<warning><simpara>This function is
currently not documented; only its argument list is available.
</simpara></warning>'>


<!-- Misc -->

<!ENTITY no.function.parameters '<para>This function has no parameters.</para>'>

<!ENTITY example.outputs '<para>The above example will output:</para>'>

<!ENTITY example.outputs.similar '<para>The above example will output 
something similar to:</para>'>

<!ENTITY array.resetspointer '<note><simpara>This function will 
<function>reset</function> the <type>array</type> pointer after 
use.</simpara></note>'>

<!ENTITY seealso.callback 'information about the <link linkend="language.types.callback">callback</link> type'>

<!ENTITY avail.register-long-arrays 'As of PHP 5.0.0, the long PHP 
<link linkend="language.variables.predefined">predefined variable</link>
arrays may be disabled with the 
<link linkend="ini.register-long-arrays">register_long_arrays</link>
directive.'>

<!ENTITY ini.shorthandbytes '<simpara>When an <type>integer</type> is used, the 
value is measured in bytes. Shorthand notation, as described 
in <link linkend="faq.using.shorthandbytes">this FAQ</link>, may also be used.
</simpara>'>

<!ENTITY info.deprecated.alias 'For backward compatibility, the following 
deprecated alias may be used: '>

<!ENTITY info.function.alias 'This function is an alias of: '>

<!ENTITY info.function.alias.deprecated '<simpara>This function alias is 
deprecated and only exists for backwards compatibility reasons. The use of this
function is not recommended, as it may be removed from PHP in the future.
</simpara>'>

<!ENTITY ext.windows.path.dll 'In order for this extension to work, there are
<acronym>DLL</acronym> files that must be available to the Windows
system <literal>PATH</literal>. For information on how to do this, see the
<acronym>FAQ</acronym> entitled "<link
linkend="faq.installation.addtopath">How do I add my PHP directory to the PATH
on Windows</link>". Although copying DLL
files from the PHP folder into the Windows system directory also works
(because the system directory is by default in the system&apos;s
<literal>PATH</literal>), this is not recommended. 
<emphasis>This extension requires the following files to be in the
<literal>PATH</literal>:</emphasis> '>

<!-- Returns -->

<!ENTITY return.success 'Returns &true; on success or &false; on failure.'>

<!ENTITY return.void 'No value is returned.'>

<!ENTITY return.falseproblem '<warning><simpara>This function may
return Boolean &false;, but may also return a non-Boolean value which
evaluates to &false;, such as <literal>0</literal> or
&quot;&quot;. Please read the section on <link
linkend="language.types.boolean">Booleans</link> for more
information. Use <link linkend="language.operators.comparison">the ===
operator</link> for testing the return value of this
function.</simpara></warning>'>




<!-- Image (GD) Notes -->
<!ENTITY note.config.t1lib '<note><simpara>This function is only available 
if PHP is compiled using <option role="configure">--with-t1lib[=DIR]</option>.
</simpara></note>'>

<!ENTITY note.config.jpeg '<note><simpara>JPEG support is only available if 
PHP was compiled against GD-1.8 or later.</simpara></note>'>

<!ENTITY note.config.wbmp '<note><simpara>WBMP support is only available if 
PHP was compiled against GD-1.8 or later.</simpara></note>'>

<!ENTITY note.bundled.gd '<note><simpara>This function is only available if
PHP is compiled with the bundled version of the GD library.</simpara></note>'>

<!ENTITY note.freetype '<note><simpara>This function is only available if
PHP is compiled with freetype support (<option role="configure">--with-freetype-dir=DIR</option>)
</simpara></note>'>

<!ENTITY note.gd.2 '<note><simpara>This function requires GD 2.0.1 or later (2.0.28 or later is recommended).</simpara></note>'>

<!ENTITY gd.image.description '<varlistentry><term><parameter>
image</parameter></term><listitem><para>An image resource, returned by one of the image creation functions, 
such as <function>imagecreatetruecolor</function>.</para></listitem></varlistentry>'>

<!ENTITY gd.font.description '<varlistentry><term><parameter>
font</parameter></term><listitem><para>Can be 1, 2, 3, 4, 5 for built-in 
fonts in latin2 encoding (where higher numbers corresponding to larger fonts) or any of your
own font identifiers registered with <function>imageloadfont</function>.
</para></listitem></varlistentry>'>

<!-- DBM notes -->

<!ENTITY dbm.dbm-identifier.description '<varlistentry><term><parameter>
dbm_identifier</parameter></term><listitem><para>The DBM link identifier,
returned by <function>dbmopen</function>.</para></listitem></varlistentry>'>

<!-- cURL notes -->

<!ENTITY curl.ch.description '<varlistentry><term><parameter>ch</parameter>
</term><listitem><para>A cURL handle returned by 
<function>curl_init</function>.</para></listitem></varlistentry>'>

<!ENTITY curl.mh.description '<varlistentry><term><parameter>mh</parameter>
</term><listitem><para>A cURL multi handle returned by 
<function>curl_multi_init</function>.</para></listitem></varlistentry>'>

<!-- IMAP notes -->

<!ENTITY imap.imap-stream.description '<varlistentry><term><parameter>
imap_stream</parameter></term><listitem><para>An IMAP stream returned by 
<function>imap_open</function>.</para></listitem></varlistentry>'>

<!-- mbstring notes -->

<!ENTITY note.mbstring.encoding.internal '<note><para>The internal encoding or the 
character encoding specified by <function>mb_regex_encoding</function> 
will be used as the character encoding for this function.</para></note>'>

<!ENTITY mbstring.encoding.parameter '<para>The <parameter>encoding</parameter> 
parameter is the character encoding. If it is omitted, the internal character 
encoding value will be used.</para>'>

<!-- MCVE notes -->

<!ENTITY mcve.conn.description '<varlistentry><term><parameter>
conn</parameter></term><listitem><para>An MCVE_CONN resource returned by 
<function>m_initengine</function>.</para></listitem></varlistentry>'>

<!-- Date and time entities -->
<!ENTITY date.timezone.errors.description '<para>
Every call to a date/time function will generate a <constant>E_NOTICE</constant> 
if the time zone is not valid, and/or a <constant>E_STRICT</constant> message
if using the system settings or the <varname>TZ</varname> environment
variable. See also <function>date_default_timezone_set</function></para>'>

<!ENTITY date.timezone.errors.changelog '<row><entry>5.1.0</entry><entry><para>
Now issues the <constant>E_STRICT</constant> and <constant>E_NOTICE</constant> 
time zone errors.</para></entry></row>'>

<!ENTITY date.timestamp.description '
<varlistentry><term><parameter>timestamp</parameter></term><listitem><para>
The optional <parameter>timestamp</parameter> parameter is an 
<type>integer</type> Unix timestamp that defaults to the current
local time if a <parameter>timestamp</parameter> is not given. In other 
words, it defaults to the value of <function>time</function>. 
</para></listitem></varlistentry>'>

<!-- DomXml Notes -->
<!ENTITY node.inserted 'This node will not show up in the document unless it
is inserted with (e.g.) <function>domnode_append_child</function>.'>


<!-- Dom Notes -->
<!ENTITY dom.node.inserted 'This node will not show up in the document unless 
it is inserted with (e.g.) <link 
linkend="domnode.appendchild">DOMNode->appendChild()</link>.'>


<!-- FileSystem entities -->
<!ENTITY fs.validfp.all '<para>The file pointer must be valid, and must point to
a file successfully opened by <function>fopen</function> or
<function>fsockopen</function> (and not yet closed by
<function>fclose</function>).</para>'>

<!ENTITY fs.file.pointer '<para>A file system pointer <type>resource</type>
that is typically created using <function>fopen</function>.</para>'>

<!-- Oracle -->
<!ENTITY oci.charset "<para>Using Oracle server version 9.2 and greater, you can
indicate <parameter>charset</parameter> by parameter, which will be used in the new
connection. If you're using Oracle server &lt; 9.2, this parameter will be ignored
and the <literal>NLS_LANG</literal> environment variable will be used instead.
</para>">

<!ENTITY oci.datatypes '<para>For details on the data type mapping performed by 
the oci8 driver, see the <link linkend="oci8.datatypes">datatypes 
supported by the driver</link></para>'>

<!-- PCNTL Notes -->
<!ENTITY pcntl.parameter.status '<para>The <parameter>status</parameter>
parameter is the status parameter supplied to a successful
call to <function>pcntl_waitpid</function>.</para>'>


<!-- XSLT Notes -->
<!ENTITY note.xslt.windows '<note><para>Please note that
<literal>file://</literal> is needed in front of the path when using Windows.
</para></note>'>


<!-- Notes for safe-mode limited functions: -->
<!ENTITY note.sm.disabled '<note><simpara>&sm.disabled;</simpara></note>'>

<!ENTITY note.sm.uidcheck '<note><simpara>When <link 
linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether 
the files or directories being operated upon have the same UID (owner) as the 
script that is being executed.</simpara></note>'>

<!ENTITY note.sm.uidcheck.dir '<note><simpara>When <link 
linkend="features.safe-mode">safe mode</link> is enabled, PHP checks whether 
the directory in which the script is operating has the same UID (owner) as the 
script that is being executed.</simpara></note>'>

<!ENTITY note.open-basedir.func '<note><para>This function is affected by <link 
linkend="ini.open-basedir">open_basedir</link>.</para></note>'>


<!ENTITY note.language-construct '<note><simpara>Because this is a 
language construct and not a function, it cannot be called using 
<link linkend="functions.variable-functions">variable functions</link></simpara>
</note>'>

<!-- Common pieces in features/safe-mode.xml 
     Jade doesn't allow in-line entities, so I put them here... Though they 
     should have been inline in safe-mode.xml -->
<!ENTITY sm.uidcheck 'Checks whether the files or directories being operated
upon have the same UID (owner) as the script that is being executed.'>

<!ENTITY warn.sm.exec '<warning><simpara>With <link linkend="features.safe-mode">safe mode</link> enabled,
the command string is escaped with <function>escapeshellcmd</function>. Thus, 
<literal>echo y | echo x</literal> becomes <literal>echo y \| echo x</literal>.</simpara></warning>'>

<!ENTITY note.exec-path '<note><simpara>When
<link linkend="features.safe-mode">safe mode</link> is enabled, you can only
execute files within the <link linkend="ini.safe-mode-exec-dir">safe_mode_exec_dir</link>.
For practical reasons, it is currently not allowed to have <literal>..</literal>
components in the path to the executable.</simpara></note>'>

<!ENTITY sm.uidcheck.dir 'Checks whether the directory in which
the script is operating has the same UID (owner) as the script that is being
executed.'>

<!ENTITY sm.disabled 'This function is disabled when PHP is running in <link 
linkend="features.safe-mode">safe mode</link>.'>

<!-- Common pieces in partintro-sections -->
<!ENTITY no.config '<para>This extension has no configuration directives defined in &php.ini;.</para>'>
<!ENTITY no.resource '<para>This extension has no resource types defined.</para>'>
<!ENTITY no.constants '<para>This extension has no constants defined.</para>'>
<!ENTITY no.requirement '<para>No external libraries are needed to build this extension.</para>'>
<!ENTITY no.install '<para>There is no installation needed to use these
functions; they are part of the PHP core.</para>'>

<!-- Used in every chapter that has directive descriptions -->
<!ENTITY ini.descriptions.title '<para>Here&apos;s a short explanation of
the configuration directives.</para>'>

<!-- Common pieces for reference part BEGIN-->

<!-- Used in reference/$extname/ini.xml -->
<!ENTITY extension.runtime '<simpara>
The behaviour of these functions is affected by settings in &php.ini;.
</simpara>'>

<!ENTITY ini.php.constants 'For further details and definitions of the 
PHP_INI_* constants, see the <xref linkend="ini"/>.'>

<!-- Used in reference/$extname/constants.xml -->
<!ENTITY extension.constants '<simpara>
The constants below are defined by this extension, and
will only be available when the extension has either
been compiled into PHP or dynamically loaded at runtime.
</simpara>'>

<!-- For STANDARD Constants used in reference/$extname/constants.xml -->
<!ENTITY extension.constants.core '<simpara>
The constants below are always available as part of the PHP core.
</simpara>'>

<!-- Used in reference/$extname/classes.xml -->
<!ENTITY extension.classes '<simpara>
The classes below are defined by this extension, and
will only be available when the extension has either
been compiled into PHP or dynamically loaded at runtime.
</simpara>'>

<!ENTITY note.extension.php5 '<note><simpara>
This extension requires PHP 5.</simpara></note>'>

<!-- PDO entities -->
<!ENTITY pdo.driver-constants '<simpara>The constants below are defined by
this driver, and will only be available when the extension has been either
compiled into PHP or dynamically loaded at runtime. In addition, these
driver-specific constants should only be used if you are using this driver.
Using mysql-specific attributes with the postgres driver may result in
unexpected behaviour. <function>PDO::getAttribute</function> may be used to
obtain the <constant>PDO_ATTR_DRIVER_NAME</constant> attribute to check the
driver, if your code can run against multiple drivers.</simpara>'>

<!-- PECL entities -->
<!ENTITY pecl.moved 'This <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> extension
is not bundled with PHP.'>

<!ENTITY pecl.bundled 'This <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> extension
is bundled with PHP.'>

<!ENTITY pecl.info 'Information for installing this PECL extension may be
found in the manual chapter titled <link linkend="install.pecl">Installation 
of PECL extensions</link>. Additional information such as new releases,
downloads, source files, maintainer information, and a CHANGELOG, can be
located here: '>

<!ENTITY pecl.source.4 'In PHP 4 this <acronym>PECL</acronym> extensions
source can be found in the <filename>ext/</filename> directory within the
PHP source or at the <acronym>PECL</acronym> link above.'>

<!ENTITY pecl.windows.4 'In PHP 4 this <acronym>DLL</acronym> resides in
the <filename>extensions/</filename> directory within the PHP Windows
binaries download.'>

<!ENTITY pecl.windows.download '
The <acronym>DLL</acronym> for this <acronym>PECL</acronym> extension
may be downloaded from either the 
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.php.downloads;">PHP Downloads</link> page or from 
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl.win;">&url.pecl.win;</link>'>

<!ENTITY pecl.windows.download.unbundled 'Unbundled <acronym>PECL</acronym> 
extensions may be downloaded from:
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl.win;">&url.pecl.win;</link>'>

<!ENTITY pecl.moved-ver 'This extension has been moved to the 
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> repository and is no longer bundled with 
PHP as of PHP '>

<!-- kept for BC -->
<!ENTITY note.pecl-php5 '<note><simpara>
This extension has been removed as of PHP 5 and moved to the
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pecl;">PECL</link> repository.
</simpara></note>'>

<!-- Common pieces for reference part END -->


<!ENTITY windows.builtin '<simpara>The Windows version of PHP has built-in
support for this extension. You do not need to load any additional
extensions in order to use these functions.</simpara>'>

<!-- These are here as helpers for manual consistency and brievety-->
<!ENTITY safemode '<link linkend="ini.safe-mode">safe mode</link>'>

<!ENTITY sqlsafemode '<link linkend="ini.sql.safe-mode">SQL safe mode</link>'>

<!-- APD Notes -->
<!ENTITY apd.debug-level.description '<varlistentry><term><parameter>
debug_level</parameter></term><listitem><para>An integer which is formed by adding 
together the <literal>XXX_TRACE</literal> constants.</para><para>It is not recommended
to use <constant>MEMORY_TRACE</constant>. It is very slow and does not appear to be accurate. 
<constant>ASSIGNMENT_TRACE</constant> is not implemented yet.</para><para>To turn on all
functional traces (TIMING, FUNCTIONS, ARGS SUMMARY (like strace -c)) use the value 99</para>
</listitem></varlistentry>'>

<!-- BCMath Notes -->
<!ENTITY bc.scale.description '<varlistentry><term><parameter>
scale</parameter></term><listitem><para>This optional parameter is used to set the number
of digits after the decimal place in the result. You can also set the global default scale
for all functions by using <function>bcscale</function>.</para></listitem></varlistentry>'>

<!-- FBSQL Notes -->
<!ENTITY fbsql.link-identifier.description '<varlistentry><term><parameter>
link_identifier</parameter></term><listitem><para>A FrontBase link identifier
returned by <function>fbsql_connect</function> or 
<function>fbsql_pconnect</function>.</para><para>If optional and not specified,
the function will try to find an open link to the FrontBase server and if no
such link is found it will try to create one as if 
<function>fbsql_connect</function> was called with no arguments</para>
</listitem></varlistentry>'>

<!ENTITY fbsql.result.description '<varlistentry><term><parameter>
result</parameter></term><listitem><para>A result identifier
returned by <function>fbsql_query</function> or 
<function>fbsql_db_query</function>.</para></listitem></varlistentry>'>

<!-- GMP Notes -->
<!ENTITY gmp.return 'A GMP number <type>resource</type>.'>
<!ENTITY gmp.parameter '<para>It can be either a GMP number <type>resource</type>, or a 
numeric string given that it is possible to convert the latter to a number.</para>'>

<!-- MySQLi Notes -->
<!ENTITY mysqli.result.description '<varlistentry><term><parameter>
result</parameter></term><listitem><para>Procedural style only: A result set
identifier returned by <function>mysqli_query</function>, <function>mysqli_store_result</function>
or <function>mysqli_use_result</function>.</para></listitem></varlistentry>'>
<!ENTITY mysqli.link.description '<varlistentry><term><parameter>
link</parameter></term><listitem><para>Procedural style only: A link identifier
returned by <function>mysqli_connect</function> or <function>mysqli_init</function>
</para></listitem></varlistentry>'>
<!ENTITY mysqli.stmt.description '<varlistentry><term><parameter>
stmt</parameter></term><listitem><para>Procedural style only: A statement identifier
returned by <function>mysqli_stmt_init</function>.</para></listitem></varlistentry>'>


<!-- Notes for SAPI/Apache -->
<!ENTITY note.apache.nsapi-module '<note><para>As of PHP 4.3.3 you can use this function with the
<link linkend="ref.nsapi">NSAPI server module</link> in Netscape/iPlanet/SunONE
webservers, too.</para></note>'>

<!ENTITY apache.req.module '<simpara>This function is only supported when PHP 
is installed as an Apache module.</simpara>'>

<!-- SimpleXML Notes -->
<!ENTITY simplexml.iteration '<note><simpara>SimpleXML has made a rule of adding
iterative properties to most methods. They cannot be viewed using <function>var_dump</function>
or anything else which can examine objects.</simpara></note>'>

<!-- SQLite Notes -->
<!ENTITY sqlite.case-fold '<para>The column names returned by
<constant>SQLITE_ASSOC</constant> and <constant>SQLITE_BOTH</constant> will be
case-folded according to the value of the
<link linkend="ini.sqlite.assoc-case">sqlite.assoc_case</link> configuration
option.</para>'>

<!ENTITY sqlite.decode-bin '<para>When the <parameter>decode_binary</parameter>
parameter is set to &true; (the default), PHP will decode the binary encoding
it applied to the data if it was encoded using the
<function>sqlite_escape_string</function>.  You should normally leave this
value at its default, unless you are interoperating with databases created by
other sqlite capable applications.</para>'>

<!ENTITY sqlite.no-unbuffered '<note><para>This function cannot be used with 
unbuffered result handles.</para></note>'>

<!ENTITY sqlite.param-compat '<note><simpara>Two alternative syntaxes are
supported for compatibility with other database extensions (such as MySQL).
The preferred form is the first, where the <parameter>dbhandle</parameter>
parameter is the first parameter to the function.</simpara></note>'>

<!ENTITY sqlite.result-type '<para>The optional <parameter>result_type</parameter>
parameter accepts a constant and determines how the returned array will be
indexed. Using <constant>SQLITE_ASSOC</constant> will return only associative
indices (named fields) while <constant>SQLITE_NUM</constant> will return
only numerical indices (ordinal field numbers). <constant>SQLITE_BOTH</constant>
will return both associative and numerical indices.
<constant>SQLITE_BOTH</constant> is the default for this function.</para>'>

<!-- Database Notes -->
<!ENTITY database.field-case '<note><simpara>Field names returned by this function
are <emphasis>case-sensitive</emphasis>.</simpara></note>'>

<!ENTITY database.fetch-null '<note><simpara>This function sets NULL fields to
the PHP &null; value.</simpara></note>'>

<!-- MSQL Notes -->
<!-- The msql.*.description entities are used in the parameters refsect1 -->
<!ENTITY msql.linkid.description '<varlistentry><term><parameter>
link_identifier</parameter></term><listitem><para>The mSQL connection.
If not specified, the last link opened by <function>msql_connect</function>
is assumed. If no such link is found, the function will try to establish a
link as if <function>msql_connect</function> was called, and use it.
</para></listitem></varlistentry>'>

<!ENTITY msql.result.description '<varlistentry><term><parameter>
result</parameter></term><listitem><para>The result <type>resource</type> that
is being evaluated. This result comes from a call to 
<function>msql_query</function>.</para></listitem></varlistentry>'>

<!ENTITY msql.field-offset.req.description '<varlistentry><term><parameter>
field_offset</parameter></term><listitem><para>The numerical field offset. The 
<parameter>field_offset</parameter> starts at <literal>1</literal>.</para></listitem></varlistentry>'>


<!-- MySQL Notes -->
<!-- The mysql.*.description entities are used in the parameters refsect1 -->
<!ENTITY mysql.linkid.description '<varlistentry><term><parameter>
link_identifier</parameter></term><listitem><para>The MySQL connection. If the 
link identifier is not specified, the last link opened by 
<function>mysql_connect</function> is assumed. If no such link is found, it
will try to create one as if <function>mysql_connect</function> was called
with no arguments. If by chance no connection is found or established, an
<constant>E_WARNING</constant> level error is generated.</para></listitem>
</varlistentry>'>

<!ENTITY mysql.result.description '<varlistentry><term><parameter>
result</parameter></term><listitem><para>The result <type>resource</type> that
is being evaluated. This result comes from a call to 
<function>mysql_query</function>.</para></listitem></varlistentry>'>

<!ENTITY mysql.field-offset.req.description '<varlistentry><term><parameter>
field_offset</parameter></term><listitem><para>The numerical field offset. The 
<parameter>field_offset</parameter> starts at <literal>0</literal>. If 
<parameter>field_offset</parameter> does not exist, an error of level
<constant>E_WARNING</constant> is also issued.</para></listitem></varlistentry>'>

<!-- Sybase Notes -->
<!ENTITY sybase.ct.only '<note><simpara>This function is only available when
using the CT library interface to Sybase, and not with the DB library.
</simpara></note>'>

<!ENTITY sybase.db.only '<note><simpara>This function is only available when
using the DB library interface to Sybase, and not with the CT library.</simpara></note>'>

<!ENTITY sybase.linkid.description '<varlistentry><term><parameter>
link_identifier</parameter></term><listitem><para>The Sybase connection. If the 
link identifier is not specified, the last link opened by 
<function>sybase_connect</function> is assumed. If no such link is found, it
will try to create one as if <function>sybase_connect</function> was called
with no arguments. If no connection is found or established, an
<constant>E_WARNING</constant> level error is generated.</para></listitem>
</varlistentry>'>

<!-- CPDF Notes -->
<!ENTITY cpdf.ul '<para>The optional parameter <parameter>mode</parameter>
determines the unit length. If it is <literal>0</literal> or omitted, the
default unit as specified for the page is used. In other cases, the coordinates
are measured in postscript points, disregarding the current unit.</para>'>

<!ENTITY cpdf.mode.description '<varlistentry><term><parameter>
mode</parameter></term><listitem><para>The optional parameter <parameter>mode</parameter>
determines the unit length. If it is <literal>0</literal> or omitted, the
default unit as specified for the page is used. In other cases, the coordinates
are measured in postscript points, disregarding the current unit.</para>
</listitem></varlistentry>'>

<!ENTITY cpdf.pdf-document.description '<varlistentry><term><parameter>
pdf_document</parameter></term><listitem><para>The document handle, returned by
<function>cpdf_open</function>.</para></listitem></varlistentry>'>

<!-- Xattr entities -->
<!ENTITY xattr.namespace '<para>Extended attributes have two different namespaces: user 
and root. The user namespace is available to all users, while the root namespace
is available only to users with root privileges. xattr operates on the user
namespace  by default, but this can be changed with the
<parameter>flags</parameter> parameter.</para>'>

<!-- Notes for IPv6 -->
<!ENTITY ipv6.brackets '<note><simpara>When specifying a numerical IPv6 address
(e.g. <literal>fe80::1</literal>), you must enclose the IP in square
brackets—for example, <literal>tcp://[fe80::1]:80</literal>.</simpara></note>'>

<!ENTITY ipv6.php5 '<note><simpara>IPv6 Support was added in PHP 5.0.0.
</simpara></note>'>

<!-- Notes for tidy -->
<!ENTITY note.tidy.ze2 '<note><simpara> This function is only available with
Zend Engine 2 (PHP &gt;= 5.0.0).</simpara></note>'>

<!ENTITY note.tidy.1only '<note><simpara>This function is only available in
Tidy 1.0. It became obsolete in Tidy 2.0, and thus has been removed.
</simpara></note>'>

<!ENTITY note.tidy.2only '<note><simpara>The optional parameters
<parameter>config</parameter> and <parameter>encoding</parameter> were
added in Tidy 2.0.</simpara></note>'>

<!ENTITY tidy.conf-enc '<para>The <parameter>config</parameter> parameter
can be passed either as an array or as a string. If a string is passed,
it is interpreted as the name of the configuration file, otherwise, it is
interpreted as the options themselves. Check
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.tidy.conf;">&url.tidy.conf;</link>
for an explanation about each option.</para><para>The
<parameter>encoding</parameter> parameter sets the encoding for input/output
documents. The possible values for <parameter>encoding</parameter> are:
<literal>ascii</literal>, <literal>latin0</literal>, <literal>latin1</literal>,
<literal>raw</literal>, <literal>utf8</literal>, <literal>iso2022</literal>,
<literal>mac</literal>, <literal>win1252</literal>, <literal>ibm858</literal>,
<literal>utf16</literal>, <literal>utf16le</literal>,
<literal>utf16be</literal>, <literal>big5</literal> and
<literal>shiftjis</literal>.</para>'>

<!-- Snippets for the installation section -->
<!ENTITY warn.apache2.compat '<warning><para>We do not recommend using a
threaded MPM in production with Apache 2. Use the prefork MPM instead, or use
Apache 1. For information on why, read the related FAQ entry on using
<link linkend="faq.installation.apache2">Apache2 with a threaded MPM</link></para></warning>'>

<!ENTITY note.apache.slashes '<note><simpara>Remember that when adding
path values in the Apache configuration files on Windows, all backslashes
such as <filename>c:\directory\file.ext</filename> must be converted to
forward slashes: <filename>c:/directory/file.ext</filename>. A trailing
slash may also be necessary for directories.</simpara></note>'>

<!-- Snippets and titles for the contributors section -->
<!ENTITY Credit.Authors.and.Contributors 'Authors and Contributors'>

<!ENTITY Credit.Introduction '<para> We highlight the currently most active
people on front page of the manual, but there are many more contributors who
currently help in our work or have provided a great amount of help to the project
in the past. There are a lot of unnamed people who help out with user
notes on manual pages, which continually get included in the references, the
work of whom we are also very thankful for. All of the lists provided below are in
alphabetical order.
</para>'>

<!ENTITY Credit.Authors.and.Editors 'Authors and Editors'>

<!ENTITY Credit.Past.Authors.Text 'The following contributors should be
recognized for the impact they have made and/or continue to make by adding
content to the manual:'>

<!ENTITY Credit.Past.Editors.Text 'The following contributors have done
significant work editing the manual:'>

<!ENTITY Credit.Note.Editors.Title 'User Note Maintainers'>

<!ENTITY Credit.Note.Editors.Active 'The currently most active maintainers are:'>

<!ENTITY Credit.Note.Editors.Inactive 'These people have also put a lot of effort
into managing user notes:'>

<!ENTITY listendand ' and'>

<!-- classkit and runkit entities -->
<!ENTITY note.classkit.selfmanipulation '<note><simpara>This function cannot
be used to manipulate the currently running (or chained) method.</simpara>
</note>'>

<!ENTITY note.runkit.selfmanipulation '<note><simpara>This function cannot
be used to manipulate the currently running (or chained) method.</simpara>
</note>'>

<!ENTITY note.runkit.sandbox '<note><simpara>Sandbox support (required for
<function>runkit_lint</function>, <function>runkit_lint_file</function>,
and the <classname>Runkit_Sandbox</classname> class) is only available as of
PHP 5.1.0 or specially patched versions of PHP 5.0, and requires that thread
safety be enabled.
See the <filename>README</filename> file included in the runkit package for
more information.</simpara></note>'>

<!ENTITY note.runkit.internal-override '<note><simpara>By default, only
userspace functions may be removed, renamed, or modified.  In order to
override internal functions, you must enable the
<literal>runkit.internal_override</literal> setting in &php.ini;.</simpara>
</note>'>

<!-- SSH2 Extension -->
<!ENTITY note.ssh2.subsystem.publickey '<note><simpara>The public key subsystem
is used for managing public keys on a server to which the client is
<emphasis>already</emphasis> authenticated.  To authenticate to a remote system
using public key authentication, use the
<function>ssh2_auth_pubkey_file</function> function instead.</simpara></note>'>

<!-- HTTP -->
<!ENTITY see.http.request.options '<para>See the full list of &link.http.request.options;.</para>'>
<!ENTITY see.http.configuration.force_exit 'See the &link.http.configuration;
   <link linkend="http.configuration.force_exit">http.force_exit</link> for what "exits" means.'>

<!ENTITY link.http.configuration '<link linkend="http.configuration">INI setting</link>'>
<!ENTITY link.http.request.option '<link linkend="http.request.options">request option</link>'>
<!ENTITY link.http.request.options '<link linkend="http.request.options">request options</link>'>
<!ENTITY link.http.request.info '<link linkend="http.request.info">Request/response information</link>'>
<!ENTITY returns.http.response 'Returns the HTTP response(s) as string on
success, or &false; on failure.'>
<!ENTITY returns.http.false.orexits 'Returns &false; or <emphasis>exits</emphasis> on success'>
<!ENTITY http.request.affects 'Affects the following request method(s) only:'>
<!ENTITY http.request.affects.any 'Affects any request method.'>
<!ENTITY http.response.class.php51 'the <link linkend="class.httpresponse">
<classname>HttpResponse</classname></link> class if you are using PHP 5.1.0
and above'>
<!ENTITY http.maynotwork.SAPI 'This may not work as expected with the following SAPI(s):'>
<!ENTITY http.content.disposition 'The <literal>Content-Disposition</literal>
header is very useful if the data actually being sent came from a file or
something similar, that should be &quot;saved&quot; by the client/user (i.e. by
the browser&apos;s &quot;Save as...&quot; popup window).'>
<!ENTITY http.use.ob_start 'For use with <function>ob_start</function>.'>

<!ENTITY note.http.response.recalculate.etag.lm '<note><simpara>Previously calculated or defined <literal>ETag</literal>
   and <literal>Last-Modified</literal> will be recalculated and redefined.</simpara></note>'>
<!ENTITY note.http.throttling.yields.process '<note><simpara>Provides a basic throttling mechanism, which will yield
   the current process or thread until the entity has been completely sent.</simpara></note>'>
<!ENTITY note.http.send.API '<note><simpara>This function should be used in conjunction with
   <function>http_send_data</function>, <function>http_send_file</function> &listendand; <function>http_send_stream</function>.</simpara></note>'>
<!ENTITY note.http.send.API.mayuse '<note><simpara>This function may be used in conjunction with
   <function>http_send_data</function>, <function>http_send_file</function> &listendand; <function>http_send_stream</function>.</simpara></note>'>
<!ENTITY note.http.request.encodecookies '<note><simpara>The &link.http.request.option; <literal>encodecookies</literal> controls
   whether the cookie values should be <function>urlencode</function>d.</simpara></note>'>
<!ENTITY note.http.request.affects.any '<note><simpara>&http.request.affects.any;</simpara></note>'>
<!ENTITY note.http.ob.once '<note><simpara>This output handler can only be used once.</simpara></note>'>

<!-- XMLWriter Notes -->
<!ENTITY xmlwriter.xmlwriter.description '<varlistentry><term><parameter>
xmlwriter</parameter></term><listitem><para>Only for procedural calls. 
The XMLWriter <type>resource</type> that is being modified. This resource comes from a call to <function>xmlwriter_open_uri</function> or <function>xmlwriter_open_memory</function>.</para></listitem></varlistentry>'>

<!-- SVN notes -->
<!ENTITY svn.relativepath "<note><simpara>Relative paths will be resolved as if the current working directory was the one that contains the PHP binary. To use the calling script&apos;s working directory, use <function>realpath</function> or dirname(__FILE__).</simpara></note>">
<!ENTITY svn.referto.status 'Refer to <link linkend="svn.constants.status">status constants</link> for possible values.'>
<!ENTITY svn.referto.type 'Refer to <link linkend="svn.constants.type">type constants</link> for possible values.'>

<!-- Imagick generic return types -->
<!ENTITY imagick.return.success 'Returns &true; on success.'>
<!ENTITY imagick.imagick.throws 'Throws ImagickException on error.'>
<!ENTITY imagick.imagickdraw.throws 'Throws ImagickDrawException on error.'>
<!ENTITY imagick.imagickpixel.throws 'Throws ImagickPixelException on error.'>
<!ENTITY imagick.imagickpixeliterator.throws 'Throws ImagickPixelIteratorException on error.'>

<!ENTITY note.openssl.cnf '<note xmlns="http://docbook.org/ns/docbook">
 <simpara>
  You need to have a valid <filename>openssl.cnf</filename> installed for
  this function to operate correctly.
  See the notes under <link linkend="openssl.installation">the installation
  section</link> for more information.
 </simpara>
</note>'>
<!ENTITY note.openssl.param-notext '<para xmlns="http://docbook.org/ns/docbook">
 The optional parameter <parameter>notext</parameter> affects
 the verbosity of the output; if it is &false;, then additional human-readable
 information is included in the output. The default value of
 <parameter>notext</parameter> is &true;.
</para>'>

<!-- COM/Dotnet -->
<!ENTITY com.variant-arith '<note xmlns="http://docbook.org/ns/docbook">
<para>
 As with all the variant arithmetic functions, the parameters for this function
 can be either a PHP native type (integer, string, floating point, boolean or
 &null;), or an instance of a COM, VARIANT or DOTNET class.  PHP native types
 will be converted to variants using the same rules as found in the constructor
 for the <xref linkend="class.variant"/> class.  COM and DOTNET objects
 will have the value of their default property taken and used as the variant value.
</para>
<para>
 The variant arithmetic functions are wrappers around the similarly named
 functions in the COM library; for more information on these functions, consult
 the MSDN library.  The PHP functions are named slightly differently; for example
 <function>variant_add</function> in PHP corresponds to <literal>VarAdd()
 </literal> in the MSDN documentation.
</para>
</note>
'>
<!ENTITY com.use-oo-instead '<note xmlns="http://docbook.org/ns/docbook">
 <simpara>
  This function does not exist in PHP 5; instead, you should use the regular
  and more natural OO syntax to access properties or call methods.
 </simpara>
</note>
'>

<!-- phar -->
<!ENTITY phar.write '<note xmlns="http://docbook.org/ns/docbook"><para>This
method requires the &php.ini; setting <literal>phar.readonly</literal> to be
set to <literal>0</literal> in order to work for <classname>Phar</classname>
objects.  Otherwise, a <classname>PharException</classname> will be thrown.</para></note>'>