SSH Channels

Functions that manage a channel. More...


Functions

int channel_change_pty_size (CHANNEL *channel, int cols, int rows)
 Change the size of the terminal associated to a channel.
int channel_close (CHANNEL *channel)
 Close a channel.
void channel_free (CHANNEL *channel)
 Close and free a channel.
int channel_get_exit_status (CHANNEL *channel)
 Get the exit status of the channel (error code from the executed instruction).
SSH_SESSION * channel_get_session (CHANNEL *channel)
 Recover the session in which belongs a channel.
int channel_is_closed (CHANNEL *channel)
 Check if the channel is closed or not.
int channel_is_eof (CHANNEL *channel)
 Check if remote has sent an EOF.
int channel_is_open (CHANNEL *channel)
 Check if the channel is open or not.
CHANNEL * channel_new (SSH_SESSION *session)
 Allocate a new channel.
int channel_open_forward (CHANNEL *channel, const char *remotehost, int remoteport, const char *sourcehost, int localport)
 Open a TCP/IP forwarding channel.
int channel_open_session (CHANNEL *channel)
 Open a session channel (suited for a shell, not TCP forwarding).
int channel_poll (CHANNEL *channel, int is_stderr)
 Polls a channel for data to read.
int channel_read (CHANNEL *channel, void *dest, u32 count, int is_stderr)
 Reads data from a channel.
int channel_read_buffer (CHANNEL *channel, BUFFER *buffer, u32 count, int is_stderr)
 Read data from a channel into a buffer.
int channel_read_nonblocking (CHANNEL *channel, void *dest, u32 count, int is_stderr)
 Do a nonblocking read on the channel.
int channel_request_env (CHANNEL *channel, const char *name, const char *value)
 Set environement variables.
int channel_request_exec (CHANNEL *channel, const char *cmd)
 Run a shell command without an interactive shell.
int channel_request_pty (CHANNEL *channel)
 Request a PTY.
int channel_request_pty_size (CHANNEL *channel, const char *terminal, int col, int row)
 Request a pty with a specific type and size.
int channel_request_shell (CHANNEL *channel)
 Request a shell.
int channel_request_subsystem (CHANNEL *channel, const char *sys)
 Request a subsystem (for example "sftp").
int channel_select (CHANNEL **readchans, CHANNEL **writechans, CHANNEL **exceptchans, struct timeval *timeout)
 Act like the standard select(2) on channels.
int channel_send_eof (CHANNEL *channel)
 Send an end of file on the channel.
void channel_set_blocking (CHANNEL *channel, int blocking)
 Put the channel into blocking or nonblocking mode.
int channel_write (CHANNEL *channel, const void *data, u32 len)
 Blocking write on channel.


Detailed Description

Functions that manage a channel.

Function Documentation

int channel_change_pty_size ( CHANNEL *  channel,
int  cols,
int  rows 
)

Change the size of the terminal associated to a channel.

Parameters:
channel The channel to change the size.
cols The new number of columns.
rows The new number of rows.
Warning:
Do not call it from a signal handler if you are not sure any other libssh function using the same channel/session is running at same time (not 100% threadsafe).

References buffer_free(), and buffer_new().

int channel_close ( CHANNEL *  channel  ) 

Close a channel.

This sends an end of file and then closes the channel. You won't be able to recover any data the server was going to send or was in buffers.

Parameters:
channel The channel to close.
Returns:
SSH_SUCCESS on success
SSH_ERROR on error
See also:
channel_free()

channel_eof()

References channel_send_eof(), ssh_log(), and SSH_LOG_PACKET.

Referenced by channel_free().

void channel_free ( CHANNEL *  channel  ) 

Close and free a channel.

Parameters:
channel The channel to free.
Warning:
Any data unread on this channel will be lost.

References buffer_free(), and channel_close().

int channel_get_exit_status ( CHANNEL *  channel  ) 

Get the exit status of the channel (error code from the executed instruction).

Parameters:
channel The channel to get the status from.
Returns:
-1 if no exit status has been returned or eof not sent, the exit status othewise.

SSH_SESSION* channel_get_session ( CHANNEL *  channel  ) 

Recover the session in which belongs a channel.

Parameters:
channel The channel to recover the session from.
Returns:
The session pointer.

int channel_is_closed ( CHANNEL *  channel  ) 

Check if the channel is closed or not.

Parameters:
channel The channel to check.
Returns:
0 if channel is opened, nonzero otherwise.
See also:
channel_is_open()

int channel_is_eof ( CHANNEL *  channel  ) 

Check if remote has sent an EOF.

Parameters:
channel The channel to check.
Returns:
0 if there is no EOF, nonzero otherwise.

int channel_is_open ( CHANNEL *  channel  ) 

Check if the channel is open or not.

Parameters:
channel The channel to check.
Returns:
0 if channel is closed, nonzero otherwise.
See also:
channel_is_closed()

CHANNEL* channel_new ( SSH_SESSION *  session  ) 

Allocate a new channel.

Parameters:
session The ssh session to use.
Returns:
A pointer to a newly allocated channel, NULL on error.

References buffer_new().

int channel_open_forward ( CHANNEL *  channel,
const char *  remotehost,
int  remoteport,
const char *  sourcehost,
int  localport 
)

Open a TCP/IP forwarding channel.

Parameters:
channel An allocated channel.
remotehost The remote host to connected (host name or IP).
remoteport The remote port.
sourcehost The source host (your local computer). It's facultative and for logging purpose.
localport The source port (your local computer). It's facultative and for logging purpose.
Returns:
SSH_OK on success
SSH_ERROR on error

References buffer_free(), buffer_new(), string_free(), and string_from_char().

int channel_open_session ( CHANNEL *  channel  ) 

Open a session channel (suited for a shell, not TCP forwarding).

Parameters:
channel An allocated channel.
Returns:
SSH_OK on success
SSH_ERROR on error.
See also:
channel_open_forward()

channel_request_env()

channel_request_shell()

channel_request_exec()

int channel_poll ( CHANNEL *  channel,
int  is_stderr 
)

Polls a channel for data to read.

Parameters:
channel The channel to poll.
is_stderr A boolean to select the stderr stream.
Returns:
The number of bytes available for reading, 0 if nothing is available or SSH_ERROR on error.
Warning:
When the channel is in EOF state, the function returns SSH_EOF.
See also:
channel_is_eof()

References ssh_handle_packets().

Referenced by channel_read_nonblocking(), and ssh_select().

int channel_read ( CHANNEL *  channel,
void *  dest,
u32  count,
int  is_stderr 
)

Reads data from a channel.

Parameters:
channel The channel to read from.
dest The destination buffer which will get the data.
count The count of bytes to be read.
is_stderr A boolean value to mark reading from the stderr flow.
Returns:
The number of bytes read, 0 on end of file or SSH_ERROR on error.
Warning:
The read function using a buffer has been renamed to channel_read_buffer().

References ssh_log(), and SSH_LOG_PROTOCOL.

Referenced by channel_read_nonblocking().

int channel_read_buffer ( CHANNEL *  channel,
BUFFER buffer,
u32  count,
int  is_stderr 
)

Read data from a channel into a buffer.

Parameters:
channel The channel to read from.
buffer The buffer which will get the data.
count The count of bytes to be read. If it is biggerthan 0, the exact size will be read, else (bytes=0) it will return once anything is available.
is_stderr A boolean value to mark reading from the stderr stream.
Returns:
The number of bytes read, 0 on end of file or SSH_ERROR on error.

References buffer_get_len(), ssh_log(), and SSH_LOG_PROTOCOL.

int channel_read_nonblocking ( CHANNEL *  channel,
void *  dest,
u32  count,
int  is_stderr 
)

Do a nonblocking read on the channel.

A nonblocking read on the specified channel. it will return <= count bytes of data read atomicly.

Parameters:
channel The channel to read from.
dest A pointer to a destination buffer.
count The count of bytes of data to be read.
is_stderr A boolean to select the stderr stream.
Returns:
The number of bytes read, 0 if nothing is available or SSH_ERROR on error.
Warning:
Don't forget to check for EOF as it would return 0 here.
See also:
channel_is_eof()

References channel_poll(), and channel_read().

int channel_request_env ( CHANNEL *  channel,
const char *  name,
const char *  value 
)

Set environement variables.

Parameters:
channel The channel to set the environement variables.
name The name of the variable.
value The value to set.
Returns:
SSH_SUCCESS on success, SSH_ERROR on error.
Warning:
Some environement variables may be refused by security reasons.

References buffer_free(), buffer_new(), string_free(), and string_from_char().

int channel_request_exec ( CHANNEL *  channel,
const char *  cmd 
)

Run a shell command without an interactive shell.

This is similar to 'sh -c command'.

Parameters:
channel The channel to execute the command.
cmd The command to execute (e.g. "ls ~/ -al | grep -i reports").
Returns:
SSH_SUCCESS on success, SSH_ERROR on error.
See also:
channel_request_shell()

References buffer_free(), buffer_new(), string_free(), and string_from_char().

int channel_request_pty ( CHANNEL *  channel  ) 

Request a PTY.

Parameters:
channel The channel to send the request.
Returns:
SSH_SUCCESS on success, SSH_ERROR on error.
See also:
channel_request_pty_size()

References channel_request_pty_size().

int channel_request_pty_size ( CHANNEL *  channel,
const char *  terminal,
int  col,
int  row 
)

Request a pty with a specific type and size.

Parameters:
channel The channel to sent the request.
terminal The terminal type ("vt100, xterm,...").
col The number of columns.
row The number of rows.
Returns:
SSH_SUCCESS on success, SSH_ERROR on error.

References buffer_free(), buffer_new(), string_free(), and string_from_char().

Referenced by channel_request_pty().

int channel_request_shell ( CHANNEL *  channel  ) 

Request a shell.

Parameters:
channel The channel to send the request.
Returns:
SSH_SUCCESS on success, SSH_ERROR on error.

int channel_request_subsystem ( CHANNEL *  channel,
const char *  sys 
)

Request a subsystem (for example "sftp").

Parameters:
channel The channel to send the request.
system The subsystem to request (for example "sftp").
Returns:
SSH_SUCCESS on success, SSH_ERROR on error.
Warning:
You normally don't have to call it for sftp, see sftp_new().

References buffer_free(), buffer_new(), string_free(), and string_from_char().

int channel_select ( CHANNEL **  readchans,
CHANNEL **  writechans,
CHANNEL **  exceptchans,
struct timeval *  timeout 
)

Act like the standard select(2) on channels.

The list of pointers are then actualized and will only contain pointers to channels that are respectively readable, writable or have an exception to trap.

Parameters:
readchans A NULL pointer or an array of channel pointers, terminated by a NULL.
writechans A NULL pointer or an array of channel pointers, terminated by a NULL.
exceptchans A NULL pointer or an array of channel pointers, terminated by a NULL.
timeout Timeout as defined by select(2).
Returns:
SSH_SUCCESS operation successful
SSH_EINTR select(2) syscall was interrupted, relaunch the function

int channel_send_eof ( CHANNEL *  channel  ) 

Send an end of file on the channel.

This doesn't close the channel. You may still read from it but not write.

Parameters:
channel The channel to send the eof to.
Returns:
SSH_SUCCESS on success
SSH_ERROR on error
See also:
channel_close()

channel_free()

References ssh_log(), and SSH_LOG_PACKET.

Referenced by channel_close().

void channel_set_blocking ( CHANNEL *  channel,
int  blocking 
)

Put the channel into blocking or nonblocking mode.

Parameters:
channel The channel to use.
blocking A boolean for blocking or nonblocking.
Bug:
This functionnality is still under development and doesn't work correctly.

int channel_write ( CHANNEL *  channel,
const void *  data,
u32  len 
)

Blocking write on channel.

Parameters:
channel The channel to write to.
data A pointer to the data to write.
len The length of the buffer to write to.
Returns:
The number of bytes written, SSH_ERROR on error.
See also:
channel_read()

References ssh_log(), SSH_LOG_PROTOCOL, and SSH_LOG_RARE.


doxygen