From b8234dab10a5ff8b0e5cab80967a3c59d5f26ca8 Mon Sep 17 00:00:00 2001
From: Sara Golemon <pollita@php.net>
Date: Thu, 30 Dec 2004 19:27:07 +0000
Subject: [PATCH] Additional Documentation for: ssh2_sftp_mkdir()
 ssh2_sftp_rmdir() ssh2_sftp_readlink() ssh2_sftp_symlink()
 ssh2_sftp_realpath()

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@176090 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/ssh2/functions/ssh2-sftp-mkdir.xml  | 35 ++++++++++++++++---
 .../ssh2/functions/ssh2-sftp-readlink.xml     | 28 +++++++++++++--
 .../ssh2/functions/ssh2-sftp-realpath.xml     | 29 +++++++++++++--
 reference/ssh2/functions/ssh2-sftp-rmdir.xml  | 35 ++++++++++++++++---
 .../ssh2/functions/ssh2-sftp-symlink.xml      | 30 +++++++++++++---
 5 files changed, 138 insertions(+), 19 deletions(-)

diff --git a/reference/ssh2/functions/ssh2-sftp-mkdir.xml b/reference/ssh2/functions/ssh2-sftp-mkdir.xml
index ef8f2c19fb..ffc0b6783d 100644
--- a/reference/ssh2/functions/ssh2-sftp-mkdir.xml
+++ b/reference/ssh2/functions/ssh2-sftp-mkdir.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
   <refentry id="function.ssh2-sftp-mkdir">
    <refnamediv>
@@ -18,9 +18,36 @@
      <methodparam choice="opt"><type>bool</type><parameter>recursive</parameter></methodparam>
     </methodsynopsis>
 
-    <para>
-     Creates a directory on the remote file server
-    </para>
+    <simpara>
+     Creates a directory on the remote file server with permissions set to
+     <parameter>mode</parameter>.  If <parameter>recursive</parameter> is &true;
+     any parent directories required for <parameter>dirname</parameter> will
+     be automatically created as well.  
+     This function is similar to using <function>mkdir</function> with the
+     <link linkend="wrappers.ssh2">ssh2.sftp://</link> wrapper.
+    </simpara>
+
+    <example>
+     <title>Creating a directory on a remote server</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$connection = ssh2_connet('shell.example.com', 22);
+ssh2_auth_password($connection, 'username', 'password');
+$sftp = ssh2_sftp($connection);
+
+ssh2_sftp_mkdir($sftp, '/home/username/newdir');
+/* Or:  mkdir("ssh2.sftp://$sftp/home/username/newdir"); */
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <simpara>
+     See Also:
+     <function>mkdir</function>, and
+     <function>ssh2_sftp_rmdir</function>
+    </simpara>
 
    </refsect1>
   </refentry>
diff --git a/reference/ssh2/functions/ssh2-sftp-readlink.xml b/reference/ssh2/functions/ssh2-sftp-readlink.xml
index 418aeca2ed..e5cdb6b467 100644
--- a/reference/ssh2/functions/ssh2-sftp-readlink.xml
+++ b/reference/ssh2/functions/ssh2-sftp-readlink.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-readlink">
    <refnamediv>
@@ -16,9 +16,31 @@
      <methodparam><type>string</type><parameter>link</parameter></methodparam>
     </methodsynopsis>
 
-    <para>
+    <simpara>
      Returns the target of a symbolic link.
-    </para>
+    </simpara>
+
+    <example>
+     <title>Reading a symbolic link</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$connection = ssh2_connect('shell.example.com', 22);
+ssh2_auth_password($connection, 'username', 'password');
+$sftp = ssh2_sftp($connection);
+
+$target = ssh2_sftp_readlink($sftp, '/tmp/mysql.sock');
+/* $target is now (e.g.): '/var/run/mysql.sock' */
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <simpara>
+     See Also:
+     <function>readlink</function>, and
+     <function>ssh2_sftp_symlink</function>
+    </simpara>
 
    </refsect1>
   </refentry>
diff --git a/reference/ssh2/functions/ssh2-sftp-realpath.xml b/reference/ssh2/functions/ssh2-sftp-realpath.xml
index 514e8c7d29..362070b034 100644
--- a/reference/ssh2/functions/ssh2-sftp-realpath.xml
+++ b/reference/ssh2/functions/ssh2-sftp-realpath.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-realpath">
    <refnamediv>
@@ -16,10 +16,33 @@
      <methodparam><type>string</type><parameter>filename</parameter></methodparam>
     </methodsynopsis>
 
-    <para>
+    <simpara>
      Translates <parameter>filename</parameter> into the effective real path
      on the remote filesystem.
-    </para>
+    </simpara>
+
+    <example>
+     <title>Resolving a pathname</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$connection = ssh2_connect('shell.example.com', 22);
+ssh2_auth_password($connection, 'username', 'password');
+$sftp = ssh2_sftp($connection);
+
+$realpath = ssh2_sftp_realpath($sftp, '/home/username/../../../..//./usr/../etc/passwd');
+/* $realpath is now: '/etc/passwd' */
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <simpara>
+     See Also:
+     <function>realpath</function>, and
+     <function>ssh2_sftp_symlink</function>
+     <function>ssh2_sftp_readlink</function>
+    </simpara>
 
    </refsect1>
   </refentry>
diff --git a/reference/ssh2/functions/ssh2-sftp-rmdir.xml b/reference/ssh2/functions/ssh2-sftp-rmdir.xml
index 0984cf3504..3e8c8aafb9 100644
--- a/reference/ssh2/functions/ssh2-sftp-rmdir.xml
+++ b/reference/ssh2/functions/ssh2-sftp-rmdir.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-rmdir">
    <refnamediv>
@@ -13,12 +13,37 @@
     <methodsynopsis>
      <type>bool</type><methodname>ssh2_sftp_rmdir</methodname>
      <methodparam><type>resource</type><parameter>sftp</parameter></methodparam>
-     <methodparam><type>string</type><parameter>filename</parameter></methodparam>
+     <methodparam><type>string</type><parameter>dirname</parameter></methodparam>
     </methodsynopsis>
 
-    <para>
-     Removes a directory from the remote server's filesystem
-    </para>
+    <simpara>
+     Removes a directory from the remote file server.
+     This function is similar to using <function>rmdir</function> with the
+     <link linkend="wrappers.ssh2">ssh2.sftp://</link> wrapper.
+    </simpara>
+
+    <example>
+     <title>Creating a directory on a remote server</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$connection = ssh2_connet('shell.example.com', 22);
+ssh2_auth_password($connection, 'username', 'password');
+$sftp = ssh2_sftp($connection);
+
+ssh2_sftp_rmdir($sftp, '/home/username/deltodel');
+/* Or:  rmdir("ssh2.sftp://$sftp/home/username/dirtodel"); */
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <simpara>
+     See Also:
+     <function>rmdir</function>, and
+     <function>ssh2_sftp_mkdir</function>
+    </simpara>
+
 
    </refsect1>
   </refentry>
diff --git a/reference/ssh2/functions/ssh2-sftp-symlink.xml b/reference/ssh2/functions/ssh2-sftp-symlink.xml
index 06d3e31155..c6ce65bdd7 100644
--- a/reference/ssh2/functions/ssh2-sftp-symlink.xml
+++ b/reference/ssh2/functions/ssh2-sftp-symlink.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-symlink">
    <refnamediv>
@@ -17,9 +17,31 @@
      <methodparam><type>string</type><parameter>link</parameter></methodparam>
     </methodsynopsis>
 
-    <para>
-     Creates a symbolic link on the remote filesystem
-    </para>
+    <simpara>
+     Creates a symbolic link named <parameter>link</parameter> on the remote filesystem
+     pointing to <parameter>target</parameter>.
+    </simpara>
+
+    <example>
+     <title>Creating a symbolic link</title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+$connection = ssh2_connect('shell.example.com', 22);
+ssh2_auth_password($connection, 'username', 'password');
+$sftp = ssh2_sftp($connection);
+
+ssh2_sftp_symlink($sftp, '/var/run/mysql.sock', '/tmp/mysql.sock');
+?>
+]]>
+     </programlisting>
+    </example>
+
+    <simpara>
+     See Also:
+     <function>symlink</function>, and
+     <function>ssh2_sftp_readlink</function>
+    </simpara>
 
    </refsect1>
   </refentry>