From 176c6caf4ea7918e1698438634b237fab8456471 Mon Sep 17 00:00:00 2001 From: "Jeremy T. Bouse" Date: Fri, 27 Nov 2009 16:20:09 -0500 Subject: Imported Upstream version 1.5.2 --- docs/private/paramiko.Channel-class.html | 1329 ++++++++++++++++++++++++++++++ 1 file changed, 1329 insertions(+) create mode 100644 docs/private/paramiko.Channel-class.html (limited to 'docs/private/paramiko.Channel-class.html') diff --git a/docs/private/paramiko.Channel-class.html b/docs/private/paramiko.Channel-class.html new file mode 100644 index 0000000..83ac46e --- /dev/null +++ b/docs/private/paramiko.Channel-class.html @@ -0,0 +1,1329 @@ + + + + + paramiko.Channel + + + + + + + + + + + + + +
   Home      Trees      Index      Help   
+ + + + +
+ + Package paramiko :: + Class Channel +
+ 		+ + +
[show private | hide private]
[frames | no frames]
+ + +

Type Channel

+ +
+object --+
+         |
+        Channel
+

+ +
+ +

A secure tunnel across an SSH Transport. A Channel is meant to behave +like a socket, and has an API that should be indistinguishable from the +python socket API.

+Because SSH2 has a windowing kind of flow control, if you stop reading +data from a Channel and its buffer fills up, the server will be unable to +send you any more data until you read some of it. (This won't affect +other channels on the same transport -- all channels on a single +transport are flow-controlled independently.) Similarly, if the server +isn't reading data you send, calls to send may block, unless you set a timeout. +This is exactly like a normal network socket, so it shouldn't be too +surprising. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Method Summary
 __init__(self, + chanid) +
+Create a new channel.
 __del__(self) +
str +__repr__(self) +
+Return a string representation of this object, for debugging.
 close(self) +
+Close the channel.
bool +exec_command(self, + command) +
+Execute a command on the server.
int +fileno(self) +
+Returns an OS-level file descriptor which can be used for polling, but +but not for reading or writing).
int +get_id(self) +
+Return the ID # for this channel.
str +get_name(self) +
+Get the name of this channel that was previously set by set_name.
bool +get_pty(self, + term, + width, + height) +
+Request a pseudo-terminal from the server.
Transport +get_transport(self) +
+Return the Transport associated with this channel.
float +gettimeout(self) +
+Returns the timeout in seconds (as a float) associated with socket +operations, or None if no timeout is set.
bool +invoke_shell(self) +
+Request an interactive shell session on this channel.
bool +invoke_subsystem(self, + subsystem) +
+Request a subsystem on the server (for example, +sftp).
ChannelFile +makefile(self, + *params) +
+Return a file-like object associated with this channel.
ChannelFile +makefile_stderr(self, + *params) +
+Return a file-like object associated with this channel's stderr +stream.
str +recv(self, + nbytes) +
+Receive data from the channel.
int +recv_exit_status(self) +
+Return the exit status from the process on the server.
boolean +recv_ready(self) +
+Returns true if data is buffered and ready to be read from this +channel.
str +recv_stderr(self, + nbytes) +
+Receive data from the channel's stderr stream.
boolean +recv_stderr_ready(self) +
+Returns true if data is buffered and ready to be read from this +channel's stderr stream.
bool +resize_pty(self, + width, + height) +
+Resize the pseudo-terminal.
int +send(self, + s) +
+Send data to the channel.
 send_exit_status(self, + status) +
+Send the exit status of an executed command to the client.
int +send_stderr(self, + s) +
+Send data to the channel on the "stderr" stream.
 sendall(self, + s) +
+Send data to the channel, without allowing partial results.
 sendall_stderr(self, + s) +
+Send data to the channel's "stderr" stream, without allowing +partial results.
bool +set_combine_stderr(self, + combine) +
+Set whether stderr should be combined into stdout on this channel.
 set_name(self, + name) +
+Set a name for this channel.
 setblocking(self, + blocking) +
+Set blocking or non-blocking mode of the channel: if +blocking is 0, the channel is set to non-blocking mode; +otherwise it's set to blocking mode.
 settimeout(self, + timeout) +
+Set a timeout on blocking read/write operations.
 shutdown(self, + how) +
+Shut down one or both halves of the connection.
 shutdown_read(self) +
+Shutdown the receiving side of this socket, closing the stream in the +incoming direction.
 shutdown_write(self) +
+Shutdown the sending side of this socket, closing the stream in the +outgoing direction.
 _check_add_window(self, + n) +
 _close_internal(self) +
 _feed(self, + m) +
 _feed_extended(self, + m) +
 _handle_close(self, + m) +
 _handle_eof(self, + m) +
 _handle_request(self, + m) +
 _log(self, + level, + msg) +
 _request_failed(self, + m) +
 _request_success(self, + m) +
 _send_eof(self) +
 _set_closed(self) +
 _set_remote_channel(self, + chanid, + window_size, + max_packet_size) +
 _set_transport(self, + transport) +
 _set_window(self, + window_size, + max_packet_size) +
 _unlink(self) +
 _wait_for_send_window(self, + size) +
+(You are already holding the lock.) Wait for the send window to open +up, and allocate up to size bytes for transmission.
 _window_adjust(self, + m) +
    Inherited from object
 __delattr__(...) +
+x.__delattr__('name') <==> del x.name
 __getattribute__(...) +
+x.__getattribute__('name') <==> x.name
 __hash__(x) +
+x.__hash__() <==> hash(x)
 __new__(T, + S, + ...) +
+T.__new__(S, ...) -> a new object with type S, a subtype of T
 __reduce__(...) +
+helper for pickle
 __reduce_ex__(...) +
+helper for pickle
 __setattr__(...) +
+x.__setattr__('name', value) <==> x.name = value
 __str__(x) +
+x.__str__() <==> str(x)

+ + + + + + + + +
Class Variable Summary
intMIN_PACKET_SIZE = 1024                                                                  

+ + + + + + +
Method Details
+ + +
+

__init__(self, + chanid) +
(Constructor) +

+ Create a new channel. The channel is not associated with any + particular session or Transport until the Transport attaches + it. Normally you would only call this method from the constructor of a + subclass of Channel. +
+
Parameters:
+
chanid - + the ID of this channel, as passed by an existing Transport. +
           + (type=int) +
+
+
Overrides:
+
__builtin__.object.__init__
+
+
+
+ + +
+

__repr__(self) +
(Representation operator) +

+ Return a string representation of this object, for debugging. +
+
Returns:
+
+ str +
+
+
Overrides:
+
__builtin__.object.__repr__
+
+
+
+ + +
+

close(self) +

+ Close the channel. All future read/write operations on the channel + will fail. The remote end will receive no more data (after queued data + is flushed). Channels are automatically closed when their Transport is closed or when they are + garbage collected. +
+
+
+ + +
+

exec_command(self, + command) +

+

Execute a command on the server. If the server allows it, the + channel will then be directly connected to the stdin, stdout, and + stderr of the command being executed.

+ When the command finishes executing, the channel will be closed and + can't be reused. You must open a new channel if you wish to execute + another command. +
+
Parameters:
+
command - + a shell command to execute. +
           + (type=str) +
+
+
Returns:
+
+ True if the operation succeeded; + False if not. +
           + (type=bool) +
+
+
+
+ + +
+

fileno(self) +

+

Returns an OS-level file descriptor which can be used for polling, + but but not for reading or writing). This is primaily to allow + python's select module to work.

+ The first time fileno is called on a channel, a pipe is + created to simulate real OS-level file descriptor (FD) behavior. + Because of this, two OS-level FDs are created, which will use up FDs + faster than normal. You won't notice this effect unless you open + hundreds or thousands of channels simultaneously, but it's still + notable. +
+
Returns:
+
+ an OS-level file descriptor +
           + (type=int) +
+
+

Warning: This method causes channel reads to be slightly less efficient. +

+ +
+
+ + +
+

get_id(self) +

+ Return the ID # for this channel. The channel ID is unique across a + Transport and usually a small number. + It's also the number passed to ServerInterface.check_channel_request + when determining whether to accept a channel request in server + mode. +
+
Returns:
+
+ the ID of this channel. +
           + (type=int) +
+
+

Since: ivysaur +

+ +
+
+ + +
+

get_name(self) +

+ Get the name of this channel that was previously set by set_name. +
+
Returns:
+
+ the name of this channel. +
           + (type=str) +
+
+
+
+ + +
+

get_pty(self, + term='vt100', + width=80, + height=24) +

+ Request a pseudo-terminal from the server. This is usually used + right after creating a client channel, to ask the server to provide + some basic terminal semantics for a shell invoked with invoke_shell. It isn't necessary (or + desirable) to call this method if you're going to exectue a single + command with exec_command. +
+
Parameters:
+
term - + the terminal type to emulate (for example, + 'vt100'). +
           + (type=str) +
width - + width (in characters) of the terminal screen +
           + (type=int) +
height - + height (in characters) of the terminal screen +
           + (type=int) +
+
+
Returns:
+
+ True if the operation succeeded; + False if not. +
           + (type=bool) +
+
+
+
+ + +
+

get_transport(self) +

+ Return the Transport associated with this + channel. +
+
Returns:
+
+ the Transport that was used to create + this channel. +
           + (type=Transport) +
+
+
+
+ + +
+

gettimeout(self) +

+ Returns the timeout in seconds (as a float) associated with socket + operations, or None if no timeout is set. This reflects + the last call to setblocking or settimeout. +
+
Returns:
+
+ timeout in seconds, or None. +
           + (type=float) +
+
+
+
+ + +
+

invoke_shell(self) +

+

Request an interactive shell session on this channel. If the server + allows it, the channel will then be directly connected to the stdin, + stdout, and stderr of the shell.

+

Normally you would call get_pty before this, in which case the + shell will operate through the pty, and the channel will be connected + to the stdin and stdout of the pty.

+ When the shell exits, the channel will be closed and can't be + reused. You must open a new channel if you wish to open another + shell. +
+
Returns:
+
+ True if the operation succeeded; + False if not. +
           + (type=bool) +
+
+
+
+ + +
+

invoke_subsystem(self, + subsystem) +

+

Request a subsystem on the server (for example, sftp). + If the server allows it, the channel will then be directly connected to + the requested subsystem.

+ When the subsystem finishes, the channel will be closed and can't be + reused. +
+
Parameters:
+
subsystem - + name of the subsystem being requested. +
           + (type=str) +
+
+
Returns:
+
+ True if the operation succeeded; + False if not. +
           + (type=bool) +
+
+
+
+ + +
+

makefile(self, + *params) +

+ Return a file-like object associated with this channel. The optional + mode and bufsize arguments are interpreted + the same way as by the built-in file() function in + python. +
+
Returns:
+
+ object which can be used for python file I/O. +
           + (type=ChannelFile) +
+
+
+
+ + +
+

makefile_stderr(self, + *params) +

+

Return a file-like object associated with this channel's stderr + stream. Only channels using exec_command or invoke_shell without a pty will ever have + data on the stderr stream.

+ The optional mode and bufsize arguments + are interpreted the same way as by the built-in file() + function in python. For a client, it only makes sense to open this file + for reading. For a server, it only makes sense to open this file for + writing. +
+
Returns:
+
+ object which can be used for python file I/O. +
           + (type=ChannelFile) +
+
+

Since: 1.1 +

+ +
+
+ + +
+

recv(self, + nbytes) +

+ Receive data from the channel. The return value is a string + representing the data received. The maximum amount of data to be + received at once is specified by nbytes. If a string of + length zero is returned, the channel stream has closed. +
+
Parameters:
+
nbytes - + maximum number of bytes to read. +
           + (type=int) +
+
+
Returns:
+
+ data. +
           + (type=str) +
+
+
Raises:
+
socket.timeout - + if no data is ready before the timeout set by settimeout. +
+
+
+ + +
+

recv_exit_status(self) +

+ Return the exit status from the process on the server. This is + mostly useful for retrieving the reults of an exec_command. If the command hasn't + finished yet, this method will wait until it does, or until the channel + is closed. If no exit status is provided by the server, -1 is + returned. +
+
Returns:
+
+ the exit code of the process on the server. +
           + (type=int) +
+
+

Since: 1.2 +

+ +
+
+ + +
+

recv_ready(self) +

+ Returns true if data is buffered and ready to be read from this + channel. A False result does not mean that the channel has + closed; it means you may need to wait before more data arrives. +
+
Returns:
+
+ True if a recv call on this channel would + immediately return at least one byte; False + otherwise. +
           + (type=boolean) +
+
+
+
+ + +
+

recv_stderr(self, + nbytes) +

+ Receive data from the channel's stderr stream. Only channels using + exec_command or invoke_shell without a pty will ever have + data on the stderr stream. The return value is a string representing + the data received. The maximum amount of data to be received at once is + specified by nbytes. If a string of length zero is + returned, the channel stream has closed. +
+
Parameters:
+
nbytes - + maximum number of bytes to read. +
           + (type=int) +
+
+
Returns:
+
+ data. +
           + (type=str) +
+
+
Raises:
+
socket.timeout - + if no data is ready before the timeout set by settimeout. +
+

Since: 1.1 +

+ +
+
+ + +
+

recv_stderr_ready(self) +

+ Returns true if data is buffered and ready to be read from this + channel's stderr stream. Only channels using exec_command or invoke_shell without a pty will ever have + data on the stderr stream. +
+
Returns:
+
+ True if a recv_stderr call on this channel + would immediately return at least one byte; False + otherwise. +
           + (type=boolean) +
+
+

Since: 1.1 +

+ +
+
+ + +
+

resize_pty(self, + width=80, + height=24) +

+ Resize the pseudo-terminal. This can be used to change the width and + height of the terminal emulation created in a previous get_pty call. +
+
Parameters:
+
width - + new width (in characters) of the terminal screen +
           + (type=int) +
height - + new height (in characters) of the terminal screen +
           + (type=int) +
+
+
Returns:
+
+ True if the operation succeeded; + False if not. +
           + (type=bool) +
+
+
+
+ + +
+

send(self, + s) +

+ Send data to the channel. Returns the number of bytes sent, or 0 if + the channel stream is closed. Applications are responsible for checking + that all data has been sent: if only some of the data was transmitted, + the application needs to attempt delivery of the remaining data. +
+
Parameters:
+
s - + data to send. +
           + (type=str) +
+
+
Returns:
+
+ number of bytes actually sent. +
           + (type=int) +
+
+
Raises:
+
socket.timeout - + if no data could be sent before the timeout set by settimeout. +
+
+
+ + +
+

send_exit_status(self, + status) +

+ Send the exit status of an executed command to the client. (This + really only makes sense in server mode.) Many clients expect to get + some sort of status code back from an executed command after it + completes. +
+
Parameters:
+
status - + the exit code of the process +
           + (type=int) +
+
+

Since: 1.2 +

+ +
+
+ + +
+

send_stderr(self, + s) +

+ Send data to the channel on the "stderr" stream. This is + normally only used by servers to send output from shell commands -- + clients won't use this. Returns the number of bytes sent, or 0 if the + channel stream is closed. Applications are responsible for checking + that all data has been sent: if only some of the data was transmitted, + the application needs to attempt delivery of the remaining data. +
+
Parameters:
+
s - + data to send. +
           + (type=str) +
+
+
Returns:
+
+ number of bytes actually sent. +
           + (type=int) +
+
+
Raises:
+
socket.timeout - + if no data could be sent before the timeout set by settimeout. +
+

Since: 1.1 +

+ +
+
+ + +
+

sendall(self, + s) +

+ Send data to the channel, without allowing partial results. Unlike + send, this method continues to send data + from the given string until either all data has been sent or an error + occurs. Nothing is returned. +
+
Parameters:
+
s - + data to send. +
           + (type=str) +
+
+
Raises:
+
socket.timeout - + if sending stalled for longer than the timeout set by settimeout. +
socket.error - + if an error occured before the entire string was sent. +
+

Note: If the channel is closed while only part of the data hase been sent, +there is no way to determine how much data (if any) was sent. This is +irritating, but identically follows python's API. +

+ +
+
+ + +
+

sendall_stderr(self, + s) +

+ Send data to the channel's "stderr" stream, without + allowing partial results. Unlike send_stderr, this method continues to + send data from the given string until all data has been sent or an + error occurs. Nothing is returned. +
+
Parameters:
+
s - + data to send to the client as "stderr" output. +
           + (type=str) +
+
+
Raises:
+
socket.timeout - + if sending stalled for longer than the timeout set by settimeout. +
socket.error - + if an error occured before the entire string was sent. +
+

Since: 1.1 +

+ +
+
+ + +
+

set_combine_stderr(self, + combine) +

+

Set whether stderr should be combined into stdout on this channel. + The default is False, but in some cases it may be + convenient to have both streams combined.

+

If this is False, and exec_command is called (or + invoke_shell with no pty), output to stderr will not show + up through the recv and recv_ready calls. You will have to use recv_stderr and recv_stderr_ready to get stderr + output.

+ If this is True, data will never show up via recv_stderr or recv_stderr_ready. +
+
Parameters:
+
combine - + True if stderr output should be combined into + stdout on this channel. +
           + (type=bool) +
+
+
Returns:
+
+ previous setting. +
           + (type=bool) +
+
+

Since: 1.1 +

+ +
+
+ + +
+

set_name(self, + name) +

+ Set a name for this channel. Currently it's only used to set the + name of the log level used for debugging. The name can be fetched with + the get_name method. +
+
Parameters:
+
name - + new channel name. +
           + (type=str) +
+
+
+
+ + +
+

setblocking(self, + blocking) +

+

Set blocking or non-blocking mode of the channel: if + blocking is 0, the channel is set to non-blocking mode; + otherwise it's set to blocking mode. Initially all channels are in + blocking mode.

+

In non-blocking mode, if a recv call doesn't find any data, or if a + send call can't immediately dispose of + the data, an error exception is raised. In blocking mode, the calls + block until they can proceed.

+ chan.setblocking(0) is equivalent to + chan.settimeout(0); chan.setblocking(1) is + equivalent to chan.settimeout(None). +
+
Parameters:
+
blocking - + 0 to set non-blocking mode; non-0 to set blocking mode. +
           + (type=int) +
+
+
+
+ + +
+

settimeout(self, + timeout) +

+

Set a timeout on blocking read/write operations. The + timeout argument can be a nonnegative float expressing + seconds, or None. If a float is given, subsequent channel + read/write operations will raise a timeout exception if the timeout + period value has elapsed before the operation has completed. Setting a + timeout of None disables timeouts on socket + operations.

+ chan.settimeout(0.0) is equivalent to + chan.setblocking(0); chan.settimeout(None) is + equivalent to chan.setblocking(1). +
+
Parameters:
+
timeout - + seconds to wait for a pending read/write operation before + raising socket.timeout, or None for no + timeout. +
           + (type=float) +
+
+
+
+ + +
+

shutdown(self, + how) +

+ Shut down one or both halves of the connection. If how + is 0, further receives are disallowed. If how is 1, + further sends are disallowed. If how is 2, further sends + and receives are disallowed. This closes the stream in one or both + directions. +
+
Parameters:
+
how - + 0 (stop receiving), 1 (stop sending), or 2 (stop receiving and + sending). +
           + (type=int) +
+
+
+
+ + +
+

shutdown_read(self) +

+ Shutdown the receiving side of this socket, closing the stream in + the incoming direction. After this call, future reads on this channel + will fail instantly. This is a convenience method, equivalent to + shutdown(0), for people who don't make it a habit to + memorize unix constants from the 1970s. +
+

Since: 1.2 +

+ +
+
+ + +
+

shutdown_write(self) +

+ Shutdown the sending side of this socket, closing the stream in the + outgoing direction. After this call, future writes on this channel will + fail instantly. This is a convenience method, equivalent to + shutdown(1), for people who don't make it a habit to + memorize unix constants from the 1970s. +
+

Since: 1.2 +

+ +
+
+ + +
+

_wait_for_send_window(self, + size) +

+ (You are already holding the lock.) Wait for the send window to open + up, and allocate up to size bytes for transmission. If no + space opens up before the timeout, a timeout exception is raised. + Returns the number of bytes available to send (may be less than + requested). +
+
+
+
+ + + + + + +
Class Variable Details
+
+ +

MIN_PACKET_SIZE

+
+
+
+
+
Type:
+
+ int + +
+
Value:
+
+
+1024                                                                  
+
+
+
+
+
+ + + + + + + + + + + +
   Home      Trees      Index      Help   
+ + + + + + +
Generated by Epydoc 2.1 on Sun Dec 4 11:16:47 2005http://epydoc.sf.net
+ + -- cgit v1.2.3