libssh/doc/commands.dox

/**
@page commands Chapter 4: Passing remote commands
@section remote_commands Passing remote commands

Previous chapter has shown how to open a full shell session, with an attached
terminal or not. If you only need to execute commands on the remote end,
you don't need all that complexity.

@subsection exec_remote Executing remote commands

The first steps for executing remote commands are identical to those
for opening remote shells. You first need a SSH channel, and then
a SSH session that uses this channel:

@code
int show_remote_files(ssh_session session)
{
  ssh_channel channel;
  int rc;

  channel = ssh_channel_new(session);
  if (channel == NULL) return SSH_ERROR;

  rc = ssh_channel_open_session(channel);
  if (rc != SSH_OK)
  {
    ssh_channel_free(channel);
    return rc;
  }
@endcode

Once a session is open, you can start the remote command with
ssh_channel_request_exec():

@code
  rc = ssh_channel_request_exec(channel, "ls -l");
  if (rc != SSH_OK)
  {
    ssh_channel_close(channel);
    ssh_channel_free(channel);
    return rc;
  }
@endcode

If the remote command displays data, you get them with ssh_channel_read().
This function returns the number of bytes read. If there is no more
data to read on the channel, this function returns 0, and you can go to next step.
If an error has been encountered, it returns a negative value:

@code
  char buffer[256];
  unsigned int nbytes;

  nbytes = ssh_channel_read(channel, buffer, sizeof(buffer), 0);
  while (nbytes > 0)
  {
    if (write(1, buffer, nbytes) != nbytes)
    {
      ssh_channel_close(channel);
      ssh_channel_free(channel);
      return SSH_ERROR;
    }
    nbytes = ssh_channel_read(channel, buffer, sizeof(buffer), 0);
  }
    
  if (nbytes < 0)
  {
    ssh_channel_close(channel);
    ssh_channel_free(channel);
    return SSH_ERROR;
  }
@endcode

Once there are no more remote commands to execute, you can send an
end-of-file to the channel, close it, and free the memory it used:

@code
  ssh_channel_send_eof(channel);
  ssh_channel_close(channel);
  ssh_channel_free(channel);

  return SSH_OK;
}
@endcode

*/