ssh_channel(3)

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()

docs.sk

comprehensive documentation repository

See also

ssh_channel(3)

NAME

Detailed Description

Function Documentation