From 025d1bab3cb0cd7081cf5fa4687e39f12e790dc9 Mon Sep 17 00:00:00 2001
From: Sara Golemon <pollita@php.net>
Date: Thu, 30 Dec 2004 05:35:30 +0000
Subject: [PATCH] Additional Documentation: ssh2_sftp(), ssh2_sftp_stat(),
 ssh2_sftp_lstat()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@175989 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/ssh2/functions/ssh2-sftp-lstat.xml | 41 +++++++++++++++++--
 reference/ssh2/functions/ssh2-sftp-stat.xml  | 42 +++++++++++++++++---
 reference/ssh2/functions/ssh2-sftp.xml       | 36 +++++++++++++++--
 3 files changed, 106 insertions(+), 13 deletions(-)

diff --git a/reference/ssh2/functions/ssh2-sftp-lstat.xml b/reference/ssh2/functions/ssh2-sftp-lstat.xml
index 49ca6bac66..7241660ed2 100644
--- a/reference/ssh2/functions/ssh2-sftp-lstat.xml
+++ b/reference/ssh2/functions/ssh2-sftp-lstat.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
   <refentry id="function.ssh2-sftp-lstat">
    <refnamediv>
@@ -16,10 +16,43 @@
      <methodparam><type>string</type><parameter>path</parameter></methodparam>
     </methodsynopsis>
 
-    <para>
+    <simpara>
      Stats a symbolic link on the remote filesystem <emphasis>without</emphasis>
-     following the link.
-    </para>
+     following the link.  This function is similar to using the
+     <function>lstat</function> function with the
+     <link linkend="wrappers.ssh2">ssh2.sftp://</link> wrapper in PHP5
+     and returns the same values.  See the documentation for
+     <function>stat</function> for details on the values which may be returned.
+    </simpara>
+
+    <example>
+     <title>Stating a symbolic link via SFTP</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$connection = ssh2_connect('shell.example.com', 22);
+ssh2_auth_password($connection, 'username', 'password');
+
+$sftp = ssh2_sftp($connection);
+$statinfo = ssh2_lstat($sftp, '/path/to/symlink');
+
+$filesize = $statinfo['size'];
+$group = $statinfo['gid'];
+$owner = $statinfo['uid'];
+$atime = $statinfo['atime'];
+$mtime = $statinfo['mtime'];
+$mode = $statinfo['mode'];
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <simpara>
+     See Also:
+     <function>ssh2_sftp_stat</function>,
+     <function>lstat</function>, and
+     <function>stat</function>
+    </simpara>
 
    </refsect1>
   </refentry>
diff --git a/reference/ssh2/functions/ssh2-sftp-stat.xml b/reference/ssh2/functions/ssh2-sftp-stat.xml
index 95178e0684..eb56599ff4 100644
--- a/reference/ssh2/functions/ssh2-sftp-stat.xml
+++ b/reference/ssh2/functions/ssh2-sftp-stat.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
   <refentry id="function.ssh2-sftp-stat">
    <refnamediv>
@@ -16,10 +16,42 @@
      <methodparam><type>string</type><parameter>path</parameter></methodparam>
     </methodsynopsis>
 
-    <para>
-     Stats a remote file.  If the file is a symbolic link, it follows the link
-     and stats its target.
-    </para>
+    <simpara>
+     Stats a file on the remote filesystem following any symbolic links.
+     This function is similar to using the <function>stat</function> function
+     with the <link linkend="wrappers.ssh2">ssh2.sftp://</link> wrapper in PHP5
+     and returns the same values.  See the documentation for
+     <function>stat</function> for details on the values which may be returned.
+    </simpara>
+
+    <example>
+     <title>Stating a file via SFTP</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$connection = ssh2_connect('shell.example.com', 22);
+ssh2_auth_password($connection, 'username', 'password');
+
+$sftp = ssh2_sftp($connection);
+$statinfo = ssh2_stat($sftp, '/path/to/symlink');
+
+$filesize = $statinfo['size'];
+$group = $statinfo['gid'];
+$owner = $statinfo['uid'];
+$atime = $statinfo['atime'];
+$mtime = $statinfo['mtime'];
+$mode = $statinfo['mode'];
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <simpara>
+     See Also:
+     <function>ssh2_sftp_lstat</function>,
+     <function>lstat</function>, and
+     <function>stat</function>
+    </simpara>
 
    </refsect1>
   </refentry>
diff --git a/reference/ssh2/functions/ssh2-sftp.xml b/reference/ssh2/functions/ssh2-sftp.xml
index 90e6703faa..da41385078 100644
--- a/reference/ssh2/functions/ssh2-sftp.xml
+++ b/reference/ssh2/functions/ssh2-sftp.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
   <refentry id="function.ssh2-sftp">
    <refnamediv>
@@ -15,9 +15,37 @@
      <methodparam><type>resource</type><parameter>session</parameter></methodparam>
     </methodsynopsis>
 
-    <para>
-     Request the SFTP subsystem from an already connected SSH2 server
-    </para>
+    <simpara>
+     Request the SFTP subsystem from an already connected SSH2 server.
+    </simpara>
+
+    <simpara>
+     This method returns an <literal>SSH2 SFTP</literal> resource for use with
+     all other ssh2_sftp_*() methods and the
+     <link linkend="wrappers.ssh2">ssh2.sftp://</link> fopen wrapper.
+    </simpara>
+
+    <example>
+     <title>Opening a file via SFTP</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$connection = ssh2_connect('shell.example.com', 22);
+ssh2_auth_password($connection, 'username', 'password');
+
+$sftp = ssh2_sftp($connection);
+
+$stream = fopen("ssh2.sftp://$sftp/path/to/file", 'r');
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <simpara>
+     See Also:
+     <function>ssh2_scp_send</function>, and
+     <function>ssh2_scp_recv</function>
+    </simpara>
 
    </refsect1>
   </refentry>