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	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_struct *	sftp_attributes

typedef struct sftp_client_message_struct *	sftp_client_message

typedef struct sftp_dir_struct *	sftp_dir

typedef struct sftp_ext_struct *	sftp_ext

typedef struct sftp_file_struct *	sftp_file

typedef struct sftp_message_struct *	sftp_message

typedef struct sftp_packet_struct *	sftp_packet

typedef struct sftp_request_queue_struct *	sftp_request_queue

typedef struct sftp_session_struct *	sftp_session

typedef struct sftp_status_message_struct *	sftp_status_message

typedef struct sftp_statvfs_struct *	sftp_statvfs_t

Functions
LIBSSH_API sftp_session	sftp_new (ssh_session session)
	Creates a new sftp session.

LIBSSH_API sftp_session	sftp_new_channel (ssh_session session, ssh_channel channel)
	Start a new sftp session with an existing channel.

LIBSSH_API void	sftp_free (sftp_session sftp)
	Close and deallocate a sftp session.

LIBSSH_API int	sftp_init (sftp_session sftp)
	Initialize the sftp protocol with the server.

LIBSSH_API int	sftp_get_error (sftp_session sftp)
	Get the last sftp error.

LIBSSH_API unsigned int	sftp_extensions_get_count (sftp_session sftp)
	Get the count of extensions provided by the server.

LIBSSH_API const char *	sftp_extensions_get_name (sftp_session sftp, unsigned int indexn)
	Get the name of the extension provided by the server.

LIBSSH_API const char *	sftp_extensions_get_data (sftp_session sftp, unsigned int indexn)
	Get the data of the extension provided by the server.

LIBSSH_API int	sftp_extension_supported (sftp_session sftp, const char name, const char data)
	Check if the given extension is supported.

LIBSSH_API sftp_dir	sftp_opendir (sftp_session session, const char *path)
	Open a directory used to obtain directory entries.

LIBSSH_API sftp_attributes	sftp_readdir (sftp_session session, sftp_dir dir)
	Get a single file attributes structure of a directory.

LIBSSH_API int	sftp_dir_eof (sftp_dir dir)
	Tell if the directory has reached EOF (End Of File).

LIBSSH_API sftp_attributes	sftp_stat (sftp_session session, const char *path)
	Get information about a file or directory.

LIBSSH_API sftp_attributes	sftp_lstat (sftp_session session, const char *path)
	Get information about a file or directory.

LIBSSH_API sftp_attributes	sftp_fstat (sftp_file file)
	Get information about a file or directory from a file handle.

LIBSSH_API void	sftp_attributes_free (sftp_attributes file)
	Free a sftp attribute structure.

LIBSSH_API int	sftp_closedir (sftp_dir dir)
	Close a directory handle opened by sftp_opendir().

LIBSSH_API int	sftp_close (sftp_file file)
	Close an open file handle.

LIBSSH_API sftp_file	sftp_open (sftp_session session, const char *file, int accesstype, mode_t mode)
	Open a file on the server.

LIBSSH_API void	sftp_file_set_nonblocking (sftp_file handle)
	Make the sftp communication for this file handle non blocking.

LIBSSH_API void	sftp_file_set_blocking (sftp_file handle)
	Make the sftp communication for this file handle blocking.

LIBSSH_API ssize_t	sftp_read (sftp_file file, void *buf, size_t count)
	Read from a file using an opened sftp file handle.

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.

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.

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.

LIBSSH_API int	sftp_seek (sftp_file file, uint32_t new_offset)
	Seek to a specific location in a file.

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.

LIBSSH_API unsigned long	sftp_tell (sftp_file file)
	Report current byte position in file.

LIBSSH_API uint64_t	sftp_tell64 (sftp_file file)
	Report current byte position in file.

LIBSSH_API void	sftp_rewind (sftp_file file)
	Rewinds the position of the file pointer to the beginning of the file.

LIBSSH_API int	sftp_unlink (sftp_session sftp, const char *file)
	Unlink (delete) a file.

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

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

LIBSSH_API int	sftp_rename (sftp_session sftp, const char original, const char newname)
	Rename or move a file or directory.

LIBSSH_API int	sftp_setstat (sftp_session sftp, const char *file, sftp_attributes attr)
	Set file attributes on a file, directory or symbolic link.

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

LIBSSH_API int	sftp_chmod (sftp_session sftp, const char *file, mode_t mode)
	Change permissions of a file.

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.

LIBSSH_API int	sftp_symlink (sftp_session sftp, const char target, const char dest)
	Create a symbolic link.

LIBSSH_API char *	sftp_readlink (sftp_session sftp, const char *path)
	Read the value of a symbolic link.

LIBSSH_API sftp_statvfs_t	sftp_statvfs (sftp_session sftp, const char *path)
	Get information about a mounted file system.

LIBSSH_API sftp_statvfs_t	sftp_fstatvfs (sftp_file file)
	Get information about a mounted file system.

LIBSSH_API void	sftp_statvfs_free (sftp_statvfs_t statvfs_o)
	Free the memory of an allocated statvfs.

LIBSSH_API int	sftp_fsync (sftp_file file)
	Synchronize a file's in-core state with storage device.

LIBSSH_API char *	sftp_canonicalize_path (sftp_session sftp, const char *path)
	Canonicalize a sftp path.

LIBSSH_API int	sftp_server_version (sftp_session sftp)
	Get the version of the SFTP protocol supported by the server.

LIBSSH_API sftp_session	sftp_server_new (ssh_session session, ssh_channel chan)
	Create a new sftp server session.

LIBSSH_API int	sftp_server_init (sftp_session sftp)
	Initialize the sftp server.

LIBSSH_API void	sftp_server_free (sftp_session sftp)
	Close and deallocate a sftp server session.

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

file	The opened sftp file handle to be read from.
data	Pointer to buffer to receive 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.

Returns: Number of bytes read, 0 on EOF, SSH_ERROR if an error occurred, 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

file	The opened sftp file handle to be read from.
len	Size 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

file	The 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

sftp	The sftp session handle.
path	The path to be canonicalized.

Returns: A pointer to the newly allocated canonicalized path, NULL on error. The caller needs to free the memory using ssh_string_free_char().

◆ sftp_chmod()

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

Change permissions of a file.

Parameters

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)

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

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.

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

file	The open sftp file handle to close.

Returns: Returns SSH_NO_ERROR or SSH_ERROR if an error occurred.

See also: sftp_open()

◆ sftp_closedir()

LIBSSH_API int sftp_closedir ( sftp_dir dir )

Close a directory handle opened by sftp_opendir().

Parameters

dir	The sftp directory handle to close.

Returns: Returns SSH_NO_ERROR or SSH_ERROR if an error occurred.

◆ sftp_dir_eof()

LIBSSH_API int sftp_dir_eof ( sftp_dir dir )

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

Parameters

dir	The 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

sftp	The sftp session to use.
name	The name of the extension.
data	The data of the extension.

Returns: 1 if supported, 0 if not.

Example:

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

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.

Definition sftp.c:795

◆ 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

sftp	The 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

sftp	The sftp session to use.
indexn	The 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

sftp	The sftp session to use.
indexn	The 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] handle The 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] handle The file handle to set non blocking.

◆ sftp_free()

LIBSSH_API void sftp_free ( sftp_session sftp )

Close and deallocate a sftp session.

Parameters

sftp	The 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

file	The 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

file	An 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" extension. You should check if the extensions is supported using:

int supported = sftp_extension_supported(sftp, "fsync@openssh.com", "1");

Parameters

file	The 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

sftp	The sftp session where the error is saved.

Returns: The saved error (see server responses), < 0 if an error in the function occurred.

See also: Server responses

◆ sftp_init()

LIBSSH_API int sftp_init ( sftp_session sftp )

Initialize the sftp protocol with the server.

This function involves the SFTP protocol initialization (as described in the SFTP specification), including the version and extensions negotiation.

Parameters

sftp	The 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

session	The sftp session handle.
path	The 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

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)

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 )

Creates a new sftp session.

This function creates a new sftp session and allocates a new sftp channel with the server inside of the provided ssh session. This function call is usually followed by the sftp_init(), which initializes SFTP protocol itself.

Parameters

session The ssh session to use.

Returns: A new sftp session or NULL on error.

See also: sftp_free(); sftp_init()

◆ 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

session	The ssh session to use.
channel	An 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

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)

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

session	The sftp session handle to open the directory.
path	The 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

file	The opened sftp file handle to be read from.
buf	Pointer to buffer to receive read data.
count	Size 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

session	The sftp session handle to read the directory entry.
dir	The 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

sftp	The sftp session handle.
path	Specifies the path name of the symlink to be read.

Returns: The target of the link, NULL on error. The caller needs to free the memory using ssh_string_free_char().

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

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.

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

file	Open sftp file handle.

◆ sftp_rmdir()

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

Remove a directory.

Parameters

sftp	The sftp session handle.
directory	The 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

file	Open sftp file handle to seek in.
new_offset	Offset 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

file	Open sftp file handle to seek in.
new_offset	Offset in bytes to seek.

Returns: 0 on success, < 0 on error.

◆ sftp_server_free()

LIBSSH_API void sftp_server_free ( sftp_session sftp )

Close and deallocate a sftp server session.

Parameters

sftp	The sftp session handle to free.

◆ sftp_server_init()

LIBSSH_API int sftp_server_init ( sftp_session sftp )

Initialize the sftp server.

Parameters

sftp	The sftp session to init.

Returns: 0 on success, < 0 on error.

◆ sftp_server_new()

LIBSSH_API sftp_session sftp_server_new	(	ssh_session	session,
		ssh_channel	chan )

Create a new sftp server session.

Parameters

session	The ssh session to use.
chan	The ssh channel to use.

Returns: A new sftp server session.

◆ sftp_server_version()

LIBSSH_API int sftp_server_version ( sftp_session sftp )

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

Parameters

sftp	The 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.

Note, that this function can only set time values using 32 bit values due to the restrictions in the SFTP protocol version 3 implemented by libssh. The support for 64 bit time values was introduced in SFTP version 5, which is not implemented by libssh nor any major SFTP servers.

Parameters

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.

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

session	The sftp session handle.
path	The 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

sftp	The sftp session handle.
path	The 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_o The statvfs to free.

◆ sftp_symlink()

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

Create a symbolic link.

Parameters

sftp	The sftp session handle.
target	Specifies the target of the symlink.
dest	Specifies 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

file	Open 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

file	Open 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

sftp	The sftp session handle.
file	The 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

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.

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

file	Open sftp file handle to write to.
buf	Pointer to buffer to write data.
count	Size 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()

Data Structures

Macros

Typedefs

Functions

Server responses

Detailed Description

Macro Definition Documentation

◆ SSH_FX_BAD_MESSAGE

◆ SSH_FX_CONNECTION_LOST

◆ SSH_FX_EOF

◆ SSH_FX_FAILURE

◆ SSH_FX_FILE_ALREADY_EXISTS

◆ SSH_FX_INVALID_HANDLE

◆ SSH_FX_NO_CONNECTION

◆ SSH_FX_NO_MEDIA

◆ SSH_FX_NO_SUCH_FILE

◆ SSH_FX_NO_SUCH_PATH

◆ SSH_FX_OK

◆ SSH_FX_OP_UNSUPPORTED

◆ SSH_FX_PERMISSION_DENIED

◆ SSH_FX_WRITE_PROTECT

Function Documentation

◆ sftp_async_read()

◆ sftp_async_read_begin()

◆ sftp_attributes_free()

◆ sftp_canonicalize_path()

◆ sftp_chmod()

◆ sftp_chown()

◆ sftp_close()

◆ sftp_closedir()

◆ sftp_dir_eof()

◆ sftp_extension_supported()

◆ sftp_extensions_get_count()

◆ sftp_extensions_get_data()

◆ sftp_extensions_get_name()

◆ sftp_file_set_blocking()

◆ sftp_file_set_nonblocking()

◆ sftp_free()

◆ sftp_fstat()

◆ sftp_fstatvfs()

◆ sftp_fsync()

◆ sftp_get_error()

◆ sftp_init()

◆ sftp_lstat()

◆ sftp_mkdir()

◆ sftp_new()

◆ sftp_new_channel()

◆ sftp_open()

◆ sftp_opendir()

◆ sftp_read()

◆ sftp_readdir()

◆ sftp_readlink()

◆ sftp_rename()

◆ sftp_rewind()

◆ sftp_rmdir()

◆ sftp_seek()

◆ sftp_seek64()

◆ sftp_server_free()

◆ sftp_server_init()

◆ sftp_server_new()

◆ sftp_server_version()

◆ sftp_setstat()

◆ sftp_stat()

◆ sftp_statvfs()

◆ sftp_statvfs_free()

◆ sftp_symlink()

◆ sftp_tell()

◆ sftp_tell64()

◆ sftp_unlink()

◆ sftp_utimes()

◆ sftp_write()