---
name: "ssh_channel"
section: "3"
platform: "linux"
package: "libssh-2-doc"
version: "0.2+svn20070321-4"
release: "Debian 5.0 (Lenny)"
platforms: ["linux"]
url: "https://new.carta.tech/ssh_channel"
---

# ssh\_channel(3)

functions that manage a 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)](/select/2.md) 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)](/select/2.md) 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)](/select/2.md)

**Returns:**

SSH\_SUCCESS operation successful\
\
  SSH\_EINTR [select(2)](/select/2.md) 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()**