NAME
Ssh_channel - functions that manage a channel
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 SSH_SESSION * channel_get_session (CHANNEL *channel)
recover the session in which belong a channel int channel_is_closed (CHANNEL *channel)
returns if the channel is closed or not int channel_is_eof (CHANNEL *channel)
returns if the remote has sent an EOF int channel_is_open (CHANNEL *channel)
returns if the channel is open or not CHANNEL * channel_new (SSH_SESSION *session)
allocate a new channel int channel_open_forward (CHANNEL *channel, char *remotehost, int remoteport, 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) int channel_poll (CHANNEL *channel, int is_stderr)
polls the channel for data to read int channel_read (CHANNEL *channel, BUFFER *buffer, int bytes, int is_stderr)
reads data from a channel int channel_read_nonblocking (CHANNEL *channel, char *dest, int len, int is_stderr)
nonblocking read int channel_request_env (CHANNEL *channel, char *name, char *value)
set the environement variables int channel_request_exec (CHANNEL *channel, char *cmd)
run a shell command without an interactive shell int channel_request_pty (CHANNEL *channel)
requests a pty int channel_request_pty_size (CHANNEL *channel, char *terminal, int col, int row)
requests a pty with a specific type and size int channel_request_shell (CHANNEL *channel)
requests a shell int channel_request_subsystem (CHANNEL *channel, char *system)
requests a subsystem (for example sftp) int channel_select (CHANNEL **readchans, CHANNEL **writechans, CHANNEL **exceptchans, struct timeval *timeout)
act as the standard select(2) for 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 nonblocking mode int channel_write (CHANNEL *channel, void *data, int 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 channel
cols new number of cols
rows 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)
int channel_close (CHANNEL * channel)
close a channel
It 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 channel
Returns:
SSH_ERROR on error
SSH_SUCCESS on success
See also:
channel_free()
channel_eof()
void channel_free (CHANNEL * channel)
close and free a channel
Parameters:
channel channel to free
Warning:
any data unread on channel will be lost
SSH_SESSION* channel_get_session (CHANNEL * channel)
recover the session in which belong a channel
Parameters:
channel channel
Returns:
the session pointer
int channel_is_closed (CHANNEL * channel)
returns if the channel is closed or not
Parameters:
channel channel
Returns:
0 if channel is opened, nonzero otherwise
See also:
channel_is_open()
int channel_is_eof (CHANNEL * channel)
returns if the remote has sent an EOF
Parameters:
channel channel
Returns:
0 if there is no EOF, nonzero otherwise
int channel_is_open (CHANNEL * channel)
returns if the channel is open or not
Parameters:
channel channel
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 ssh session
Returns:
an allocated channel. As this function doesn't speak with server, it never fails
int channel_open_forward (CHANNEL * channel, char * remotehost, int remoteport, char * sourcehost, int localport)
open a TCP/IP forwarding channel.
Parameters:
channel an allocated channel (see channel_new())
remotehost remote host to be connected (host name or IP)
remoteport remote port
sourcehost source host (your local computer). It's facultative and for logging purpose
localport source port (your local computer). It's facultative and for logging purpose
Returns:
SSH_ERROR on error
SSH_OK on success
Warning:
API changed from 0.11
int channel_open_session (CHANNEL * channel)
open a session channel (suited for a shell. Not tcp)
Parameters:
channel an allocated channel (see channel_new())
Returns:
SSH_OK on success
SSH_ERROR on error
See also:
channel_open_forward()
channel_request_env()
channel_request_shell()
channel_request_exec()
Warning:
API changed from 0.11
int channel_poll (CHANNEL * channel, int is_stderr)
polls the channel for data to read
Parameters:
channel channel
is_stderr boolean to select the stderr stream
Returns:
number of bytes available for reading
0 if nothing is available
SSH_ERROR on error
Warning:
don't forget to check for EOF as it would return 0 here
See also:
channel_is_eof()
int channel_read (CHANNEL * channel, BUFFER * buffer, int bytes, int is_stderr)
reads data from a channel
Parameters:
channel channel
buffer buffer which will get the data
bytes number 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 boolean value to mark reading from the stderr flow.
Returns:
number of bytes read
0 on end of file
SSH_ERROR on error
int channel_read_nonblocking (CHANNEL * channel, char * dest, int len, int is_stderr)
nonblocking read
This read will make a nonblocking read (unlike channel_read()) and won't force you to deal with BUFFER's
Parameters:
channel channel
dest pointer to destination for data
len maximum length of data to be read
is_stderr boolean to select the stderr stream
Returns:
number of bytes read
0 if nothing is available
SSH_ERROR on error
Warning:
don't forget to check for EOF as it would return 0 here
See also:
channel_is_eof()
int channel_request_env (CHANNEL * channel, char * name, char * value)
set the environement variables
Parameters:
channel channel
name name of the variable
value value
Returns:
SSH_SUCCESS on success
SSH_ERROR on error
Warning:
some environement variables may be refused by security
int channel_request_exec (CHANNEL * channel, char * cmd)
run a shell command without an interactive shell
it's similar to sh -c 'command'
Parameters:
channel channel
cmd command to execute (by ex. 'ls ~/ -al | grep -i reports')
Returns:
SSH_SUCCESS on success
SSH_ERROR on error
See also:
channel_request_shell()
int channel_request_pty (CHANNEL * channel)
requests a pty
Parameters:
channel channel
See also:
channel_request_pty_size()
Returns:
SSH_SUCCESS on success
SSH_ERROR on error
int channel_request_pty_size (CHANNEL * channel, char * terminal, int col, int row)
requests a pty with a specific type and size
Parameters:
channel channel
terminal terminal type ('vt100, xterm,...')
col number of cols
row number of rows
Returns:
SSH_SUCCESS on success
SSH_ERROR on error
int channel_request_shell (CHANNEL * channel)
requests a shell
Parameters:
channel
Returns:
SSH_SUCCESS on success
SSH_ERROR on error
int channel_request_subsystem (CHANNEL * channel, char * system)
requests a subsystem (for example sftp)
Parameters:
channel channel
system subsystem to request (for example sftp)
Returns:
SSH_SUCCESS on success
SSH_ERROR on error
Warning:
you normally don't have to call it to have sftp
See also:
sftp_new()
int channel_select (CHANNEL ** readchans, CHANNEL ** writechans, CHANNEL ** exceptchans, struct timeval * timeout)
act as the standard select(2) for 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, finished by a NULL
writechans a NULL pointer or an array of channel pointers, finished by a NULL
exceptchans a NULL pointer or an array of channel pointers, finished 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
it doesn't close the channel. You may still read from it but not write.
Parameters:
channel channel
Returns:
SSH_ERROR on error
SSH_SUCCESS on success
See also:
channel_close()
channel_free()
void channel_set_blocking (CHANNEL * channel, int blocking)
put the channel into nonblocking mode
Parameters:
channel channel
blocking boolean for blocking or nonblocking
Bug
This functionnality is still under development and doesn't work correctly
int channel_write (CHANNEL * channel, void * data, int len)
blocking write on channel
Parameters:
channel channel
data pointer to data to write
len length of data
Returns:
number of bytes written on success
SSH_ERROR on error
See also:
channel_read()