Add warning to Channel.recv_exit_status re: call order.

Closes #448...kinda

1 files changed, 11 insertions, 0 deletions

diff --git a/paramiko/channel.py b/paramiko/channel.py
index b6803f63..8a1c0f87 100644
--- a/paramiko/channel.py
+++ b/paramiko/channel.py
@@ -301,6 +301,17 @@ class Channel (ClosingContextManager):
         it does, or until the channel is closed.  If no exit status is
         provided by the server, -1 is returned.
 
+        .. warning::
+            In some situations, receiving remote output larger than the current
+            `.Transport` or session's ``window_size`` (e.g. that set by the
+            ``default_window_size`` kwarg for `.Transport.__init__`) will cause
+            `.recv_exit_status` to hang indefinitely if it is called prior to a
+            sufficiently large `.read` (or if there are no threads calling
+            `.read` in the background).
+
+            In these cases, ensuring that `.recv_exit_status` is called *after*
+            `.read` (or, again, using threads) can avoid the hang.
+
         :return: the exit code (as an `int`) of the process on the server.
 
         .. versionadded:: 1.2