libssh: The SSH scp functions

libssh 0.9.4 The SSH library

Functions
The SSH scp functions
The libssh API

## Functions
ssh_scp | ssh_scp_new (ssh_session session, int mode, const char *location)
| Create a new scp session. More...
int | ssh_scp_init (ssh_scp scp)
| Initialize the scp channel. More...
int | ssh_scp_close (ssh_scp scp)
| Close the scp channel. More...
void | ssh_scp_free (ssh_scp scp)
| Free a scp context. 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_leave_directory (ssh_scp scp)
| Leave a directory. 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_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_response (ssh_scp scp, char **response)
int | ssh_scp_write (ssh_scp scp, const void *buffer, size_t len)
| Write into 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...
int | ssh_scp_pull_request (ssh_scp scp)
| Wait for a scp request (file, directory). 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...
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_read (ssh_scp scp, void *buffer, size_t size)
| Read from a remote scp file. 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...
int | ssh_scp_integer_mode (const char *mode)
| Convert a scp text mode to an integer. More...
char * | ssh_scp_string_mode (int mode)
| Convert a unix mode into a scp string. More...
const char * | ssh_scp_request_get_warning (ssh_scp scp)
| Get the warning string from a scp handle. 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] | 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.

## ◆ ssh_scp_close()

int ssh_scp_close | ( | ssh_scp | scp | ) |

Close the scp channel.

Parameters

  [in] | scp | The scp context to close.

Returns
  SSH_OK on success or an SSH error code.

See also
  ssh_scp_init()

## ◆ 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] | scp | The scp handle.
  [in] | 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.

## ◆ ssh_scp_free()

void ssh_scp_free | ( | ssh_scp | scp | ) |

Free a scp context.

Parameters

  [in] | scp | The context to free.

See also
  ssh_scp_new()

## ◆ ssh_scp_init()

int ssh_scp_init | ( | ssh_scp | scp | ) |

Initialize the scp channel.

Parameters

  [in] | scp | The scp context to initialize.

Returns
  SSH_OK on success or an SSH error code.

See also
  ssh_scp_new()

## ◆ ssh_scp_integer_mode()

int ssh_scp_integer_mode | ( | const char * | mode | ) |

Convert a scp text mode to an integer.

Parameters

  [in] | mode | The mode to convert, e.g. "0644".

Returns
  An integer value, e.g. 420 for "0644".

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

## ◆ ssh_scp_new()

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

Create a new scp session.

Parameters

  [in] | session | The SSH session to use.
  [in] | 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.
  [in] | 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.

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

## ◆ 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] | scp | The scp handle.
  [in] | dirname | The name of the directory being created.
  [in] | 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()

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

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

## ◆ ssh_scp_read()

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

Read from a remote scp file.

Parameters

  [in] | scp | The scp handle.
  [in] | buffer | The destination buffer.
  [in] | size | The size of the buffer.

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

## ◆ 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] | scp | The scp handle.
  [out] | buffer | A pointer to a buffer to place the string.
  [in] | 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.

## ◆ 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] | scp | The 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] | 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".

## ◆ ssh_scp_write()

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

Write into a remote scp file.

Parameters

  [in] | scp | The scp handle.
  [in] | buffer | The buffer to write.
  [in] | len | The number of bytes to write.

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