Ssh_channel

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

---