libssh  0.8.4
The SSH library
Data Structures | Macros | Typedefs | Functions
The libssh SFTP API

SFTP handling functions. More...

Data Structures

struct  sftp_session_struct
 
struct  sftp_packet_struct
 
struct  sftp_file_struct
 
struct  sftp_dir_struct
 
struct  sftp_message_struct
 
struct  sftp_client_message_struct
 
struct  sftp_request_queue_struct
 
struct  sftp_status_message_struct
 
struct  sftp_attributes_struct
 
struct  sftp_statvfs_struct
 SFTP statvfs structure. More...
 

Macros

#define LIBSFTP_VERSION   3
 
#define SFTP_HANDLES   256
 
#define SSH_FXP_INIT   1
 
#define SSH_FXP_VERSION   2
 
#define SSH_FXP_OPEN   3
 
#define SSH_FXP_CLOSE   4
 
#define SSH_FXP_READ   5
 
#define SSH_FXP_WRITE   6
 
#define SSH_FXP_LSTAT   7
 
#define SSH_FXP_FSTAT   8
 
#define SSH_FXP_SETSTAT   9
 
#define SSH_FXP_FSETSTAT   10
 
#define SSH_FXP_OPENDIR   11
 
#define SSH_FXP_READDIR   12
 
#define SSH_FXP_REMOVE   13
 
#define SSH_FXP_MKDIR   14
 
#define SSH_FXP_RMDIR   15
 
#define SSH_FXP_REALPATH   16
 
#define SSH_FXP_STAT   17
 
#define SSH_FXP_RENAME   18
 
#define SSH_FXP_READLINK   19
 
#define SSH_FXP_SYMLINK   20
 
#define SSH_FXP_STATUS   101
 
#define SSH_FXP_HANDLE   102
 
#define SSH_FXP_DATA   103
 
#define SSH_FXP_NAME   104
 
#define SSH_FXP_ATTRS   105
 
#define SSH_FXP_EXTENDED   200
 
#define SSH_FXP_EXTENDED_REPLY   201
 
#define SSH_FILEXFER_ATTR_SIZE   0x00000001
 
#define SSH_FILEXFER_ATTR_PERMISSIONS   0x00000004
 
#define SSH_FILEXFER_ATTR_ACCESSTIME   0x00000008
 
#define SSH_FILEXFER_ATTR_ACMODTIME   0x00000008
 
#define SSH_FILEXFER_ATTR_CREATETIME   0x00000010
 
#define SSH_FILEXFER_ATTR_MODIFYTIME   0x00000020
 
#define SSH_FILEXFER_ATTR_ACL   0x00000040
 
#define SSH_FILEXFER_ATTR_OWNERGROUP   0x00000080
 
#define SSH_FILEXFER_ATTR_SUBSECOND_TIMES   0x00000100
 
#define SSH_FILEXFER_ATTR_EXTENDED   0x80000000
 
#define SSH_FILEXFER_ATTR_UIDGID   0x00000002
 
#define SSH_FILEXFER_TYPE_REGULAR   1
 
#define SSH_FILEXFER_TYPE_DIRECTORY   2
 
#define SSH_FILEXFER_TYPE_SYMLINK   3
 
#define SSH_FILEXFER_TYPE_SPECIAL   4
 
#define SSH_FILEXFER_TYPE_UNKNOWN   5
 
#define SSH_FXF_READ   0x01
 
#define SSH_FXF_WRITE   0x02
 
#define SSH_FXF_APPEND   0x04
 
#define SSH_FXF_CREAT   0x08
 
#define SSH_FXF_TRUNC   0x10
 
#define SSH_FXF_EXCL   0x20
 
#define SSH_FXF_TEXT   0x40
 
#define SSH_S_IFMT   00170000
 
#define SSH_S_IFSOCK   0140000
 
#define SSH_S_IFLNK   0120000
 
#define SSH_S_IFREG   0100000
 
#define SSH_S_IFBLK   0060000
 
#define SSH_S_IFDIR   0040000
 
#define SSH_S_IFCHR   0020000
 
#define SSH_S_IFIFO   0010000
 
#define SSH_FXF_RENAME_OVERWRITE   0x00000001
 
#define SSH_FXF_RENAME_ATOMIC   0x00000002
 
#define SSH_FXF_RENAME_NATIVE   0x00000004
 
#define SFTP_OPEN   SSH_FXP_OPEN
 
#define SFTP_CLOSE   SSH_FXP_CLOSE
 
#define SFTP_READ   SSH_FXP_READ
 
#define SFTP_WRITE   SSH_FXP_WRITE
 
#define SFTP_LSTAT   SSH_FXP_LSTAT
 
#define SFTP_FSTAT   SSH_FXP_FSTAT
 
#define SFTP_SETSTAT   SSH_FXP_SETSTAT
 
#define SFTP_FSETSTAT   SSH_FXP_FSETSTAT
 
#define SFTP_OPENDIR   SSH_FXP_OPENDIR
 
#define SFTP_READDIR   SSH_FXP_READDIR
 
#define SFTP_REMOVE   SSH_FXP_REMOVE
 
#define SFTP_MKDIR   SSH_FXP_MKDIR
 
#define SFTP_RMDIR   SSH_FXP_RMDIR
 
#define SFTP_REALPATH   SSH_FXP_REALPATH
 
#define SFTP_STAT   SSH_FXP_STAT
 
#define SFTP_RENAME   SSH_FXP_RENAME
 
#define SFTP_READLINK   SSH_FXP_READLINK
 
#define SFTP_SYMLINK   SSH_FXP_SYMLINK
 
#define SFTP_EXTENDED   SSH_FXP_EXTENDED
 
#define SSH_FXE_STATVFS_ST_RDONLY   0x1 /* read-only */
 
#define SSH_FXE_STATVFS_ST_NOSUID   0x2 /* no setuid */
 

Typedefs

typedef struct sftp_attributes_structsftp_attributes
 
typedef struct sftp_client_message_structsftp_client_message
 
typedef struct sftp_dir_structsftp_dir
 
typedef struct sftp_ext_struct * sftp_ext
 
typedef struct sftp_file_structsftp_file
 
typedef struct sftp_message_structsftp_message
 
typedef struct sftp_packet_structsftp_packet
 
typedef struct sftp_request_queue_structsftp_request_queue
 
typedef struct sftp_session_structsftp_session
 
typedef struct sftp_status_message_structsftp_status_message
 
typedef struct sftp_statvfs_structsftp_statvfs_t
 

Functions

LIBSSH_API sftp_session sftp_new (ssh_session session)
 Start a new sftp session. More...
 
LIBSSH_API sftp_session sftp_new_channel (ssh_session session, ssh_channel channel)
 Start a new sftp session with an existing channel. More...
 
LIBSSH_API void sftp_free (sftp_session sftp)
 Close and deallocate a sftp session. More...
 
LIBSSH_API int sftp_init (sftp_session sftp)
 Initialize the sftp session with the server. More...
 
LIBSSH_API int sftp_get_error (sftp_session sftp)
 Get the last sftp error. More...
 
LIBSSH_API unsigned int sftp_extensions_get_count (sftp_session sftp)
 Get the count of extensions provided by the server. More...
 
LIBSSH_API const char * sftp_extensions_get_name (sftp_session sftp, unsigned int indexn)
 Get the name of the extension provided by the server. More...
 
LIBSSH_API const char * sftp_extensions_get_data (sftp_session sftp, unsigned int indexn)
 Get the data of the extension provided by the server. More...
 
LIBSSH_API int sftp_extension_supported (sftp_session sftp, const char *name, const char *data)
 Check if the given extension is supported. More...
 
LIBSSH_API sftp_dir sftp_opendir (sftp_session session, const char *path)
 Open a directory used to obtain directory entries. More...
 
LIBSSH_API sftp_attributes sftp_readdir (sftp_session session, sftp_dir dir)
 Get a single file attributes structure of a directory. More...
 
LIBSSH_API int sftp_dir_eof (sftp_dir dir)
 Tell if the directory has reached EOF (End Of File). More...
 
LIBSSH_API sftp_attributes sftp_stat (sftp_session session, const char *path)
 Get information about a file or directory. More...
 
LIBSSH_API sftp_attributes sftp_lstat (sftp_session session, const char *path)
 Get information about a file or directory. More...
 
LIBSSH_API sftp_attributes sftp_fstat (sftp_file file)
 Get information about a file or directory from a file handle. More...
 
LIBSSH_API void sftp_attributes_free (sftp_attributes file)
 Free a sftp attribute structure. More...
 
LIBSSH_API int sftp_closedir (sftp_dir dir)
 Close a directory handle opened by sftp_opendir(). More...
 
LIBSSH_API int sftp_close (sftp_file file)
 Close an open file handle. More...
 
LIBSSH_API sftp_file sftp_open (sftp_session session, const char *file, int accesstype, mode_t mode)
 Open a file on the server. More...
 
LIBSSH_API void sftp_file_set_nonblocking (sftp_file handle)
 Make the sftp communication for this file handle non blocking. More...
 
LIBSSH_API void sftp_file_set_blocking (sftp_file handle)
 Make the sftp communication for this file handle blocking. More...
 
LIBSSH_API ssize_t sftp_read (sftp_file file, void *buf, size_t count)
 Read from a file using an opened sftp file handle. More...
 
LIBSSH_API 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...
 
LIBSSH_API 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...
 
LIBSSH_API ssize_t sftp_write (sftp_file file, const void *buf, size_t count)
 Write to a file using an opened sftp file handle. More...
 
LIBSSH_API int sftp_seek (sftp_file file, uint32_t new_offset)
 Seek to a specific location in a file. More...
 
LIBSSH_API int sftp_seek64 (sftp_file file, uint64_t new_offset)
 Seek to a specific location in a file. This is the 64bit version. More...
 
LIBSSH_API unsigned long sftp_tell (sftp_file file)
 Report current byte position in file. More...
 
LIBSSH_API uint64_t sftp_tell64 (sftp_file file)
 Report current byte position in file. More...
 
LIBSSH_API void sftp_rewind (sftp_file file)
 Rewinds the position of the file pointer to the beginning of the file. More...
 
LIBSSH_API int sftp_unlink (sftp_session sftp, const char *file)
 Unlink (delete) a file. More...
 
LIBSSH_API int sftp_rmdir (sftp_session sftp, const char *directory)
 Remove a directoy. More...
 
LIBSSH_API int sftp_mkdir (sftp_session sftp, const char *directory, mode_t mode)
 Create a directory. More...
 
LIBSSH_API int sftp_rename (sftp_session sftp, const char *original, const char *newname)
 Rename or move a file or directory. More...
 
LIBSSH_API int sftp_setstat (sftp_session sftp, const char *file, sftp_attributes attr)
 Set file attributes on a file, directory or symbolic link. More...
 
LIBSSH_API int sftp_chown (sftp_session sftp, const char *file, uid_t owner, gid_t group)
 Change the file owner and group. More...
 
LIBSSH_API int sftp_chmod (sftp_session sftp, const char *file, mode_t mode)
 Change permissions of a file. More...
 
LIBSSH_API int sftp_utimes (sftp_session sftp, const char *file, const struct timeval *times)
 Change the last modification and access time of a file. More...
 
LIBSSH_API int sftp_symlink (sftp_session sftp, const char *target, const char *dest)
 Create a symbolic link. More...
 
LIBSSH_API char * sftp_readlink (sftp_session sftp, const char *path)
 Read the value of a symbolic link. More...
 
LIBSSH_API sftp_statvfs_t sftp_statvfs (sftp_session sftp, const char *path)
 Get information about a mounted file system. More...
 
LIBSSH_API sftp_statvfs_t sftp_fstatvfs (sftp_file file)
 Get information about a mounted file system. More...
 
LIBSSH_API void sftp_statvfs_free (sftp_statvfs_t statvfs_o)
 Free the memory of an allocated statvfs. More...
 
LIBSSH_API int sftp_fsync (sftp_file file)
 Synchronize a file's in-core state with storage device. More...
 
LIBSSH_API char * sftp_canonicalize_path (sftp_session sftp, const char *path)
 Canonicalize a sftp path. More...
 
LIBSSH_API int sftp_server_version (sftp_session sftp)
 Get the version of the SFTP protocol supported by the server. More...
 
sftp_packet sftp_packet_read (sftp_session sftp)
 
int sftp_packet_write (sftp_session sftp, uint8_t type, ssh_buffer payload)
 
void sftp_packet_free (sftp_packet packet)
 
int buffer_add_attributes (ssh_buffer buffer, sftp_attributes attr)
 
sftp_attributes sftp_parse_attr (sftp_session session, ssh_buffer buf, int expectname)
 
LIBSSH_API sftp_client_message sftp_get_client_message (sftp_session sftp)
 
LIBSSH_API void sftp_client_message_free (sftp_client_message msg)
 
LIBSSH_API uint8_t sftp_client_message_get_type (sftp_client_message msg)
 
LIBSSH_API const char * sftp_client_message_get_filename (sftp_client_message msg)
 
LIBSSH_API void sftp_client_message_set_filename (sftp_client_message msg, const char *newname)
 
LIBSSH_API const char * sftp_client_message_get_data (sftp_client_message msg)
 
LIBSSH_API uint32_t sftp_client_message_get_flags (sftp_client_message msg)
 
LIBSSH_API const char * sftp_client_message_get_submessage (sftp_client_message msg)
 
LIBSSH_API int sftp_send_client_message (sftp_session sftp, sftp_client_message msg)
 
LIBSSH_API int sftp_reply_name (sftp_client_message msg, const char *name, sftp_attributes attr)
 
LIBSSH_API int sftp_reply_handle (sftp_client_message msg, ssh_string handle)
 
LIBSSH_API ssh_string sftp_handle_alloc (sftp_session sftp, void *info)
 
LIBSSH_API int sftp_reply_attr (sftp_client_message msg, sftp_attributes attr)
 
LIBSSH_API void * sftp_handle (sftp_session sftp, ssh_string handle)
 
LIBSSH_API int sftp_reply_status (sftp_client_message msg, uint32_t status, const char *message)
 
LIBSSH_API int sftp_reply_names_add (sftp_client_message msg, const char *file, const char *longname, sftp_attributes attr)
 
LIBSSH_API int sftp_reply_names (sftp_client_message msg)
 
LIBSSH_API int sftp_reply_data (sftp_client_message msg, const void *data, int len)
 
LIBSSH_API void sftp_handle_remove (sftp_session sftp, void *handle)
 

Server responses

Responses returned by the sftp server.

#define SSH_FX_OK   0
 
#define SSH_FX_EOF   1
 
#define SSH_FX_NO_SUCH_FILE   2
 
#define SSH_FX_PERMISSION_DENIED   3
 
#define SSH_FX_FAILURE   4
 
#define SSH_FX_BAD_MESSAGE   5
 
#define SSH_FX_NO_CONNECTION   6
 
#define SSH_FX_CONNECTION_LOST   7
 
#define SSH_FX_OP_UNSUPPORTED   8
 
#define SSH_FX_INVALID_HANDLE   9
 
#define SSH_FX_NO_SUCH_PATH   10
 
#define SSH_FX_FILE_ALREADY_EXISTS   11
 
#define SSH_FX_WRITE_PROTECT   12
 
#define SSH_FX_NO_MEDIA   13
 

Detailed Description

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

Macro Definition Documentation

◆ SSH_FX_BAD_MESSAGE

#define SSH_FX_BAD_MESSAGE   5

Garbage received from server

◆ SSH_FX_CONNECTION_LOST

#define SSH_FX_CONNECTION_LOST   7

There was a connection, but we lost it

◆ SSH_FX_EOF

#define SSH_FX_EOF   1

End-of-file encountered

◆ SSH_FX_FAILURE

#define SSH_FX_FAILURE   4

Generic failure

◆ SSH_FX_FILE_ALREADY_EXISTS

#define SSH_FX_FILE_ALREADY_EXISTS   11

An attempt to create an already existing file or directory has been made

◆ SSH_FX_INVALID_HANDLE

#define SSH_FX_INVALID_HANDLE   9

Invalid file handle

◆ SSH_FX_NO_CONNECTION

#define SSH_FX_NO_CONNECTION   6

No connection has been set up

◆ SSH_FX_NO_MEDIA

#define SSH_FX_NO_MEDIA   13

No media in remote drive

◆ SSH_FX_NO_SUCH_FILE

#define SSH_FX_NO_SUCH_FILE   2

File doesn't exist

◆ SSH_FX_NO_SUCH_PATH

#define SSH_FX_NO_SUCH_PATH   10

No such file or directory path exists

◆ SSH_FX_OK

#define SSH_FX_OK   0

No error

◆ SSH_FX_OP_UNSUPPORTED

#define SSH_FX_OP_UNSUPPORTED   8

Operation not supported by the server

◆ SSH_FX_PERMISSION_DENIED

#define SSH_FX_PERMISSION_DENIED   3

Permission denied

◆ SSH_FX_WRITE_PROTECT

#define SSH_FX_WRITE_PROTECT   12

We are trying to write on a write-protected filesystem

Function Documentation

◆ sftp_async_read()

LIBSSH_API 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.

Parameters
fileThe opened sftp file handle to be read from.
dataPointer to buffer to recieve read data.
lenSize of the buffer in bytes. It should be bigger or equal to the length parameter of the sftp_async_read_begin() call.
idThe identifier returned by the sftp_async_read_begin() function.
Returns
Number of bytes read, 0 on EOF, SSH_ERROR if an error occured, SSH_AGAIN if the file is opened in nonblocking mode and the request hasn't been executed yet.
Warning
A call to this function with an invalid identifier will never return.
See also
sftp_async_read_begin()

◆ sftp_async_read_begin()

LIBSSH_API 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.

Parameters
fileThe opened sftp file handle to be read from.
lenSize to read in bytes.
Returns
An identifier corresponding to the sent request, < 0 on error.
Warning
When calling this function, the internal offset is updated corresponding to the len parameter.
A call to sftp_async_read_begin() sends a request to the server. When the server answers, libssh allocates memory to store it until sftp_async_read() is called. Not calling sftp_async_read() will lead to memory leaks.
See also
sftp_async_read()
sftp_open()

◆ sftp_attributes_free()

LIBSSH_API void sftp_attributes_free ( sftp_attributes  file)

Free a sftp attribute structure.

Parameters
fileThe sftp attribute structure to free.

◆ sftp_canonicalize_path()

LIBSSH_API char* sftp_canonicalize_path ( sftp_session  sftp,
const char *  path 
)

Canonicalize a sftp path.

Parameters
sftpThe sftp session handle.
pathThe path to be canonicalized.
Returns
The canonicalize path, NULL on error.

◆ sftp_chmod()

LIBSSH_API int sftp_chmod ( sftp_session  sftp,
const char *  file,
mode_t  mode 
)

Change permissions of a file.

Parameters
sftpThe sftp session handle.
fileThe file which owner and group should be changed.
modeSpecifies 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)
Returns
0 on success, < 0 on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_chown()

LIBSSH_API int sftp_chown ( sftp_session  sftp,
const char *  file,
uid_t  owner,
gid_t  group 
)

Change the file owner and group.

Parameters
sftpThe sftp session handle.
fileThe file which owner and group should be changed.
ownerThe new owner which should be set.
groupThe new group which should be set.
Returns
0 on success, < 0 on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_close()

LIBSSH_API int sftp_close ( sftp_file  file)

Close an open file handle.

Parameters
fileThe open sftp file handle to close.
Returns
Returns SSH_NO_ERROR or SSH_ERROR if an error occured.
See also
sftp_open()

◆ sftp_closedir()

LIBSSH_API int sftp_closedir ( sftp_dir  dir)

Close a directory handle opened by sftp_opendir().

Parameters
dirThe sftp directory handle to close.
Returns
Returns SSH_NO_ERROR or SSH_ERROR if an error occured.

◆ sftp_dir_eof()

LIBSSH_API int sftp_dir_eof ( sftp_dir  dir)

Tell if the directory has reached EOF (End Of File).

Parameters
dirThe sftp directory handle.
Returns
1 if the directory is EOF, 0 if not.
See also
sftp_readdir()

◆ sftp_extension_supported()

LIBSSH_API int sftp_extension_supported ( sftp_session  sftp,
const char *  name,
const char *  data 
)

Check if the given extension is supported.

Parameters
sftpThe sftp session to use.
nameThe name of the extension.
dataThe data of the extension.
Returns
1 if supported, 0 if not.

Example:

sftp_extension_supported(sftp, "statvfs@openssh.com", "2");

◆ sftp_extensions_get_count()

LIBSSH_API unsigned int sftp_extensions_get_count ( sftp_session  sftp)

Get the count of extensions provided by the server.

Parameters
sftpThe sftp session to use.
Returns
The count of extensions provided by the server, 0 on error or not available.

◆ sftp_extensions_get_data()

LIBSSH_API 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.

Parameters
sftpThe sftp session to use.
indexnThe index number of the extension data you want.
Returns
The data of the extension.

◆ sftp_extensions_get_name()

LIBSSH_API const char* sftp_extensions_get_name ( sftp_session  sftp,
unsigned int  indexn 
)

Get the name of the extension provided by the server.

Parameters
sftpThe sftp session to use.
indexnThe index number of the extension name you want.
Returns
The name of the extension.

◆ sftp_file_set_blocking()

LIBSSH_API void sftp_file_set_blocking ( sftp_file  handle)

Make the sftp communication for this file handle blocking.

Parameters
[in]handleThe file handle to set blocking.

◆ sftp_file_set_nonblocking()

LIBSSH_API void sftp_file_set_nonblocking ( sftp_file  handle)

Make the sftp communication for this file handle non blocking.

Parameters
[in]handleThe file handle to set non blocking.

◆ sftp_free()

LIBSSH_API void sftp_free ( sftp_session  sftp)

Close and deallocate a sftp session.

Parameters
sftpThe sftp session handle to free.

◆ sftp_fstat()

LIBSSH_API sftp_attributes sftp_fstat ( sftp_file  file)

Get information about a file or directory from a file handle.

Parameters
fileThe sftp file handle to get the stat information.
Returns
The sftp attributes structure of the file or directory, NULL on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_fstatvfs()

LIBSSH_API sftp_statvfs_t sftp_fstatvfs ( sftp_file  file)

Get information about a mounted file system.

Parameters
fileAn opened file.
Returns
A statvfs structure or NULL on error.
See also
sftp_get_error()

◆ sftp_fsync()

LIBSSH_API int sftp_fsync ( sftp_file  file)

Synchronize a file's in-core state with storage device.

This calls the "fsync@openssh.com" extention. You should check if the extensions is supported using:

int supported = sftp_extension_supported(sftp, "fsync@openssh.com", "1");
Parameters
fileThe opened sftp file handle to sync
Returns
0 on success, < 0 on error with ssh and sftp error set.

◆ sftp_get_error()

LIBSSH_API 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.

Parameters
sftpThe sftp session where the error is saved.
Returns
The saved error (see server responses), < 0 if an error in the function occured.
See also
Server responses

◆ sftp_init()

LIBSSH_API int sftp_init ( sftp_session  sftp)

Initialize the sftp session with the server.

Parameters
sftpThe sftp session to initialize.
Returns
0 on success, < 0 on error with ssh error set.
See also
sftp_new()

◆ sftp_lstat()

LIBSSH_API 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.

Parameters
sessionThe sftp session handle.
pathThe path to the file or directory to obtain the information.
Returns
The sftp attributes structure of the file or directory, NULL on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_mkdir()

LIBSSH_API int sftp_mkdir ( sftp_session  sftp,
const char *  directory,
mode_t  mode 
)

Create a directory.

Parameters
sftpThe sftp session handle.
directoryThe directory to create.
modeSpecifies 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)
Returns
0 on success, < 0 on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_new()

LIBSSH_API sftp_session sftp_new ( ssh_session  session)

Start a new sftp session.

Parameters
sessionThe ssh session to use.
Returns
A new sftp session or NULL on error.
See also
sftp_free()

◆ sftp_new_channel()

LIBSSH_API sftp_session sftp_new_channel ( ssh_session  session,
ssh_channel  channel 
)

Start a new sftp session with an existing channel.

Parameters
sessionThe ssh session to use.
channelAn open session channel with subsystem already allocated
Returns
A new sftp session or NULL on error.
See also
sftp_free()

◆ sftp_open()

LIBSSH_API sftp_file sftp_open ( sftp_session  session,
const char *  file,
int  accesstype,
mode_t  mode 
)

Open a file on the server.

Parameters
sessionThe sftp session handle.
fileThe file to be opened.
accesstypeIs 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.
modeMode 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)
Returns
A sftp file handle, NULL on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_opendir()

LIBSSH_API sftp_dir sftp_opendir ( sftp_session  session,
const char *  path 
)

Open a directory used to obtain directory entries.

Parameters
sessionThe sftp session handle to open the directory.
pathThe path of the directory to open.
Returns
A sftp directory handle or NULL on error with ssh and sftp error set.
See also
sftp_readdir
sftp_closedir

◆ sftp_read()

LIBSSH_API ssize_t sftp_read ( sftp_file  file,
void *  buf,
size_t  count 
)

Read from a file using an opened sftp file handle.

Parameters
fileThe opened sftp file handle to be read from.
bufPointer to buffer to recieve read data.
countSize of the buffer in bytes.
Returns
Number of bytes written, < 0 on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_readdir()

LIBSSH_API sftp_attributes sftp_readdir ( sftp_session  session,
sftp_dir  dir 
)

Get a single file attributes structure of a directory.

Parameters
sessionThe sftp session handle to read the directory entry.
dirThe opened sftp directory handle to read from.
Returns
A file attribute structure or NULL at the end of the directory.
See also
sftp_opendir()
sftp_attribute_free()
sftp_closedir()

◆ sftp_readlink()

LIBSSH_API char* sftp_readlink ( sftp_session  sftp,
const char *  path 
)

Read the value of a symbolic link.

Parameters
sftpThe sftp session handle.
pathSpecifies the path name of the symlink to be read.
Returns
The target of the link, NULL on error.
See also
sftp_get_error()

◆ sftp_rename()

LIBSSH_API int sftp_rename ( sftp_session  sftp,
const char *  original,
const char *  newname 
)

Rename or move a file or directory.

Parameters
sftpThe sftp session handle.
originalThe original url (source url) of file or directory to be moved.
newnameThe new url (destination url) of the file or directory after the move.
Returns
0 on success, < 0 on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_rewind()

LIBSSH_API void sftp_rewind ( sftp_file  file)

Rewinds the position of the file pointer to the beginning of the file.

Parameters
fileOpen sftp file handle.

◆ sftp_rmdir()

LIBSSH_API int sftp_rmdir ( sftp_session  sftp,
const char *  directory 
)

Remove a directoy.

Parameters
sftpThe sftp session handle.
directoryThe directory to remove.
Returns
0 on success, < 0 on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_seek()

LIBSSH_API int sftp_seek ( sftp_file  file,
uint32_t  new_offset 
)

Seek to a specific location in a file.

Parameters
fileOpen sftp file handle to seek in.
new_offsetOffset in bytes to seek.
Returns
0 on success, < 0 on error.

◆ sftp_seek64()

LIBSSH_API int sftp_seek64 ( sftp_file  file,
uint64_t  new_offset 
)

Seek to a specific location in a file. This is the 64bit version.

Parameters
fileOpen sftp file handle to seek in.
new_offsetOffset in bytes to seek.
Returns
0 on success, < 0 on error.

◆ sftp_server_version()

LIBSSH_API int sftp_server_version ( sftp_session  sftp)

Get the version of the SFTP protocol supported by the server.

Parameters
sftpThe sftp session handle.
Returns
The server version.

◆ sftp_setstat()

LIBSSH_API int sftp_setstat ( sftp_session  sftp,
const char *  file,
sftp_attributes  attr 
)

Set file attributes on a file, directory or symbolic link.

Parameters
sftpThe sftp session handle.
fileThe file which attributes should be changed.
attrThe file attributes structure with the attributes set which should be changed.
Returns
0 on success, < 0 on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_stat()

LIBSSH_API sftp_attributes sftp_stat ( sftp_session  session,
const char *  path 
)

Get information about a file or directory.

Parameters
sessionThe sftp session handle.
pathThe path to the file or directory to obtain the information.
Returns
The sftp attributes structure of the file or directory, NULL on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_statvfs()

LIBSSH_API sftp_statvfs_t sftp_statvfs ( sftp_session  sftp,
const char *  path 
)

Get information about a mounted file system.

Parameters
sftpThe sftp session handle.
pathThe pathname of any file within the mounted file system.
Returns
A statvfs structure or NULL on error.
See also
sftp_get_error()

◆ sftp_statvfs_free()

LIBSSH_API void sftp_statvfs_free ( sftp_statvfs_t  statvfs_o)

Free the memory of an allocated statvfs.

Parameters
statvfs_oThe statvfs to free.

◆ sftp_symlink()

LIBSSH_API int sftp_symlink ( sftp_session  sftp,
const char *  target,
const char *  dest 
)

Create a symbolic link.

Parameters
sftpThe sftp session handle.
targetSpecifies the target of the symlink.
destSpecifies the path name of the symlink to be created.
Returns
0 on success, < 0 on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_tell()

LIBSSH_API unsigned long sftp_tell ( sftp_file  file)

Report current byte position in file.

Parameters
fileOpen sftp file handle.
Returns
The offset of the current byte relative to the beginning of the file associated with the file descriptor. < 0 on error.

◆ sftp_tell64()

LIBSSH_API uint64_t sftp_tell64 ( sftp_file  file)

Report current byte position in file.

Parameters
fileOpen sftp file handle.
Returns
The offset of the current byte relative to the beginning of the file associated with the file descriptor. < 0 on error.

◆ sftp_unlink()

LIBSSH_API int sftp_unlink ( sftp_session  sftp,
const char *  file 
)

Unlink (delete) a file.

Parameters
sftpThe sftp session handle.
fileThe file to unlink/delete.
Returns
0 on success, < 0 on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_utimes()

LIBSSH_API int sftp_utimes ( sftp_session  sftp,
const char *  file,
const struct timeval *  times 
)

Change the last modification and access time of a file.

Parameters
sftpThe sftp session handle.
fileThe file which owner and group should be changed.
timesA timeval structure which contains the desired access and modification time.
Returns
0 on success, < 0 on error with ssh and sftp error set.
See also
sftp_get_error()

◆ sftp_write()

LIBSSH_API ssize_t sftp_write ( sftp_file  file,
const void *  buf,
size_t  count 
)

Write to a file using an opened sftp file handle.

Parameters
fileOpen sftp file handle to write to.
bufPointer to buffer to write data.
countSize of buffer in bytes.
Returns
Number of bytes written, < 0 on error with ssh and sftp error set.
See also
sftp_open()
sftp_read()
sftp_close()