The SSH scp functions

Overview

SCP protocol over SSH functions. More…

// global functions

int
ssh_scp_accept_request(ssh_scp scp);

int
ssh_scp_close(ssh_scp scp);

int
ssh_scp_deny_request(
    ssh_scp scp,
    const char* reason
);

void
ssh_scp_free(ssh_scp scp);

int
ssh_scp_init(ssh_scp scp);

int
ssh_scp_leave_directory(ssh_scp scp);

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

int
ssh_scp_pull_request(ssh_scp scp);

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

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

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

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

const char*
ssh_scp_request_get_filename(ssh_scp scp);

int
ssh_scp_request_get_permissions(ssh_scp scp);

size_t
ssh_scp_request_get_size(ssh_scp scp);

uint64_t
ssh_scp_request_get_size64(ssh_scp scp);

const char*
ssh_scp_request_get_warning(ssh_scp scp);

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

int
ssh_scp_integer_mode(const char* mode);

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

char*
ssh_scp_string_mode(int mode);

int
ssh_scp_response(
    ssh_scp scp,
    char** response
);

Detailed Documentation

SCP protocol over SSH functions.

Global Functions

int
ssh_scp_accept_request(ssh_scp scp)

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

Parameters:

scp	The scp handle.

Returns:

SSH_OK if the message was sent, SSH_ERROR if sending the message failed, or sending it in a bad state.

int
ssh_scp_close(ssh_scp scp)

Close the scp channel.

Parameters:

scp	The scp context to close.

Returns:

SSH_OK on success or an SSH error code.

See also:

ssh_scp_init()

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:

scp	The scp handle.
reason	A 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.

void
ssh_scp_free(ssh_scp scp)

Free a scp context.

Parameters:

scp	The context to free.

See also:

ssh_scp_new()

int
ssh_scp_init(ssh_scp scp)

Initialize the scp channel.

Parameters:

scp	The scp context to initialize.

Returns:

SSH_OK on success or an SSH error code.

See also:

ssh_scp_new()

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()

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

Create a new scp session.

Parameters:

session	The SSH session to use.
mode	One 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.
location	The 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.

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()

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

Create a directory in a scp in sink mode.

Parameters:

scp	The scp handle.
dirname	The name of the directory being created.
mode	The 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()

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

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

Parameters:

scp	The scp handle.
filename	The name of the file being sent. It should not contain any path indicator
size	Exact size in bytes of the file being sent.
mode	The 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.

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

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

Parameters:

scp	The scp handle.
filename	The name of the file being sent. It should not contain any path indicator
size	Exact size in bytes of the file being sent.
mode	The 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()

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

Read from a remote scp file.

Parameters:

scp	The scp handle.
buffer	The destination buffer.
size	The size of the buffer.

Returns:

The nNumber of bytes read, SSH_ERROR if an error occured while reading.

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.

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.

size_t
ssh_scp_request_get_size(ssh_scp scp)

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

Warning

The real size may not fit in a 32 bits field and may be truncated.

Returns:

The numeric size of the file being read.

See also:

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.

const char*
ssh_scp_request_get_warning(ssh_scp scp)

Get the warning string from a scp handle.

Parameters:

scp	The scp handle.

Returns:

A warning string, or NULL on error. The string should not be freed.

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

Write into a remote scp file.

Parameters:

scp	The scp handle.
buffer	The buffer to write.
len	The number of bytes to write.

Returns:

SSH_OK if the write was successful, SSH_ERROR an error occured while writing.

int
ssh_scp_integer_mode(const char* mode)

Convert a scp text mode to an integer.

Parameters:

mode	The mode to convert, e.g. “0644”.

Returns:

An integer value, e.g. 420 for “0644”.

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

Read a string on a channel, terminated by ‘

‘.

Parameters:

scp	The scp handle.
buffer	A pointer to a buffer to place the string.
len	The 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.

char*
ssh_scp_string_mode(int mode)

Convert a unix mode into a scp string.

Parameters:

mode	The mode to convert, e.g. 420 or 0644.

Returns:

A pointer to a malloc’ed string containing the scp mode, e.g. “0644”.