Linux Certif

Toute la documentation sur la certification Linux LPI

ssh_channel

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

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