The SSH channel functions
[The libssh API]

Functions that manage a SSH channel. More...

Collaboration diagram for The SSH channel functions:

Functions

int channel_read_buffer (ssh_channel channel, ssh_buffer buffer, uint32_t count, int is_stderr)
 Read data from a channel into a buffer.
ssh_channel ssh_channel_accept_x11 (ssh_channel channel, int timeout_ms)
 Accept an X11 forwarding channel.
int ssh_channel_change_pty_size (ssh_channel channel, int cols, int rows)
 Change the size of the terminal associated to a channel.
int ssh_channel_close (ssh_channel channel)
 Close a channel.
void ssh_channel_free (ssh_channel channel)
 Close and free a channel.
int ssh_channel_get_exit_status (ssh_channel channel)
 Get the exit status of the channel (error code from the executed instruction).
ssh_session ssh_channel_get_session (ssh_channel channel)
 Recover the session in which belongs a channel.
int ssh_channel_is_closed (ssh_channel channel)
 Check if the channel is closed or not.
int ssh_channel_is_eof (ssh_channel channel)
 Check if remote has sent an EOF.
int ssh_channel_is_open (ssh_channel channel)
 Check if the channel is open or not.
ssh_channel ssh_channel_new (ssh_session session)
 Allocate a new channel.
int ssh_channel_open_forward (ssh_channel channel, const char *remotehost, int remoteport, const char *sourcehost, int localport)
 Open a TCP/IP forwarding channel.
int ssh_channel_open_session (ssh_channel channel)
 Open a session channel (suited for a shell, not TCP forwarding).
int ssh_channel_poll (ssh_channel channel, int is_stderr)
 Polls a channel for data to read.
int ssh_channel_read (ssh_channel channel, void *dest, uint32_t count, int is_stderr)
 Reads data from a channel.
int ssh_channel_read_nonblocking (ssh_channel channel, void *dest, uint32_t count, int is_stderr)
 Do a nonblocking read on the channel.
int ssh_channel_request_env (ssh_channel channel, const char *name, const char *value)
 Set environment variables.
int ssh_channel_request_exec (ssh_channel channel, const char *cmd)
 Run a shell command without an interactive shell.
int ssh_channel_request_pty (ssh_channel channel)
 Request a PTY.
int ssh_channel_request_pty_size (ssh_channel channel, const char *terminal, int col, int row)
 Request a pty with a specific type and size.
int ssh_channel_request_send_signal (ssh_channel channel, const char *sig)
 Send a signal to remote process (as described in RFC 4254, section 6.9).
int ssh_channel_request_shell (ssh_channel channel)
 Request a shell.
int ssh_channel_request_subsystem (ssh_channel channel, const char *subsys)
 Request a subsystem (for example "sftp").
int ssh_channel_request_x11 (ssh_channel channel, int single_connection, const char *protocol, const char *cookie, int screen_number)
 Sends the "x11-req" channel request over an existing session channel.
int ssh_channel_select (ssh_channel *readchans, ssh_channel *writechans, ssh_channel *exceptchans, struct timeval *timeout)
 Act like the standard select(2) on channels.
int ssh_channel_send_eof (ssh_channel channel)
 Send an end of file on the channel.
void ssh_channel_set_blocking (ssh_channel channel, int blocking)
 Put the channel into blocking or nonblocking mode.
int ssh_channel_write (ssh_channel channel, const void *data, uint32_t len)
 Blocking write on a channel.
ssh_channel ssh_forward_accept (ssh_session session, int timeout_ms)
 Accept an incoming TCP/IP forwarding channel.
int ssh_forward_cancel (ssh_session session, const char *address, int port)
 Sends the "cancel-tcpip-forward" global request to ask the server to cancel the tcpip-forward request.
int ssh_forward_listen (ssh_session session, const char *address, int port, int *bound_port)
 Sends the "tcpip-forward" global request to ask the server to begin listening for inbound connections.

Detailed Description

Functions that manage a SSH channel.


Function Documentation

int channel_read_buffer ( ssh_channel  channel,
ssh_buffer  buffer,
uint32_t  count,
int  is_stderr 
)

Read data from a channel into a buffer.

Parameters:
[in] channel The channel to read from.
[in] buffer The buffer which will get the data.
[in] count The count of bytes to be read. If it is bigger than 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.
Deprecated:
Please use ssh_channel_read instead
See also:
ssh_channel_read

References ssh_channel_is_eof(), ssh_channel_poll(), and ssh_channel_read().

ssh_channel ssh_channel_accept_x11 ( ssh_channel  channel,
int  timeout_ms 
)

Accept an X11 forwarding channel.

Parameters:
[in] channel An x11-enabled session channel.
[in] timeout_ms Timeout in milliseconds.
Returns:
A newly created channel, or NULL if no X11 request from the server.

Referenced by ssh::Channel::acceptX11().

int ssh_channel_change_pty_size ( ssh_channel  channel,
int  cols,
int  rows 
)

Change the size of the terminal associated to a channel.

Parameters:
[in] channel The channel to change the size.
[in] cols The new number of columns.
[in] rows The new number of rows.
Returns:
SSH_OK on success, SSH_ERROR if an error occured.
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 ssh_buffer_free(), and ssh_buffer_new().

Referenced by ssh::Channel::changePtySize().

int ssh_channel_close ( ssh_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:
[in] channel The channel to close.
Returns:
SSH_OK on success, SSH_ERROR if an error occured.
See also:
channel_free()
channel_eof()

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

Referenced by ssh::Channel::close(), and ssh_channel_free().

void ssh_channel_free ( ssh_channel  channel  ) 

Close and free a channel.

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

References ssh_buffer_free(), and ssh_channel_close().

Referenced by ssh_disconnect(), and ssh_free().

int ssh_channel_get_exit_status ( ssh_channel  channel  ) 

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

Parameters:
[in] channel The channel to get the status from.
Returns:
The exit status, -1 if no exit status has been returned or eof not sent.
ssh_session ssh_channel_get_session ( ssh_channel  channel  ) 

Recover the session in which belongs a channel.

Parameters:
[in] channel The channel to recover the session from.
Returns:
The session pointer.
int ssh_channel_is_closed ( ssh_channel  channel  ) 

Check if the channel is closed or not.

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

Referenced by ssh::Channel::isClosed().

int ssh_channel_is_eof ( ssh_channel  channel  ) 

Check if remote has sent an EOF.

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

Referenced by channel_read_buffer(), ssh::Channel::isEof(), and ssh_scp_pull_request().

int ssh_channel_is_open ( ssh_channel  channel  ) 

Check if the channel is open or not.

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

Referenced by ssh::Channel::isOpen().

ssh_channel ssh_channel_new ( ssh_session  session  ) 

Allocate a new channel.

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

References ssh_buffer_free(), and ssh_buffer_new().

int ssh_channel_open_forward ( ssh_channel  channel,
const char *  remotehost,
int  remoteport,
const char *  sourcehost,
int  localport 
)

Open a TCP/IP forwarding channel.

Parameters:
[in] channel An allocated channel.
[in] remotehost The remote host to connected (host name or IP).
[in] remoteport The remote port.
[in] sourcehost The numeric IP address of the machine from where the connection request originates. This is mostly for logging purposes.
[in] localport The port on the host from where the connection originated. This is mostly for logging purposes.
Returns:
SSH_OK on success, SSH_ERROR if an error occured.
Warning:
This function does not bind the local port and does not automatically forward the content of a socket to the channel. You still have to use channel_read and channel_write for this.

References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), and ssh_string_from_char().

int ssh_channel_open_session ( ssh_channel  channel  ) 

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

Parameters:
[in] channel An allocated channel.
Returns:
SSH_OK on success, SSH_ERROR if an error occured.
See also:
channel_open_forward()
channel_request_env()
channel_request_shell()
channel_request_exec()
int ssh_channel_poll ( ssh_channel  channel,
int  is_stderr 
)

Polls a channel for data to read.

Parameters:
[in] channel The channel to poll.
[in] 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()

Referenced by channel_read_buffer(), ssh_channel_read_nonblocking(), ssh_scp_write(), and ssh_select().

int ssh_channel_read ( ssh_channel  channel,
void *  dest,
uint32_t  count,
int  is_stderr 
)

Reads data from a channel.

Parameters:
[in] channel The channel to read from.
[in] dest The destination buffer which will get the data.
[in] count The count of bytes to be read.
[in] 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:
This function may return less than count bytes of data, and won't block until count bytes have been read.
The read function using a buffer has been renamed to channel_read_buffer().

References ssh_log(), and SSH_LOG_PROTOCOL.

Referenced by channel_read_buffer(), ssh_channel_read_nonblocking(), ssh_scp_leave_directory(), ssh_scp_push_directory(), ssh_scp_push_file(), ssh_scp_read(), ssh_scp_read_string(), and ssh_scp_write().

int ssh_channel_read_nonblocking ( ssh_channel  channel,
void *  dest,
uint32_t  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 atomically.

Parameters:
[in] channel The channel to read from.
[in] dest A pointer to a destination buffer.
[in] count The count of bytes of data to be read.
[in] 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 ssh_channel_poll(), and ssh_channel_read().

int ssh_channel_request_env ( ssh_channel  channel,
const char *  name,
const char *  value 
)

Set environment variables.

Parameters:
[in] channel The channel to set the environment variables.
[in] name The name of the variable.
[in] value The value to set.
Returns:
SSH_OK on success, SSH_ERROR if an error occured.
Warning:
Some environment variables may be refused by security reasons.

References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), and ssh_string_from_char().

int ssh_channel_request_exec ( ssh_channel  channel,
const char *  cmd 
)

Run a shell command without an interactive shell.

This is similar to 'sh -c command'.

Parameters:
[in] channel The channel to execute the command.
[in] cmd The command to execute (e.g. "ls ~/ -al | grep -i reports").
Returns:
SSH_OK on success, SSH_ERROR if an error occured.
   rc = channel_request_exec(channel, "ps aux");
   if (rc > 0) {
     return -1;
   }

   while ((rc = channel_read(channel, buffer, sizeof(buffer), 0)) > 0) {
     if (fwrite(buffer, 1, rc, stdout) != (unsigned int) rc) {
       return -1;
     }
   }
See also:
channel_request_shell()

References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), and ssh_string_from_char().

int ssh_channel_request_pty ( ssh_channel  channel  ) 

Request a PTY.

Parameters:
[in] channel The channel to send the request.
Returns:
SSH_OK on success, SSH_ERROR if an error occured.
See also:
channel_request_pty_size()

References ssh_channel_request_pty_size().

int ssh_channel_request_pty_size ( ssh_channel  channel,
const char *  terminal,
int  col,
int  row 
)

Request a pty with a specific type and size.

Parameters:
[in] channel The channel to sent the request.
[in] terminal The terminal type ("vt100, xterm,...").
[in] col The number of columns.
[in] row The number of rows.
Returns:
SSH_OK on success, SSH_ERROR if an error occured.

References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), and ssh_string_from_char().

Referenced by ssh_channel_request_pty().

int ssh_channel_request_send_signal ( ssh_channel  channel,
const char *  sig 
)

Send a signal to remote process (as described in RFC 4254, section 6.9).

Sends a signal 'sig' to the remote process. Note, that remote system may not support signals concept. In such a case this request will be silently ignored. Only SSH-v2 is supported (I'm not sure about SSH-v1).

OpenSSH doesn't support signals yet, see: https://bugzilla.mindrot.org/show_bug.cgi?id=1424

Parameters:
[in] channel The channel to send signal.
[in] sig The signal to send (without SIG prefix)

SIGABRT -> ABRT
SIGALRM -> ALRM
SIGFPE -> FPE
SIGHUP -> HUP
SIGILL -> ILL
SIGINT -> INT
SIGKILL -> KILL
SIGPIPE -> PIPE
SIGQUIT -> QUIT
SIGSEGV -> SEGV
SIGTERM -> TERM
SIGUSR1 -> USR1
SIGUSR2 -> USR2
Returns:
SSH_OK on success, SSH_ERROR if an error occured (including attempts to send signal via SSH-v1 session).

References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), and ssh_string_from_char().

int ssh_channel_request_shell ( ssh_channel  channel  ) 

Request a shell.

Parameters:
[in] channel The channel to send the request.
Returns:
SSH_OK on success, SSH_ERROR if an error occured.
int ssh_channel_request_subsystem ( ssh_channel  channel,
const char *  subsys 
)

Request a subsystem (for example "sftp").

Parameters:
[in] channel The channel to send the request.
[in] subsys The subsystem to request (for example "sftp").
Returns:
SSH_OK on success, SSH_ERROR if an error occured.
Warning:
You normally don't have to call it for sftp, see sftp_new().

References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), and ssh_string_from_char().

int ssh_channel_request_x11 ( ssh_channel  channel,
int  single_connection,
const char *  protocol,
const char *  cookie,
int  screen_number 
)

Sends the "x11-req" channel request over an existing session channel.

This will enable redirecting the display of the remote X11 applications to local X server over an secure tunnel.

Parameters:
[in] channel An existing session channel where the remote X11 applications are going to be executed.
[in] single_connection A boolean to mark only one X11 app will be redirected.
[in] protocol A x11 authentication protocol. Pass NULL to use the default value MIT-MAGIC-COOKIE-1.
[in] cookie A x11 authentication cookie. Pass NULL to generate a random cookie.
[in] screen_number The screen number.
Returns:
SSH_OK on success, SSH_ERROR if an error occured.

References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), and ssh_string_from_char().

int ssh_channel_select ( ssh_channel *  readchans,
ssh_channel *  writechans,
ssh_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:
[in] readchans A NULL pointer or an array of channel pointers, terminated by a NULL.
[in] writechans A NULL pointer or an array of channel pointers, terminated by a NULL.
[in] exceptchans A NULL pointer or an array of channel pointers, terminated by a NULL.
[in] timeout Timeout as defined by select(2).
Returns:
SSH_OK on a successful operation, SSH_EINTR if the select(2) syscall was interrupted, then relaunch the function.
int ssh_channel_send_eof ( ssh_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:
[in] channel The channel to send the eof to.
Returns:
SSH_OK on success, SSH_ERROR if an error occured.
See also:
channel_close()
channel_free()

References ssh_log(), and SSH_LOG_PACKET.

Referenced by ssh_channel_close().

void ssh_channel_set_blocking ( ssh_channel  channel,
int  blocking 
)

Put the channel into blocking or nonblocking mode.

Parameters:
[in] channel The channel to use.
[in] blocking A boolean for blocking or nonblocking.
Bug:
This functionality is still under development and doesn't work correctly.
int ssh_channel_write ( ssh_channel  channel,
const void *  data,
uint32_t  len 
)

Blocking write on a channel.

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

Referenced by ssh_scp_accept_request(), ssh_scp_deny_request(), ssh_scp_leave_directory(), ssh_scp_pull_request(), ssh_scp_push_directory(), ssh_scp_push_file(), ssh_scp_read(), ssh_scp_write(), and ssh::Channel::write().

ssh_channel ssh_forward_accept ( ssh_session  session,
int  timeout_ms 
)

Accept an incoming TCP/IP forwarding channel.

Parameters:
[in] session The ssh session to use.
[in] timeout_ms A timeout in milliseconds.
Returns:
Newly created channel, or NULL if no incoming channel request from the server

Referenced by ssh::Session::acceptForward().

int ssh_forward_cancel ( ssh_session  session,
const char *  address,
int  port 
)

Sends the "cancel-tcpip-forward" global request to ask the server to cancel the tcpip-forward request.

Parameters:
[in] session The ssh session to send the request.
[in] address The bound address on the server.
[in] port The bound port on the server.
Returns:
SSH_OK on success, SSH_ERROR if an error occured.

References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), and ssh_string_from_char().

int ssh_forward_listen ( ssh_session  session,
const char *  address,
int  port,
int *  bound_port 
)

Sends the "tcpip-forward" global request to ask the server to begin listening for inbound connections.

Parameters:
[in] session The ssh session to send the request.
[in] address The address to bind to on the server. Pass NULL to bind to all available addresses on all protocol families supported by the server.
[in] port The port to bind to on the server. Pass 0 to ask the server to allocate the next available unprivileged port number
[in] bound_port The pointer to get actual bound port. Pass NULL to ignore.
Returns:
SSH_OK on success, SSH_ERROR if an error occured.

References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), and ssh_string_from_char().


Generated on 22 Mar 2017 for libssh by  doxygen 1.6.1