libssh  0.7.90
Functions
The SSH scp functions

SCP protocol over SSH functions. More...

Functions

int ssh_scp_accept_request (ssh_scp scp)
 Accepts transfer of a file or creation of a directory coming from the remote party. More...
 
int ssh_scp_close (ssh_scp scp)
 Close the scp channel. More...
 
int ssh_scp_deny_request (ssh_scp scp, const char *reason)
 Deny the transfer of a file or creation of a directory coming from the remote party. More...
 
void ssh_scp_free (ssh_scp scp)
 Free a scp context. More...
 
int ssh_scp_init (ssh_scp scp)
 Initialize the scp channel. More...
 
int ssh_scp_integer_mode (const char *mode)
 Convert a scp text mode to an integer. More...
 
int ssh_scp_leave_directory (ssh_scp scp)
 Leave a directory. More...
 
ssh_scp ssh_scp_new (ssh_session session, int mode, const char *location)
 Create a new scp session. More...
 
int ssh_scp_pull_request (ssh_scp scp)
 Wait for a scp request (file, directory). More...
 
int ssh_scp_push_directory (ssh_scp scp, const char *dirname, int mode)
 Create a directory in a scp in sink mode. More...
 
int ssh_scp_push_file (ssh_scp scp, const char *filename, size_t size, int mode)
 Initialize the sending of a file to a scp in sink mode. More...
 
int ssh_scp_push_file64 (ssh_scp scp, const char *filename, uint64_t size, int mode)
 Initialize the sending of a file to a scp in sink mode, using a 64-bit size. More...
 
int ssh_scp_read (ssh_scp scp, void *buffer, size_t size)
 Read from a remote scp file. More...
 
int ssh_scp_read_string (ssh_scp scp, char *buffer, size_t len)
 Read a string on a channel, terminated by '
'. More...
 
const char * ssh_scp_request_get_filename (ssh_scp scp)
 Get the name of the directory or file being pushed from the other party. More...
 
int ssh_scp_request_get_permissions (ssh_scp scp)
 Get the permissions of the directory or file being pushed from the other party. More...
 
size_t ssh_scp_request_get_size (ssh_scp scp)
 Get the size of the file being pushed from the other party. More...
 
uint64_t ssh_scp_request_get_size64 (ssh_scp scp)
 Get the size of the file being pushed from the other party. More...
 
const char * ssh_scp_request_get_warning (ssh_scp scp)
 Get the warning string from a scp handle. More...
 
char * ssh_scp_string_mode (int mode)
 Convert a unix mode into a scp string. More...
 
int ssh_scp_write (ssh_scp scp, const void *buffer, size_t len)
 Write into a remote scp file. More...
 

Detailed Description

SCP protocol over SSH functions.

Function Documentation

◆ ssh_scp_accept_request()

int ssh_scp_accept_request ( ssh_scp  scp)

Accepts transfer of a file or creation of a directory coming from the remote party.

Parameters
[in]scpThe scp handle.
Returns
SSH_OK if the message was sent, SSH_ERROR if sending the message failed, or sending it in a bad state.

References ssh_channel_write().

Referenced by ssh_scp_read().

◆ ssh_scp_close()

int ssh_scp_close ( ssh_scp  scp)

Close the scp channel.

Parameters
[in]scpThe scp context to close.
Returns
SSH_OK on success or an SSH error code.
See also
ssh_scp_init()

References ssh_channel_close(), ssh_channel_free(), ssh_channel_is_eof(), ssh_channel_read(), and ssh_channel_send_eof().

Referenced by ssh_scp_free().

◆ ssh_scp_deny_request()

int ssh_scp_deny_request ( ssh_scp  scp,
const char *  reason 
)

Deny the transfer of a file or creation of a directory coming from the remote party.

Parameters
[in]scpThe scp handle.
[in]reasonA nul-terminated string with a human-readable explanation of the deny.
Returns
SSH_OK if the message was sent, SSH_ERROR if the sending the message failed, or sending it in a bad state.

References ssh_channel_write().

◆ ssh_scp_free()

void ssh_scp_free ( ssh_scp  scp)

Free a scp context.

Parameters
[in]scpThe context to free.
See also
ssh_scp_new()

References ssh_channel_free(), and ssh_scp_close().

Referenced by ssh_scp_new().

◆ ssh_scp_init()

int ssh_scp_init ( ssh_scp  scp)

Initialize the scp channel.

Parameters
[in]scpThe scp context to initialize.
Returns
SSH_OK on success or an SSH error code.
See also
ssh_scp_new()

References ssh_channel_new(), ssh_channel_open_session(), ssh_channel_read(), ssh_channel_request_exec(), ssh_channel_write(), ssh_get_error(), and SSH_LOG_PROTOCOL.

◆ ssh_scp_integer_mode()

int ssh_scp_integer_mode ( const char *  mode)

Convert a scp text mode to an integer.

Parameters
[in]modeThe mode to convert, e.g. "0644".
Returns
An integer value, e.g. 420 for "0644".

Referenced by ssh_scp_pull_request().

◆ ssh_scp_leave_directory()

int ssh_scp_leave_directory ( ssh_scp  scp)

Leave a directory.

Returns
SSH_OK if the directory has been left,SSH_ERROR if an error occured.
See also
ssh_scp_push_directory()

References ssh_channel_read(), ssh_channel_write(), and ssh_get_error().

◆ ssh_scp_new()

ssh_scp ssh_scp_new ( ssh_session  session,
int  mode,
const char *  location 
)

Create a new scp session.

Parameters
[in]sessionThe SSH session to use.
[in]modeOne of SSH_SCP_WRITE or SSH_SCP_READ, depending if you need to drop files remotely or read them. It is not possible to combine read and write. SSH_SCP_RECURSIVE Flag can be or'ed to this to indicate that you're going to use recursion. Browsing through directories is not possible without this.
[in]locationThe directory in which write or read will be done. Any push or pull will be relative to this place. This can also be a pattern of files to download (read).
Returns
A ssh_scp handle, NULL if the creation was impossible.

References ssh_scp_free().

◆ ssh_scp_pull_request()

int ssh_scp_pull_request ( ssh_scp  scp)

Wait for a scp request (file, directory).

Returns
SSH_SCP_REQUEST_NEWFILE: The other side is sending a file SSH_SCP_REQUEST_NEWDIR: The other side is sending a directory SSH_SCP_REQUEST_ENDDIR: The other side has finished with the current directory SSH_SCP_REQUEST_WARNING: The other side sent us a warning SSH_SCP_REQUEST_EOF: The other side finished sending us files and data. SSH_ERROR: Some error happened
See also
ssh_scp_read()
ssh_scp_deny_request()
ssh_scp_accept_request()
ssh_scp_request_get_warning()

References ssh_channel_is_eof(), ssh_channel_write(), SSH_LOG_PROTOCOL, ssh_scp_integer_mode(), and ssh_scp_read_string().

◆ ssh_scp_push_directory()

int ssh_scp_push_directory ( ssh_scp  scp,
const char *  dirname,
int  mode 
)

Create a directory in a scp in sink mode.

Parameters
[in]scpThe scp handle.
[in]dirnameThe name of the directory being created.
[in]modeThe UNIX permissions for the new directory, e.g. 0755.
Returns
SSH_OK if the directory has been created, SSH_ERROR if an error occured.
See also
ssh_scp_leave_directory()

References ssh_basename(), ssh_channel_read(), ssh_channel_write(), ssh_get_error(), and ssh_scp_string_mode().

◆ ssh_scp_push_file()

int ssh_scp_push_file ( ssh_scp  scp,
const char *  filename,
size_t  size,
int  mode 
)

Initialize the sending of a file to a scp in sink mode.

Parameters
[in]scpThe scp handle.
[in]filenameThe name of the file being sent. It should not contain any path indicator
[in]sizeExact size in bytes of the file being sent.
[in]modeThe UNIX permissions for the new file, e.g. 0644.
Returns
SSH_OK if the file is ready to be sent, SSH_ERROR if an error occured.

References ssh_scp_push_file64().

◆ ssh_scp_push_file64()

int ssh_scp_push_file64 ( ssh_scp  scp,
const char *  filename,
uint64_t  size,
int  mode 
)

Initialize the sending of a file to a scp in sink mode, using a 64-bit size.

Parameters
[in]scpThe scp handle.
[in]filenameThe name of the file being sent. It should not contain any path indicator
[in]sizeExact size in bytes of the file being sent.
[in]modeThe UNIX permissions for the new file, e.g. 0644.
Returns
SSH_OK if the file is ready to be sent, SSH_ERROR if an error occured.
See also
ssh_scp_push_file()

References ssh_basename(), ssh_channel_read(), ssh_channel_write(), ssh_get_error(), SSH_LOG_PROTOCOL, and ssh_scp_string_mode().

Referenced by ssh_scp_push_file().

◆ ssh_scp_read()

int ssh_scp_read ( ssh_scp  scp,
void *  buffer,
size_t  size 
)

Read from a remote scp file.

Parameters
[in]scpThe scp handle.
[in]bufferThe destination buffer.
[in]sizeThe size of the buffer.
Returns
The nNumber of bytes read, SSH_ERROR if an error occured while reading.

References ssh_channel_read(), ssh_channel_write(), and ssh_scp_accept_request().

◆ ssh_scp_read_string()

int ssh_scp_read_string ( ssh_scp  scp,
char *  buffer,
size_t  len 
)

Read a string on a channel, terminated by '
'.

Parameters
[in]scpThe scp handle.
[out]bufferA pointer to a buffer to place the string.
[in]lenThe size of the buffer in bytes. If the string is bigger than len-1, only len-1 bytes are read and the string is null-terminated.
Returns
SSH_OK if the string was read, SSH_ERROR if an error occured while reading.

References ssh_channel_read().

Referenced by ssh_scp_pull_request().

◆ ssh_scp_request_get_filename()

const char* ssh_scp_request_get_filename ( ssh_scp  scp)

Get the name of the directory or file being pushed from the other party.

Returns
The file name, NULL on error. The string should not be freed.

◆ ssh_scp_request_get_permissions()

int ssh_scp_request_get_permissions ( ssh_scp  scp)

Get the permissions of the directory or file being pushed from the other party.

Returns
The UNIX permission, e.g 0644, -1 on error.

◆ ssh_scp_request_get_size()

size_t ssh_scp_request_get_size ( ssh_scp  scp)

Get the size of the file being pushed from the other party.

Returns
The numeric size of the file being read.
Warning
The real size may not fit in a 32 bits field and may be truncated.
See also
ssh_scp_request_get_size64()

◆ ssh_scp_request_get_size64()

uint64_t ssh_scp_request_get_size64 ( ssh_scp  scp)

Get the size of the file being pushed from the other party.

Returns
The numeric size of the file being read.

◆ ssh_scp_request_get_warning()

const char* ssh_scp_request_get_warning ( ssh_scp  scp)

Get the warning string from a scp handle.

Parameters
[in]scpThe scp handle.
Returns
A warning string, or NULL on error. The string should not be freed.

◆ ssh_scp_string_mode()

char* ssh_scp_string_mode ( int  mode)

Convert a unix mode into a scp string.

Parameters
[in]modeThe mode to convert, e.g. 420 or 0644.
Returns
A pointer to a malloc'ed string containing the scp mode, e.g. "0644".

Referenced by ssh_scp_push_directory(), and ssh_scp_push_file64().

◆ ssh_scp_write()

int ssh_scp_write ( ssh_scp  scp,
const void *  buffer,
size_t  len 
)

Write into a remote scp file.

Parameters
[in]scpThe scp handle.
[in]bufferThe buffer to write.
[in]lenThe number of bytes to write.
Returns
SSH_OK if the write was successful, SSH_ERROR an error occured while writing.

References ssh_channel_poll(), ssh_channel_read(), and ssh_channel_write().