From: Jacob Nevins <jacobn@chiark.greenend.org.uk>
Date: Thu, 22 Oct 2015 00:48:35 +0000 (+0100)
Subject: Update docs/usage for 'plink -shareexists'.
X-Git-Tag: 0.68~339
X-Git-Url: https://asedeno.scripts.mit.edu/gitweb/?a=commitdiff_plain;h=48eafd66aa274c32fc8169a0d36619663905c210;p=PuTTY.git

Update docs/usage for 'plink -shareexists'.
---

diff --git a/doc/config.but b/doc/config.but
index 82656cd2..5107858c 100644
--- a/doc/config.but
+++ b/doc/config.but
@@ -2353,6 +2353,9 @@ with sharing enabled, then it can act as a downstream and use an
 existing SSH connection set up by an instance of GUI PuTTY. The one
 special case is that PSCP and PSFTP will \e{never} act as upstreams.
 
+It is possible to test programmatically for the existence of a live
+upstream using Plink. See \k{plink-option-shareexists}.
+
 \H{config-ssh-kex} The Kex panel
 
 The Kex panel (short for \q{\i{key exchange}}) allows you to configure
diff --git a/doc/index.but b/doc/index.but
index 77b3493a..204430ce 100644
--- a/doc/index.but
+++ b/doc/index.but
@@ -766,6 +766,7 @@ saved sessions from
 
 \IM{-batch-plink} \c{-batch} Plink command-line option
 \IM{-s-plink} \c{-s} Plink command-line option
+\IM{-shareexists-plink} \c{-shareexists} Plink command-line option
 
 \IM{subsystem} subsystem, SSH
 \IM{subsystem} SSH subsystem
diff --git a/doc/plink.but b/doc/plink.but
index c45312c5..553639e6 100644
--- a/doc/plink.but
+++ b/doc/plink.but
@@ -41,7 +41,7 @@ use Plink:
 
 \c Z:\sysosd>plink
 \c Plink: command-line connection utility
-\c Release 0.65
+\c Release 0.XX
 \c Usage: plink [options] [user@]host [command]
 \c        ("host" can also be a PuTTY saved session name)
 \c Options:
@@ -80,6 +80,8 @@ use Plink:
 \c   -N        don't start a shell/command (SSH-2 only)
 \c   -nc host:port
 \c             open tunnel in place of session (SSH-2 only)
+\c   -shareexists
+\c             test whether a connection-sharing upstream exists
 
 Once this works, you are ready to use Plink.
 
@@ -230,6 +232,27 @@ line.
 
 (This option is only meaningful with the SSH-2 protocol.)
 
+\S2{plink-option-shareexists} \I{-shareexists-plink}\c{-shareexists}:
+test for connection-sharing upstream
+
+This option does not make a new connection; instead it allows testing
+for the presence of an existing connection that can be shared.
+(See \k{config-ssh-sharing} for more information about SSH connection
+sharing.)
+
+A Plink invocation of the form:
+
+\c plink -shareexists <session>
+\e                    iiiiiiiii
+
+will test whether there is currently a viable \q{upstream} for the
+session in question, which can be specified using any syntax you'd
+normally use with Plink to make an actual connection (a host/port
+number, a bare saved session name, \c{-load}, etc). It returns a
+zero exit status if a usable \q{upstream} exists, nonzero otherwise.
+
+(This option is only meaningful with the SSH-2 protocol.)
+
 \H{plink-batch} Using Plink in \i{batch files} and \i{scripts}
 
 Once you have set up Plink to be able to log in to a remote server
diff --git a/unix/uxplink.c b/unix/uxplink.c
index ad122e9d..8351a6ea 100644
--- a/unix/uxplink.c
+++ b/unix/uxplink.c
@@ -581,6 +581,8 @@ static void usage(void)
     printf("  -N        don't start a shell/command (SSH-2 only)\n");
     printf("  -nc host:port\n");
     printf("            open tunnel in place of session (SSH-2 only)\n");
+    printf("  -shareexists\n");
+    printf("            test whether a connection-sharing upstream exists\n");
     exit(1);
 }
 
diff --git a/windows/winplink.c b/windows/winplink.c
index 8ffa4651..78311b59 100644
--- a/windows/winplink.c
+++ b/windows/winplink.c
@@ -212,6 +212,8 @@ static void usage(void)
     printf("  -N        don't start a shell/command (SSH-2 only)\n");
     printf("  -nc host:port\n");
     printf("            open tunnel in place of session (SSH-2 only)\n");
+    printf("  -shareexists\n");
+    printf("            test whether a connection-sharing upstream exists\n");
     exit(1);
 }