php-doc-en/functions/ftp.xml
Hartmut Holzgraefe 034533bf75 added skeleton for missing function
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@65156 c90b9560-bf6c-de11-be94-00142212c4b1
2001-12-15 14:37:18 +00:00

640 lines
20 KiB
XML

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.30 $ -->
<reference id="ref.ftp">
<title>FTP functions</title>
<titleabbrev>FTP</titleabbrev>
<partintro>
<para>
The functions in this extension implement client access to file
servers speaking the File Transfer Protocol FTP as defined in
&spec.ftp;.
</para>
<para>
The following constants are defined when using the FTP module:
<constant>FTP_ASCII</constant> and <constant>FTP_BINARY</constant>.
</para>
<para>
In order to use FTP functions with your PHP configuration, you should
add the <link linkend="install.configure.enable-ftp">
<option>--enable-ftp</option></link> option when installing PHP 4,
and <link linkend="install.configure.with-ftp">
<option>--with-ftp</option></link> when using PHP 3.
</para>
<para>
<example>
<title><function>ftp</function> example</title>
<programlisting>
<![CDATA[
<?php
// set up basic connection
$conn_id = ftp_connect("$ftp_server");
// login with username and password
$login_result = ftp_login($conn_id, "$ftp_user_name", "$ftp_user_pass");
// check connection
if ((!$conn_id) || (!$login_result)) {
echo "Ftp connection has failed!";
echo "Attempted to connect to $ftp_server for user $ftp_user_name";
die;
} else {
echo "Connected to $ftp_server, for user $ftp_user_name";
}
// upload the file
$upload = ftp_put($conn_id, "$destination_file", "$source_file", FTP_BINARY);
// check upload status
if (!$upload) {
echo "Ftp upload has failed!";
} else {
echo "Uploaded $source_file to $ftp_server as $destination_file";
}
// close the FTP stream
ftp_quit($conn_id);
?>
]]>
</programlisting>
</example>
</para>
</partintro>
<refentry id="function.ftp-connect">
<refnamediv>
<refname>ftp_connect</refname>
<refpurpose>Opens up an FTP connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_connect</function></funcdef>
<paramdef>string <parameter>host</parameter></paramdef>
<paramdef>int <parameter><optional>port</optional>
</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns a FTP stream on success, &false; on error.
</para>
<para>
<function>ftp_connect</function> opens up a FTP connection to the
specified <parameter>host</parameter>. The <parameter>port</parameter>
parameter specifies an alternate port to connect to. If it is
omitted or zero, then the default FTP port, 21, will be used.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-login">
<refnamediv>
<refname>ftp_login</refname>
<refpurpose>Logs in an FTP connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_login</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>username</parameter></paramdef>
<paramdef>string <parameter>password</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Logs in the given FTP stream.
</para>
<para>
Returns &true; on success, &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-pwd">
<refnamediv>
<refname>ftp_pwd</refname>
<refpurpose>Returns the current directory name</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>ftp_pwd</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns the current directory, or &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-cdup">
<refnamediv>
<refname>ftp_cdup</refname>
<refpurpose>Changes to the parent directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_cdup</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Changes to the parent directory.
</para>
<para>
Returns &true; on success, &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-chdir">
<refnamediv>
<refname>ftp_chdir</refname>
<refpurpose>Changes directories on a FTP server</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_chdir</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>directory</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Changes to the specified <parameter>directory</parameter>.
</para>
<para>
Returns &true; on success, &false; on error.</para>
</refsect1>
</refentry>
<refentry id="function.ftp-mkdir">
<refnamediv>
<refname>ftp_mkdir</refname>
<refpurpose>Creates a directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>ftp_mkdir</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>directory</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Creates the specified <parameter>directory</parameter>.
</para>
<para>
Returns the newly created directory name on success, &false; on error.</para>
</refsect1>
</refentry>
<refentry id="function.ftp-rmdir">
<refnamediv>
<refname>ftp_rmdir</refname>
<refpurpose>Removes a directory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_rmdir</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>directory</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Removes the specified <parameter>directory</parameter>.
</para>
<para>
Returns &true; on success, &false; on error.</para>
</refsect1>
</refentry>
<refentry id="function.ftp-nlist">
<refnamediv>
<refname>ftp_nlist</refname>
<refpurpose>Returns a list of files in the given directory.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>ftp_nlist</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>directory</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns an array of filenames on success, &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-rawlist">
<refnamediv>
<refname>ftp_rawlist</refname>
<refpurpose>
Returns a detailed list of files in the given directory.
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>ftp_rawlist</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>directory</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ftp_rawlist</function> executes the FTP LIST command,
and returns the result as an array. Each array element corresponds
to one line of text. The output is not parsed in any way. The
system type identifier returned by <function>ftp_systype</function>
can be used to determine how the results should be interpreted.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-systype">
<refnamediv>
<refname>ftp_systype</refname>
<refpurpose>
Returns the system type identifier of the remote FTP server.
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>ftp_systype</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Returns the remote system type, or &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-pasv">
<refnamediv>
<refname>ftp_pasv</refname>
<refpurpose>Turns passive mode on or off.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_pasv</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>int <parameter>pasv</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ftp_pasv</function> turns on passive mode if the
<parameter>pasv</parameter> parameter is &true; (it turns off
passive mode if <parameter>pasv</parameter> is &false;.) In
passive mode, data connections are initiated by the client,
rather than by the server.
</para>
<para>
Returns &true; on success, &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-get">
<refnamediv>
<refname>ftp_get</refname>
<refpurpose>Downloads a file from the FTP server.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_get</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>local_file</parameter></paramdef>
<paramdef>string <parameter>remote_file</parameter></paramdef>
<paramdef>int <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ftp_get</function> retrieves <parameter>remote_file</parameter>
from the FTP server, and saves it to <parameter>local_file</parameter>
locally. The transfer <parameter>mode</parameter> specified must
be either <constant>FTP_ASCII</constant> or
<constant>FTP_BINARY</constant>.
</para>
<para>
Returns &true; on success, &false; on error.
</para>
<para>
See also <function>ftp_fget</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-fget">
<refnamediv>
<refname>ftp_fget</refname>
<refpurpose>Downloads a file from the FTP server and saves to an
open file.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_fget</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>int <parameter>fp</parameter></paramdef>
<paramdef>string <parameter>remote_file</parameter></paramdef>
<paramdef>int <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ftp_fget</function> retrieves <parameter>remote_file</parameter>
from the FTP server, and writes it to the given file pointer,
<parameter>fp</parameter>. The transfer <parameter>mode</parameter>
specified must be either <constant>FTP_ASCII</constant> or
<constant>FTP_BINARY</constant>.
</para>
<para>
Returns &true; on success, &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-put">
<refnamediv>
<refname>ftp_put</refname>
<refpurpose>Uploads a file to the FTP server.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_put</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>remote_file</parameter></paramdef>
<paramdef>string <parameter>local_file</parameter></paramdef>
<paramdef>int <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ftp_put</function> stores <parameter>local_file</parameter>
on the FTP server, as <parameter>remote_file</parameter>. The transfer
<parameter>mode</parameter> specified must be either
<constant>FTP_ASCII</constant> or <constant>FTP_BINARY</constant>.
</para>
<para>
Returns &true; on success, &false; on error.
</para>
<para>
<example>
<title><function>ftp_put</function> example</title>
<programlisting role="php">
<![CDATA[
$upload = ftp_put ($conn_id, "$destination_file", "$source_file", FTP_ASCII);
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-fput">
<refnamediv>
<refname>ftp_fput</refname>
<refpurpose>Uploads from an open file to the FTP server.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_fput</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>remote_file</parameter></paramdef>
<paramdef>int <parameter>fp</parameter></paramdef>
<paramdef>int <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ftp_fput</function> uploads the data from the file pointer
<parameter>fp</parameter> until end of file. The results are stored
in <parameter>remote_file</parameter> on the FTP server. The transfer
<parameter>mode</parameter> specified must be either
<constant>FTP_ASCII</constant> or <constant>FTP_BINARY</constant>
</para>
<para>
Returns &true; on success, &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-size">
<refnamediv>
<refname>ftp_size</refname>
<refpurpose>Returns the size of the given file.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_size</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>remote_file</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ftp_size</function> returns the size of a file. If an
error occurs, of if the file does not exist, -1 is returned. Not
all servers support this feature.</para>
<para>
Returns the file size on success, or -1 on error.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-mdtm">
<refnamediv>
<refname>ftp_mdtm</refname>
<refpurpose>Returns the last modified time of the given file.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_mdtm</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>remote_file</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ftp_mdtm</function> checks the last-modified time for a
file, and returns it as a UNIX timestamp. If an error occurs, or
the file does not exist, -1 is returned. Note that not all servers
support this feature.
</para>
<para>
Returns a UNIX timestamp on success, or -1 on error.
</para>
<note>
<para>
<function>ftp_mdtm</function> does not work with directories.
</para>
</note>
</refsect1>
</refentry>
<refentry id="function.ftp-rename">
<refnamediv>
<refname>ftp_rename</refname>
<refpurpose>Renames a file on the ftp server.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>boolean <function>ftp_rename</function></funcdef>
<paramdef>resource <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>from</parameter></paramdef>
<paramdef>string <parameter>to</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ftp_rename</function> renames the file or directory
currently named <parameter>from</parameter> to the new name
<parameter>to</parameter>, on the FTP stream <parameter>ftp_stream</parameter>.
</para>
<para>
Returns &true; on success, &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-delete">
<refnamediv>
<refname>ftp_delete</refname>
<refpurpose>Deletes a file on the ftp server.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_delete</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>path</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ftp_delete</function> deletes the file specified by
<parameter>path</parameter> from the FTP server.
</para>
<para>
Returns &true; on success, &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-site">
<refnamediv>
<refname>ftp_site</refname>
<refpurpose>Sends a SITE command to the server.</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_site</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
<paramdef>string <parameter>cmd</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ftp_site</function> sends the command specified by
<parameter>cmd</parameter> to the FTP server. SITE commands
are not standardized, and vary from server to server. They are
useful for handling such things as file permissions and group
membership.
</para>
<para>
Returns &true; on success, &false; on error.
</para>
</refsect1>
</refentry>
<refentry id="function.ftp-quit">
<refnamediv>
<refname>ftp_quit</refname>
<refpurpose>Closes an FTP connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_quit</function></funcdef>
<paramdef>int <parameter>ftp_stream</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>ftp_quit</function> closes <parameter>ftp_stream</parameter>.
</para>
</refsect1>
</refentry>
<refentry id='function.ftp-exec'>
<refnamediv>
<refname>ftp_exec</refname>
<refpurpose>
Request execution of a program on the ftp server */
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ftp_exec</function></funcdef>
<paramdef>int <parameter>stream</parameter></paramdef>
<paramdef>string <parameter>command</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
&warn.undocumented.func;
</para>
</refsect1>
</refentry>
</reference>
<!-- 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:"../../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=xml
vi: ts=1 sw=1
-->