libssh: The SSH poll functions

libssh 0.12.1 The SSH library

Loading...
Searching...
No Matches
Functions
The SSH poll functions
The libssh API

## Functions
void | ssh_poll_init (void)
void | ssh_poll_cleanup (void)
int | ssh_poll (ssh_pollfd_t *fds, nfds_t nfds, int timeout)
ssh_poll_handle | ssh_poll_new (socket_t fd, short events, ssh_poll_callback cb, void *userdata)
| Allocate a new poll object, which could be used within a poll context.
void | ssh_poll_free (ssh_poll_handle p)
| Free a poll object.
ssh_poll_ctx | ssh_poll_get_ctx (ssh_poll_handle p)
| Get the poll context of a poll object.
short | ssh_poll_get_events (ssh_poll_handle p)
| Get the events of a poll object.
void | ssh_poll_set_events (ssh_poll_handle p, short events)
| Set the events of a poll object. The events will also be propagated to an associated poll context unless the fd is locked. In that case, only the POLLOUT can be set.
void | ssh_poll_set_fd (ssh_poll_handle p, socket_t fd)
| Set the file descriptor of a poll object. The FD will also be propagated to an associated poll context.
void | ssh_poll_add_events (ssh_poll_handle p, short events)
| Add extra events to a poll object. Duplicates are ignored. The events will also be propagated to an associated poll context.
void | ssh_poll_remove_events (ssh_poll_handle p, short events)
| Remove events from a poll object. Non-existent are ignored. The events will also be propagated to an associated poll context.
socket_t | ssh_poll_get_fd (ssh_poll_handle p)
| Get the raw socket of a poll object.
void | ssh_poll_set_callback (ssh_poll_handle p, ssh_poll_callback cb, void *userdata)
| Set the callback of a poll object.
ssh_poll_ctx | ssh_poll_ctx_new (size_t chunk_size)
| Create a new poll context. It could be associated with many poll object which are going to be polled at the same time as the poll context. You would need a single poll context per thread.
void | ssh_poll_ctx_free (ssh_poll_ctx ctx)
| Free a poll context.
int | ssh_poll_ctx_add (ssh_poll_ctx ctx, ssh_poll_handle p)
| Add a poll object to a poll context.
int | ssh_poll_ctx_add_socket (ssh_poll_ctx ctx, ssh_socket s)
| Add a socket object to a poll context.
void | ssh_poll_ctx_remove (ssh_poll_ctx ctx, ssh_poll_handle p)
| Remove a poll object from a poll context.
bool | ssh_poll_is_locked (ssh_poll_handle p)
| Returns if a poll object is locked.
int | ssh_poll_ctx_dopoll (ssh_poll_ctx ctx, int timeout)
| Poll all the sockets associated through a poll object with a poll context. If any of the events are set after the poll, the call back function of the socket will be called. This function should be called once within the program's main loop.
ssh_poll_ctx | ssh_poll_get_default_ctx (ssh_session session)
ssh_event | ssh_event_new (void)
| Create a new event context. It could be associated with many ssh_session objects and socket fd which are going to be polled at the same time as the event context. You would need a single event context per thread.
int | ssh_event_add_fd (ssh_event event, socket_t fd, short events, ssh_event_callback cb, void *userdata)
| Add a fd to the event and assign it a callback, when used in blocking mode.
int | ssh_event_add_poll (ssh_event event, ssh_poll_handle p)
| Add a poll handle to the event.
void | ssh_event_remove_poll (ssh_event event, ssh_poll_handle p)
| remove a poll handle to the event.
int | ssh_event_add_session (ssh_event event, ssh_session session)
| remove the poll handle from session and assign them to an event, when used in blocking mode.
int | ssh_event_add_connector (ssh_event event, ssh_connector connector)
| Add a connector to the SSH event loop.
int | ssh_event_dopoll (ssh_event event, int timeout)
| Poll all the sockets and sessions associated through an event object.
int | ssh_event_remove_fd (ssh_event event, socket_t fd)
| Remove a socket fd from an event context.
int | ssh_event_remove_session (ssh_event event, ssh_session session)
| Remove a session object from an event context.
int | ssh_event_remove_connector (ssh_event event, ssh_connector connector)
| Remove a connector from an event context.
void | ssh_event_free (ssh_event event)
| Free an event context.

## Detailed Description

Add a generic way to handle sockets asynchronously.

It's based on poll objects, each of which store a socket, its events and a callback, which gets called whenever an event is set. The poll objects are attached to a poll context, which should be allocated on a per thread basis.

Polling the poll context will poll all the attached poll objects and call their callbacks (handlers) if any of the socket events are set. This should be done within the main loop of an application.

## Function Documentation

## ◆ ssh_event_add_connector()

int ssh_event_add_connector | ( | ssh_event | event,
|  | ssh_connector | connector )

Add a connector to the SSH event loop.

Parameters

  [in] | event | The SSH event loop
  [in] | connector | The connector object

Returns
  SSH_OK
  SSH_ERROR in case of error

## ◆ ssh_event_add_fd()

int ssh_event_add_fd | ( | ssh_event | event,
|  | socket_t | fd,
|  | short | events,
|  | ssh_event_callback | cb,
|  | void * | userdata )

Add a fd to the event and assign it a callback, when used in blocking mode.

Parameters

  event | The ssh_event
  fd | Socket that will be polled.
  events | Poll events that will be monitored for the socket. i.e. POLLIN, POLLPRI, POLLOUT
  cb | Function to be called if any of the events are set. The prototype of cb is: int (*ssh_event_callback)(socket_t fd, int revents, void *userdata);
  userdata | Userdata to be passed to the callback function. NULL if not needed.

Returns
  SSH_OK on success SSH_ERROR on failure

## ◆ ssh_event_add_poll()

int ssh_event_add_poll | ( | ssh_event | event,
|  | ssh_poll_handle | p )

Add a poll handle to the event.

Parameters

  event | the ssh_event
  p | the poll handle

Returns
  SSH_OK on success SSH_ERROR on failure

## ◆ ssh_event_add_session()

int ssh_event_add_session | ( | ssh_event | event,
|  | ssh_session | session )

remove the poll handle from session and assign them to an event, when used in blocking mode.

Parameters

  event | The ssh_event object
  session | The session to add to the event.

Returns
  SSH_OK on success SSH_ERROR on failure

## ◆ ssh_event_dopoll()

int ssh_event_dopoll | ( | ssh_event | event,
|  | int | timeout )

Poll all the sockets and sessions associated through an event object.

If any of the events are set after the poll, the call back functions of the sessions or sockets will be called. This function should be called once within the programs main loop. In case of failure, the errno should be consulted to find more information about the failure set by underlying poll imlpementation.

Parameters

  event | The ssh_event object to poll.
  timeout | An upper limit on the time for which the poll will block, in milliseconds. Specifying a negative value means an infinite timeout. This parameter is passed to the poll() function.

Returns
  SSH_OK on success. SSH_ERROR Error happened during the poll. Check errno to get more details about why it failed. SSH_AGAIN Timeout occurred

## ◆ ssh_event_free()

void ssh_event_free | ( | ssh_event | event | ) |

Free an event context.

Parameters

  event | The ssh_event object to free. Note: you have to manually remove sessions and socket fds before freeing the event object.

## ◆ ssh_event_new()

ssh_event ssh_event_new | ( | void |  | ) |

Create a new event context. It could be associated with many ssh_session objects and socket fd which are going to be polled at the same time as the event context. You would need a single event context per thread.

Returns
  The ssh_event object on success, NULL on failure.

## ◆ ssh_event_remove_connector()

int ssh_event_remove_connector | ( | ssh_event | event,
|  | ssh_connector | connector )

Remove a connector from an event context.

Parameters

  [in] | event | The ssh_event object.
  [in] | connector | connector object to remove

Returns
  SSH_OK on success
  SSH_ERROR on failure

## ◆ ssh_event_remove_fd()

int ssh_event_remove_fd | ( | ssh_event | event,
|  | socket_t | fd )

Remove a socket fd from an event context.

Parameters

  event | The ssh_event object.
  fd | The fd to remove.

Returns
  SSH_OK on success SSH_ERROR on failure

## ◆ ssh_event_remove_poll()

void ssh_event_remove_poll | ( | ssh_event | event,
|  | ssh_poll_handle | p )

remove a poll handle to the event.

Parameters

  event | the ssh_event
  p | the poll handle

## ◆ ssh_event_remove_session()

int ssh_event_remove_session | ( | ssh_event | event,
|  | ssh_session | session )

Remove a session object from an event context.

Parameters

  event | The ssh_event object.
  session | The session to remove.

Returns
  SSH_OK on success SSH_ERROR on failure

## ◆ ssh_poll_add_events()

void ssh_poll_add_events | ( | ssh_poll_handle | p,
|  | short | events )

Add extra events to a poll object. Duplicates are ignored. The events will also be propagated to an associated poll context.

Parameters

  p | Pointer to an already allocated poll object.
  events | Poll events.

## ◆ ssh_poll_ctx_add()

int ssh_poll_ctx_add | ( | ssh_poll_ctx | ctx,
|  | ssh_poll_handle | p )

Add a poll object to a poll context.

Parameters

  ctx | Pointer to an already allocated poll context.
  p | Pointer to an already allocated poll object.

Returns
  0 on success, < 0 on error

## ◆ ssh_poll_ctx_add_socket()

int ssh_poll_ctx_add_socket | ( | ssh_poll_ctx | ctx,
|  | ssh_socket | s )

Add a socket object to a poll context.

Parameters

  ctx | Pointer to an already allocated poll context.
  s | A SSH socket handle

Returns
  0 on success, < 0 on error

## ◆ ssh_poll_ctx_dopoll()

int ssh_poll_ctx_dopoll | ( | ssh_poll_ctx | ctx,
|  | int | timeout )

Poll all the sockets associated through a poll object with a poll context. If any of the events are set after the poll, the call back function of the socket will be called. This function should be called once within the program's main loop.

Parameters

  ctx | Pointer to an already allocated poll context.
  timeout | An upper limit on the time for which ssh_poll_ctx() will block, in milliseconds. Specifying a negative value means an infinite timeout. This parameter is passed to the poll() function.

Returns
  SSH_OK No error. SSH_ERROR Error happened during the poll. SSH_AGAIN Timeout occurred

## ◆ ssh_poll_ctx_free()

void ssh_poll_ctx_free | ( | ssh_poll_ctx | ctx | ) |

Free a poll context.

Parameters

  ctx | Pointer to an already allocated poll context.

## ◆ ssh_poll_ctx_new()

ssh_poll_ctx ssh_poll_ctx_new | ( | size_t | chunk_size | ) |

Create a new poll context. It could be associated with many poll object which are going to be polled at the same time as the poll context. You would need a single poll context per thread.

Parameters

  chunk_size | The size of the memory chunk that will be allocated, when more memory is needed. This is for efficiency reasons, i.e. don't allocate memory for each new poll object, but for the next 5. Set it to 0 if you want to use the library's default value.

## ◆ ssh_poll_ctx_remove()

void ssh_poll_ctx_remove | ( | ssh_poll_ctx | ctx,
|  | ssh_poll_handle | p )

Remove a poll object from a poll context.

Parameters

  ctx | Pointer to an already allocated poll context.
  p | Pointer to an already allocated poll object.

## ◆ ssh_poll_free()

void ssh_poll_free | ( | ssh_poll_handle | p | ) |

Free a poll object.

Parameters

  p | Pointer to an already allocated poll object.

## ◆ ssh_poll_get_ctx()

ssh_poll_ctx ssh_poll_get_ctx | ( | ssh_poll_handle | p | ) |

Get the poll context of a poll object.

Parameters

  p | Pointer to an already allocated poll object.

Returns
  Poll context or NULL if the poll object isn't attached.

## ◆ ssh_poll_get_events()

short ssh_poll_get_events | ( | ssh_poll_handle | p | ) |

Get the events of a poll object.

Parameters

  p | Pointer to an already allocated poll object.

Returns
  Poll events.

## ◆ ssh_poll_get_fd()

socket_t ssh_poll_get_fd | ( | ssh_poll_handle | p | ) |

Get the raw socket of a poll object.

Parameters

  p | Pointer to an already allocated poll object.

Returns
  Raw socket.

## ◆ ssh_poll_is_locked()

bool ssh_poll_is_locked | ( | ssh_poll_handle | p | ) |

Returns if a poll object is locked.

Parameters

  p | Pointer to an already allocated poll object.

Returns
  true if the poll object is locked; false otherwise.

## ◆ ssh_poll_new()

ssh_poll_handle ssh_poll_new | ( | socket_t | fd,
|  | short | events,
|  | ssh_poll_callback | cb,
|  | void * | userdata )

Allocate a new poll object, which could be used within a poll context.

Parameters

  [in] | fd | Socket that will be polled.
  [in] | events | Poll events that will be monitored for the socket. i.e. POLLIN, POLLPRI, POLLOUT
  [in] | cb | Function to be called if any of the events are set. The prototype of cb is: int (*ssh_poll_callback)(ssh_poll_handle p, socket_t fd, int revents, void *userdata);
  [in] | userdata | Userdata to be passed to the callback function. NULL if not needed.

Returns
  A new poll object, NULL on error

## ◆ ssh_poll_remove_events()

void ssh_poll_remove_events | ( | ssh_poll_handle | p,
|  | short | events )

Remove events from a poll object. Non-existent are ignored. The events will also be propagated to an associated poll context.

Parameters

  p | Pointer to an already allocated poll object.
  events | Poll events.

## ◆ ssh_poll_set_callback()

void ssh_poll_set_callback | ( | ssh_poll_handle | p,
|  | ssh_poll_callback | cb,
|  | void * | userdata )

Set the callback of a poll object.

Parameters

  p | Pointer to an already allocated poll object.
  cb | Function to be called if any of the events are set.
  userdata | Userdata to be passed to the callback function. NULL if not needed.

## ◆ ssh_poll_set_events()

void ssh_poll_set_events | ( | ssh_poll_handle | p,
|  | short | events )

Set the events of a poll object. The events will also be propagated to an associated poll context unless the fd is locked. In that case, only the POLLOUT can be set.

Parameters

  p | Pointer to an already allocated poll object.
  events | Poll events.

## ◆ ssh_poll_set_fd()

void ssh_poll_set_fd | ( | ssh_poll_handle | p,
|  | socket_t | fd )

Set the file descriptor of a poll object. The FD will also be propagated to an associated poll context.

Parameters

  p | Pointer to an already allocated poll object.
  fd | New file descriptor.