From 398bc769cec5631bcb561d17b9c6900a5ec36b4a Mon Sep 17 00:00:00 2001 From: Éric Bischoff Date: Tue, 7 Sep 2010 09:54:42 +0200 Subject: doc: More work on the tutorial. --- doc/command.dox | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/commands.dox | 94 ---------------------------------------------------- doc/guided_tour.dox | 4 +-- doc/introduction.dox | 2 +- 4 files changed, 97 insertions(+), 97 deletions(-) create mode 100644 doc/command.dox delete mode 100644 doc/commands.dox diff --git a/doc/command.dox b/doc/command.dox new file mode 100644 index 0000000..91b74dd --- /dev/null +++ b/doc/command.dox @@ -0,0 +1,94 @@ +/** +@page command Chapter 4: Passing a remote command +@section remote_command Passing a remote command + +Previous chapter has shown how to open a full shell session, with an attached +terminal or not. If you only need to execute a command on the remote end, +you don't need all that complexity. + +The method described here is suited for executing only one remote command. +If you need to issue several commands in a row, you should consider using +a non-interactive remote shell, as explained in previous chapter. + +@see shell + + +@subsection exec_remote Executing a remote command + +The first steps for executing a remote command 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 you read the result of the remote command, you send an +end-of-file to the channel, close it, and free the memory +that it used: + +@code + ssh_channel_send_eof(channel); + ssh_channel_close(channel); + ssh_channel_free(channel); + + return SSH_OK; +} +@endcode + +*/ diff --git a/doc/commands.dox b/doc/commands.dox deleted file mode 100644 index 86cf156..0000000 --- a/doc/commands.dox +++ /dev/null @@ -1,94 +0,0 @@ -/** -@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. - -The method described here is suited for executing only one remote command. -If you need to issue several commands in a row, you should consider using -a non-interactive remote shell, as explained in previous chapter. - -@see shell - - -@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 you read the result of the remote command, you send an -end-of-file to the channel, close it, and free the memory -that it used: - -@code - ssh_channel_send_eof(channel); - ssh_channel_close(channel); - ssh_channel_free(channel); - - return SSH_OK; -} -@endcode - -*/ diff --git a/doc/guided_tour.dox b/doc/guided_tour.dox index 5f7a100..5f33724 100644 --- a/doc/guided_tour.dox +++ b/doc/guided_tour.dox @@ -356,7 +356,7 @@ int main() At this point, the authenticity of both server and client is established. Time has come to take advantage of the many possibilities offered by the SSH -protocol: execute remote commands, open remote shells, transfer files, +protocol: execute a remote command, open remote shells, transfer files, forward ports, etc. The example below shows how to execute a remote command: @@ -416,7 +416,7 @@ int show_remote_processes(ssh_session session) @endcode @see @ref opening_shell -@see @ref remote_commands +@see @ref remote_command @see @ref sftp_subsystem @see @ref scp_subsystem diff --git a/doc/introduction.dox b/doc/introduction.dox index 4c51d14..2089482 100644 --- a/doc/introduction.dox +++ b/doc/introduction.dox @@ -35,7 +35,7 @@ Table of contents: @subpage shell -@subpage commands +@subpage command @subpage sftp -- cgit