lib/libssh
1
0
Fork 0
mirror of https://git.libssh.org/projects/libssh.git synced 2025-08-05 20:55:46 +03:00
Code Activity

sftp.dox: Remove references of old sftp async API

Browse Source 
This commit removes the references of the old async sftp API from the
libssh sftp tutorial because the old async API is to be deprecated and
replaced by the sftp aio API.

Signed-off-by: Eshan Kelkar <eshankelkar@galorithm.com>
Reviewed-by: Sahana Prasad <sahana@redhat.com>
Reviewed-by: Jakub Jelen <jjelen@redhat.com>
This commit is contained in:
Eshan Kelkar
2023-09-16 19:43:22 +05:30
committed by Sahana Prasad
parent c0a76cf9b1
commit 677d1e1d10
1 changed files with 31 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
doc/sftp.dox
View File

@@ -203,16 +203,14 @@ int sftp_helloworld(ssh_session session, sftp_session sftp)
@subsection sftp_read Reading a file from the remote computer @subsection sftp_read Reading a file from the remote computer
The nice thing with reading a file over the network through SFTP is that it A synchronous read from a remote file is done using sftp_read(). This
can be done both in a synchronous way or an asynchronous way. If you read the file section describes how to download a remote file using sftp_read(). The
asynchronously, your program can do something else while it waits for the next section will discuss more about synchronous/asynchronous read/write
results to come. operations using libssh sftp API.
Synchronous read is done with sftp_read().
Files are normally transferred in chunks. A good chunk size is 16 KB. The following Files are normally transferred in chunks. A good chunk size is 16 KB. The following
example transfers the remote file "/etc/profile" in 16 KB chunks. For each chunk we example transfers the remote file "/etc/profile" in 16 KB chunks. For each chunk we
request, sftp_read blocks till the data has been received: request, sftp_read() blocks till the data has been received:
@code @code
// Good chunk size // Good chunk size
@@ -273,87 +271,39 @@ int sftp_read_sync(ssh_session session, sftp_session sftp)
} }
@endcode @endcode
Asynchronous read is done in two steps, first sftp_async_read_begin(), which @subsection sftp_aio Performing an asynchronous read/write on a file on the remote computer
returns a "request handle", and then sftp_async_read(), which uses that request handle.
If the file has been opened in nonblocking mode, then sftp_async_read()
might return SSH_AGAIN, which means that the request hasn't completed yet
and that the function should be called again later on. Otherwise,
sftp_async_read() waits for the data to come. To open a file in nonblocking mode,
call sftp_file_set_nonblocking() right after you opened it. Default is blocking mode.
The example below reads a very big file in asynchronous, nonblocking, mode. Each sftp_read() performs a "synchronous" read operation on a remote file.
time the data is not ready yet, a counter is incremented. This means that sftp_read() will first request the server to read some
data from the remote file and then would wait until the server response
containing data to read (or an error) arrives at the client side.
@code sftp_write() performs a "synchronous" write operation on a remote file.
// Good chunk size This means that sftp_write() will first request the server to write some
#define MAX_XFER_BUF_SIZE 16384 data to the remote file and then would wait until the server response
containing information about the status of the write operation arrives at the
client side.
int sftp_read_async(ssh_session session, sftp_session sftp) If your client program wants to do something other than waiting for the
{ response after requesting a read/write, the synchronous sftp_read() and
int access_type; sftp_write() can't be used. In such a case the "asynchronous" sftp aio API
sftp_file file; should be used.
char buffer[MAX_XFER_BUF_SIZE];
int async_request;
int nbytes;
long counter;
int rc;
access_type = O_RDONLY; Please go through @ref libssh_tutor_sftp_aio for a detailed description
file = sftp_open(sftp, "some_very_big_file", of the sftp aio API.
access_type, 0);
if (file == NULL) {
fprintf(stderr, "Can't open file for reading: %s\n",
ssh_get_error(session));
return SSH_ERROR;
}
sftp_file_set_nonblocking(file);
async_request = sftp_async_read_begin(file, sizeof(buffer)); The sftp aio API provides two categories of functions :
counter = 0L; - sftp_aio_begin_*() : For requesting a read/write from the server.
usleep(10000); - sftp_aio_wait_*() : For waiting for the response of a previously
if (async_request >= 0) { issued read/write request from the server.
nbytes = sftp_async_read(file, buffer, sizeof(buffer),
async_request);
} else {
nbytes = -1;
}
while (nbytes > 0 || nbytes == SSH_AGAIN) { Hence, the client program can call sftp_aio_begin_*() to request a read/write
if (nbytes > 0) { and then can perform any number of operations (other than waiting) before
write(1, buffer, nbytes); calling sftp_aio_wait_*() for waiting for the response of the previously
async_request = sftp_async_read_begin(file, sizeof(buffer)); issued request.
} else {
counter++;
}
usleep(10000);
if (async_request >= 0) { We call read/write operations performed in the manner described above as
nbytes = sftp_async_read(file, buffer, sizeof(buffer), "asynchronous" read/write operations on a remote file.
async_request);
} else {
nbytes = -1;
}
}
if (nbytes < 0) {
fprintf(stderr, "Error while reading file: %s\n",
ssh_get_error(session));
sftp_close(file);
return SSH_ERROR;
}
printf("The counter has reached value: %ld\n", counter);
rc = sftp_close(file);
if (rc != SSH_OK) {
fprintf(stderr, "Can't close the read file: %s\n",
ssh_get_error(session));
return rc;
}
return SSH_OK;
}
@endcode
@subsection sftp_ls Listing the contents of a directory @subsection sftp_ls Listing the contents of a directory