libssh
0.7
|
SFTP handling functions. More...
Data Structures | |
struct | sftp_statvfs_t |
SFTP statvfs structure. More... | |
Functions | |
int | sftp_async_read (sftp_file file, void *data, uint32_t len, uint32_t id) |
Wait for an asynchronous read to complete and save the data. More... | |
int | sftp_async_read_begin (sftp_file file, uint32_t len) |
Start an asynchronous read from a file using an opened sftp file handle. More... | |
void | sftp_attributes_free (sftp_attributes file) |
Free a sftp attribute structure. More... | |
char * | sftp_canonicalize_path (sftp_session sftp, const char *path) |
Canonicalize a sftp path. More... | |
int | sftp_chmod (sftp_session sftp, const char *file, mode_t mode) |
Change permissions of a file. More... | |
int | sftp_chown (sftp_session sftp, const char *file, uid_t owner, gid_t group) |
Change the file owner and group. More... | |
int | sftp_close (sftp_file file) |
Close an open file handle. More... | |
int | sftp_closedir (sftp_dir dir) |
Close a directory handle opened by sftp_opendir(). More... | |
int | sftp_dir_eof (sftp_dir dir) |
Tell if the directory has reached EOF (End Of File). More... | |
int | sftp_extension_supported (sftp_session sftp, const char *name, const char *data) |
Check if the given extension is supported. More... | |
unsigned int | sftp_extensions_get_count (sftp_session sftp) |
Get the count of extensions provided by the server. More... | |
const char * | sftp_extensions_get_data (sftp_session sftp, unsigned int indexn) |
Get the data of the extension provided by the server. More... | |
const char * | sftp_extensions_get_name (sftp_session sftp, unsigned int indexn) |
Get the name of the extension provided by the server. More... | |
void | sftp_file_set_blocking (sftp_file handle) |
Make the sftp communication for this file handle blocking. More... | |
void | sftp_file_set_nonblocking (sftp_file handle) |
Make the sftp communication for this file handle non blocking. More... | |
void | sftp_free (sftp_session sftp) |
Close and deallocate a sftp session. More... | |
sftp_attributes | sftp_fstat (sftp_file file) |
Get information about a file or directory from a file handle. More... | |
sftp_statvfs_t | sftp_fstatvfs (sftp_file file) |
Get information about a mounted file system. More... | |
int | sftp_get_error (sftp_session sftp) |
Get the last sftp error. More... | |
int | sftp_init (sftp_session sftp) |
Initialize the sftp session with the server. More... | |
sftp_attributes | sftp_lstat (sftp_session session, const char *path) |
Get information about a file or directory. More... | |
int | sftp_mkdir (sftp_session sftp, const char *directory, mode_t mode) |
Create a directory. More... | |
sftp_session | sftp_new (ssh_session session) |
Start a new sftp session. More... | |
sftp_session | sftp_new_channel (ssh_session session, ssh_channel channel) |
Start a new sftp session with an existing channel. More... | |
sftp_file | sftp_open (sftp_session session, const char *file, int accesstype, mode_t mode) |
Open a file on the server. More... | |
sftp_dir | sftp_opendir (sftp_session session, const char *path) |
Open a directory used to obtain directory entries. More... | |
ssize_t | sftp_read (sftp_file file, void *buf, size_t count) |
Read from a file using an opened sftp file handle. More... | |
sftp_attributes | sftp_readdir (sftp_session session, sftp_dir dir) |
Get a single file attributes structure of a directory. More... | |
char * | sftp_readlink (sftp_session sftp, const char *path) |
Read the value of a symbolic link. More... | |
int | sftp_rename (sftp_session sftp, const char *original, const char *newname) |
Rename or move a file or directory. More... | |
void | sftp_rewind (sftp_file file) |
Rewinds the position of the file pointer to the beginning of the file. More... | |
int | sftp_rmdir (sftp_session sftp, const char *directory) |
Remove a directoy. More... | |
int | sftp_seek (sftp_file file, uint32_t new_offset) |
Seek to a specific location in a file. More... | |
int | sftp_seek64 (sftp_file file, uint64_t new_offset) |
Seek to a specific location in a file. More... | |
int | sftp_server_init (sftp_session sftp) |
Intialize the sftp server. More... | |
sftp_session | sftp_server_new (ssh_session session, ssh_channel chan) |
Create a new sftp server session. More... | |
int | sftp_server_version (sftp_session sftp) |
Get the version of the SFTP protocol supported by the server. More... | |
int | sftp_setstat (sftp_session sftp, const char *file, sftp_attributes attr) |
Set file attributes on a file, directory or symbolic link. More... | |
sftp_attributes | sftp_stat (sftp_session session, const char *path) |
Get information about a file or directory. More... | |
sftp_statvfs_t | sftp_statvfs (sftp_session sftp, const char *path) |
Get information about a mounted file system. More... | |
void | sftp_statvfs_free (sftp_statvfs_t statvfs_o) |
Free the memory of an allocated statvfs. More... | |
int | sftp_symlink (sftp_session sftp, const char *target, const char *dest) |
Create a symbolic link. More... | |
unsigned long | sftp_tell (sftp_file file) |
Report current byte position in file. More... | |
uint64_t | sftp_tell64 (sftp_file file) |
Report current byte position in file. More... | |
int | sftp_unlink (sftp_session sftp, const char *file) |
Unlink (delete) a file. More... | |
int | sftp_utimes (sftp_session sftp, const char *file, const struct timeval *times) |
Change the last modification and access time of a file. More... | |
ssize_t | sftp_write (sftp_file file, const void *buf, size_t count) |
Write to a file using an opened sftp file handle. More... | |
Server responses | |
#define | SSH_FX_OK 0 |
No error. | |
#define | SSH_FX_EOF 1 |
End-of-file encountered. | |
#define | SSH_FX_NO_SUCH_FILE 2 |
File doesn't exist. | |
#define | SSH_FX_PERMISSION_DENIED 3 |
Permission denied. | |
#define | SSH_FX_FAILURE 4 |
Generic failure. | |
#define | SSH_FX_BAD_MESSAGE 5 |
Garbage received from server. | |
#define | SSH_FX_NO_CONNECTION 6 |
No connection has been set up. | |
#define | SSH_FX_CONNECTION_LOST 7 |
There was a connection, but we lost it. | |
#define | SSH_FX_OP_UNSUPPORTED 8 |
Operation not supported by the server. | |
#define | SSH_FX_INVALID_HANDLE 9 |
Invalid file handle. | |
#define | SSH_FX_NO_SUCH_PATH 10 |
No such file or directory path exists. | |
#define | SSH_FX_FILE_ALREADY_EXISTS 11 |
An attempt to create an already existing file or directory has been made. | |
#define | SSH_FX_WRITE_PROTECT 12 |
We are trying to write on a write-protected filesystem. | |
#define | SSH_FX_NO_MEDIA 13 |
No media in remote drive. | |
SFTP handling functions.
SFTP commands are channeled by the ssh sftp subsystem. Every packet is sent/read using a sftp_packet type structure. Related to these packets, most of the server answers are messages having an ID and a message specific part. It is described by sftp_message when reading a message, the sftp system puts it into the queue, so the process having asked for it can fetch it, while continuing to read for other messages (it is unspecified in which order messages may be sent back to the client
int sftp_async_read | ( | sftp_file | file, |
void * | data, | ||
uint32_t | len, | ||
uint32_t | id | ||
) |
Wait for an asynchronous read to complete and save the data.
file | The opened sftp file handle to be read from. |
data | Pointer to buffer to recieve read data. |
len | Size of the buffer in bytes. It should be bigger or equal to the length parameter of the sftp_async_read_begin() call. |
id | The identifier returned by the sftp_async_read_begin() function. |
References ssh_channel_poll(), SSH_FX_EOF, ssh_string_data(), ssh_string_free(), and ssh_string_len().
int sftp_async_read_begin | ( | sftp_file | file, |
uint32_t | len | ||
) |
Start an asynchronous read from a file using an opened sftp file handle.
Its goal is to avoid the slowdowns related to the request/response pattern of a synchronous read. To do so, you must call 2 functions:
sftp_async_read_begin() and sftp_async_read().
The first step is to call sftp_async_read_begin(). This function returns a request identifier. The second step is to call sftp_async_read() using the returned identifier.
file | The opened sftp file handle to be read from. |
len | Size to read in bytes. |
References ssh_buffer_free(), and ssh_buffer_new().
void sftp_attributes_free | ( | sftp_attributes | file | ) |
Free a sftp attribute structure.
file | The sftp attribute structure to free. |
References ssh_string_free().
char* sftp_canonicalize_path | ( | sftp_session | sftp, |
const char * | path | ||
) |
Canonicalize a sftp path.
sftp | The sftp session handle. |
path | The path to be canonicalized. |
References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), ssh_string_from_char(), and ssh_string_to_char().
int sftp_chmod | ( | sftp_session | sftp, |
const char * | file, | ||
mode_t | mode | ||
) |
Change permissions of a file.
sftp | The sftp session handle. |
file | The file which owner and group should be changed. |
mode | Specifies the permissions to use. It is modified by the process's umask in the usual way: The permissions of the created file are (mode & ~umask) |
References sftp_setstat().
int sftp_chown | ( | sftp_session | sftp, |
const char * | file, | ||
uid_t | owner, | ||
gid_t | group | ||
) |
Change the file owner and group.
sftp | The sftp session handle. |
file | The file which owner and group should be changed. |
owner | The new owner which should be set. |
group | The new group which should be set. |
References sftp_setstat().
int sftp_close | ( | sftp_file | file | ) |
Close an open file handle.
file | The open sftp file handle to close. |
References ssh_string_free().
int sftp_closedir | ( | sftp_dir | dir | ) |
Close a directory handle opened by sftp_opendir().
dir | The sftp directory handle to close. |
References ssh_buffer_free(), and ssh_string_free().
int sftp_dir_eof | ( | sftp_dir | dir | ) |
Tell if the directory has reached EOF (End Of File).
dir | The sftp directory handle. |
int sftp_extension_supported | ( | sftp_session | sftp, |
const char * | name, | ||
const char * | data | ||
) |
Check if the given extension is supported.
sftp | The sftp session to use. |
name | The name of the extension. |
data | The data of the extension. |
Example:
References sftp_extensions_get_count(), sftp_extensions_get_data(), and sftp_extensions_get_name().
unsigned int sftp_extensions_get_count | ( | sftp_session | sftp | ) |
Get the count of extensions provided by the server.
sftp | The sftp session to use. |
Referenced by sftp_extension_supported().
const char* sftp_extensions_get_data | ( | sftp_session | sftp, |
unsigned int | indexn | ||
) |
Get the data of the extension provided by the server.
This is normally the version number of the extension.
sftp | The sftp session to use. |
indexn | The index number of the extension data you want. |
Referenced by sftp_extension_supported().
const char* sftp_extensions_get_name | ( | sftp_session | sftp, |
unsigned int | indexn | ||
) |
Get the name of the extension provided by the server.
sftp | The sftp session to use. |
indexn | The index number of the extension name you want. |
Referenced by sftp_extension_supported().
void sftp_file_set_blocking | ( | sftp_file | handle | ) |
Make the sftp communication for this file handle blocking.
[in] | handle | The file handle to set blocking. |
void sftp_file_set_nonblocking | ( | sftp_file | handle | ) |
Make the sftp communication for this file handle non blocking.
[in] | handle | The file handle to set non blocking. |
void sftp_free | ( | sftp_session | sftp | ) |
Close and deallocate a sftp session.
sftp | The sftp session handle to free. |
References ssh_channel_free(), and ssh_channel_send_eof().
Referenced by sftp_new().
sftp_attributes sftp_fstat | ( | sftp_file | file | ) |
Get information about a file or directory from a file handle.
file | The sftp file handle to get the stat information. |
References ssh_buffer_free(), and ssh_buffer_new().
sftp_statvfs_t sftp_fstatvfs | ( | sftp_file | file | ) |
Get information about a mounted file system.
file | An opened file. |
References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), and ssh_string_from_char().
int sftp_get_error | ( | sftp_session | sftp | ) |
Get the last sftp error.
Use this function to get the latest error set by a posix like sftp function.
sftp | The sftp session where the error is saved. |
int sftp_init | ( | sftp_session | sftp | ) |
Initialize the sftp session with the server.
sftp | The sftp session to initialize. |
References ssh_buffer_free(), and ssh_buffer_new().
sftp_attributes sftp_lstat | ( | sftp_session | session, |
const char * | path | ||
) |
Get information about a file or directory.
Identical to sftp_stat, but if the file or directory is a symbolic link, then the link itself is stated, not the file that it refers to.
session | The sftp session handle. |
path | The path to the file or directory to obtain the information. |
Referenced by sftp_mkdir().
int sftp_mkdir | ( | sftp_session | sftp, |
const char * | directory, | ||
mode_t | mode | ||
) |
Create a directory.
sftp | The sftp session handle. |
directory | The directory to create. |
mode | Specifies the permissions to use. It is modified by the process's umask in the usual way: The permissions of the created file are (mode & ~umask) |
References sftp_lstat(), ssh_buffer_free(), ssh_buffer_new(), SSH_FX_FAILURE, SSH_FX_FILE_ALREADY_EXISTS, SSH_FX_OK, ssh_string_free(), and ssh_string_from_char().
sftp_session sftp_new | ( | ssh_session | session | ) |
Start a new sftp session.
session | The ssh session to use. |
References sftp_free(), ssh_channel_free(), ssh_channel_new(), and ssh_channel_open_session().
sftp_session sftp_new_channel | ( | ssh_session | session, |
ssh_channel | channel | ||
) |
Start a new sftp session with an existing channel.
session | The ssh session to use. |
channel | An open session channel with subsystem already allocated |
sftp_file sftp_open | ( | sftp_session | session, |
const char * | file, | ||
int | accesstype, | ||
mode_t | mode | ||
) |
Open a file on the server.
session | The sftp session handle. |
file | The file to be opened. |
accesstype | Is one of O_RDONLY, O_WRONLY or O_RDWR which request opening the file read-only,write-only or read/write. Acesss may also be bitwise-or'd with one or more of the following: O_CREAT - If the file does not exist it will be created. O_EXCL - When used with O_CREAT, if the file already exists it is an error and the open will fail. O_TRUNC - If the file already exists it will be truncated. |
mode | Mode specifies the permissions to use if a new file is created. It is modified by the process's umask in the usual way: The permissions of the created file are (mode & ~umask) |
References ssh_buffer_free(), ssh_buffer_new(), SSH_LOG_PACKET, ssh_string_free(), and ssh_string_from_char().
sftp_dir sftp_opendir | ( | sftp_session | session, |
const char * | path | ||
) |
Open a directory used to obtain directory entries.
session | The sftp session handle to open the directory. |
path | The path of the directory to open. |
References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), and ssh_string_from_char().
ssize_t sftp_read | ( | sftp_file | file, |
void * | buf, | ||
size_t | count | ||
) |
Read from a file using an opened sftp file handle.
file | The opened sftp file handle to be read from. |
buf | Pointer to buffer to recieve read data. |
count | Size of the buffer in bytes. |
References ssh_buffer_free(), ssh_buffer_new(), ssh_channel_poll(), SSH_FX_EOF, ssh_string_data(), ssh_string_free(), and ssh_string_len().
sftp_attributes sftp_readdir | ( | sftp_session | session, |
sftp_dir | dir | ||
) |
Get a single file attributes structure of a directory.
session | The sftp session handle to read the directory entry. |
dir | The opened sftp directory handle to read from. |
References ssh_buffer_free(), ssh_buffer_new(), SSH_FX_EOF, and SSH_LOG_PACKET.
char* sftp_readlink | ( | sftp_session | sftp, |
const char * | path | ||
) |
Read the value of a symbolic link.
sftp | The sftp session handle. |
path | Specifies the path name of the symlink to be read. |
References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), ssh_string_from_char(), and ssh_string_to_char().
int sftp_rename | ( | sftp_session | sftp, |
const char * | original, | ||
const char * | newname | ||
) |
Rename or move a file or directory.
sftp | The sftp session handle. |
original | The original url (source url) of file or directory to be moved. |
newname | The new url (destination url) of the file or directory after the move. |
References ssh_buffer_free(), ssh_buffer_new(), and SSH_FX_OK.
void sftp_rewind | ( | sftp_file | file | ) |
Rewinds the position of the file pointer to the beginning of the file.
file | Open sftp file handle. |
int sftp_rmdir | ( | sftp_session | sftp, |
const char * | directory | ||
) |
Remove a directoy.
sftp | The sftp session handle. |
directory | The directory to remove. |
References ssh_buffer_free(), ssh_buffer_new(), and SSH_FX_OK.
int sftp_seek | ( | sftp_file | file, |
uint32_t | new_offset | ||
) |
Seek to a specific location in a file.
file | Open sftp file handle to seek in. |
new_offset | Offset in bytes to seek. |
int sftp_seek64 | ( | sftp_file | file, |
uint64_t | new_offset | ||
) |
Seek to a specific location in a file.
This is the 64bit version.
file | Open sftp file handle to seek in. |
new_offset | Offset in bytes to seek. |
int sftp_server_init | ( | sftp_session | sftp | ) |
Intialize the sftp server.
sftp | The sftp session to init. |
References ssh_buffer_free(), ssh_buffer_new(), and SSH_LOG_PACKET.
sftp_session sftp_server_new | ( | ssh_session | session, |
ssh_channel | chan | ||
) |
Create a new sftp server session.
session | The ssh session to use. |
chan | The ssh channel to use. |
int sftp_server_version | ( | sftp_session | sftp | ) |
Get the version of the SFTP protocol supported by the server.
sftp | The sftp session handle. |
int sftp_setstat | ( | sftp_session | sftp, |
const char * | file, | ||
sftp_attributes | attr | ||
) |
Set file attributes on a file, directory or symbolic link.
sftp | The sftp session handle. |
file | The file which attributes should be changed. |
attr | The file attributes structure with the attributes set which should be changed. |
References ssh_buffer_free(), ssh_buffer_new(), SSH_FX_OK, ssh_string_free(), and ssh_string_from_char().
Referenced by sftp_chmod(), sftp_chown(), and sftp_utimes().
sftp_attributes sftp_stat | ( | sftp_session | session, |
const char * | path | ||
) |
Get information about a file or directory.
session | The sftp session handle. |
path | The path to the file or directory to obtain the information. |
sftp_statvfs_t sftp_statvfs | ( | sftp_session | sftp, |
const char * | path | ||
) |
Get information about a mounted file system.
sftp | The sftp session handle. |
path | The pathname of any file within the mounted file system. |
References ssh_buffer_free(), ssh_buffer_new(), ssh_string_free(), and ssh_string_from_char().
void sftp_statvfs_free | ( | sftp_statvfs_t | statvfs_o | ) |
Free the memory of an allocated statvfs.
statvfs_o | The statvfs to free. |
int sftp_symlink | ( | sftp_session | sftp, |
const char * | target, | ||
const char * | dest | ||
) |
Create a symbolic link.
sftp | The sftp session handle. |
target | Specifies the target of the symlink. |
dest | Specifies the path name of the symlink to be created. |
References ssh_buffer_free(), ssh_buffer_new(), SSH_FX_OK, and ssh_get_openssh_version().
unsigned long sftp_tell | ( | sftp_file | file | ) |
Report current byte position in file.
file | Open sftp file handle. |
uint64_t sftp_tell64 | ( | sftp_file | file | ) |
Report current byte position in file.
file | Open sftp file handle. |
int sftp_unlink | ( | sftp_session | sftp, |
const char * | file | ||
) |
Unlink (delete) a file.
sftp | The sftp session handle. |
file | The file to unlink/delete. |
References ssh_buffer_free(), ssh_buffer_new(), and SSH_FX_OK.
int sftp_utimes | ( | sftp_session | sftp, |
const char * | file, | ||
const struct timeval * | times | ||
) |
Change the last modification and access time of a file.
sftp | The sftp session handle. |
file | The file which owner and group should be changed. |
times | A timeval structure which contains the desired access and modification time. |
References sftp_setstat().
ssize_t sftp_write | ( | sftp_file | file, |
const void * | buf, | ||
size_t | count | ||
) |
Write to a file using an opened sftp file handle.
file | Open sftp file handle to write to. |
buf | Pointer to buffer to write data. |
count | Size of buffer in bytes. |
References ssh_buffer_free(), ssh_buffer_new(), SSH_FX_OK, and SSH_LOG_PACKET.