SFTP Functions

Functions
int	sftp_async_read (SFTP_FILE *file, void *data, u32 len, u32 id)
	Wait for an asynchronous read to complete and save the data.
int	sftp_async_read_begin (SFTP_FILE *file, u32 len)
	Start an asynchronous read from a file using an opened sftp file handle.
void	sftp_attributes_free (SFTP_ATTRIBUTES *file)
	Free a sftp attribute structure.
char *	sftp_canonicalize_path (SFTP_SESSION *sftp, const char *path)
	Canonicalize a sftp path.
int	sftp_chmod (SFTP_SESSION *sftp, const char *file, mode_t mode)
	Change permissions of a file.
int	sftp_chown (SFTP_SESSION *sftp, const char *file, uid_t owner, gid_t group)
	Change the file owner and group.
int	sftp_close (SFTP_FILE *file)
	Close an open file handle.
int	sftp_closedir (SFTP_DIR *dir)
	Close a directory handle opened by sftp_opendir().
int	sftp_dir_close (SFTP_DIR *dir) SFTP_DEPRECATED
int	sftp_dir_eof (SFTP_DIR *dir)
	Tell if the directory has reached EOF (End Of File).
int	sftp_file_close (SFTP_FILE *file) SFTP_DEPRECATED
void	sftp_free (SFTP_SESSION *sftp)
	Close and deallocate a sftp session.
SFTP_ATTRIBUTES *	sftp_fstat (SFTP_FILE *file)
	Get information about a file or directory from a file handle.
int	sftp_get_error (SFTP_SESSION *sftp)
	Get the last sftp error.
int	sftp_init (SFTP_SESSION *sftp)
	Initialize the sftp session with the server.
SFTP_ATTRIBUTES *	sftp_lstat (SFTP_SESSION *session, const char *path)
	Get information about a file or directory.
int	sftp_mkdir (SFTP_SESSION *sftp, const char *directory, mode_t mode)
	Create a directory.
SFTP_SESSION *	sftp_new (SSH_SESSION *session)
	Start a new sftp session.
SFTP_FILE *	sftp_open (SFTP_SESSION *session, const char *file, int flags, mode_t mode)
	Open a file on the server.
SFTP_DIR *	sftp_opendir (SFTP_SESSION *session, const char *path)
	Open a directory used to obtain directory entries.
ssize_t	sftp_read (SFTP_FILE *file, void *buf, size_t count)
	Read from a file using an opened sftp file handle.
SFTP_ATTRIBUTES *	sftp_readdir (SFTP_SESSION *session, SFTP_DIR *dir)
	Get a single file attributes structure of a directory.
char *	sftp_readlink (SFTP_SESSION *sftp, const char *path)
	Read the value of a symbolic link.
int	sftp_rename (SFTP_SESSION *sftp, const char *original, const char *newname)
	Rename or move a file or directory.
void	sftp_rewind (SFTP_FILE *file)
	Rewinds the position of the file pointer to the beginning of the file.
int	sftp_rm (SFTP_SESSION *sftp, const char *file) SFTP_DEPRECATED
int	sftp_rmdir (SFTP_SESSION *sftp, const char *directory)
	Remove a directoy.
int	sftp_seek (SFTP_FILE *file, u32 new_offset)
	Seek to a specific location in a file.
int	sftp_seek64 (SFTP_FILE *file, u64 new_offset)
	Seek to a specific location in a file.
int	sftp_server_version (SFTP_SESSION *sftp)
	Get the version of the SFTP protocol supported by the server.
int	sftp_setstat (SFTP_SESSION *sftp, const char *file, SFTP_ATTRIBUTES *attr)
	Set file attributes on a file, directory or symbolic link.
SFTP_ATTRIBUTES *	sftp_stat (SFTP_SESSION *session, const char *path)
	Get information about a file or directory.
int	sftp_symlink (SFTP_SESSION *sftp, const char *target, const char *dest)
	Create a symbolic link.
unsigned long	sftp_tell (SFTP_FILE *file)
	Report current byte position in file.
u64	sftp_tell64 (SFTP_FILE *file)
	Report current byte position in file.
int	sftp_unlink (SFTP_SESSION *sftp, const char *file)
	Unlink (delete) a file.
int	sftp_utimes (SFTP_SESSION *sftp, const char *file, const struct timeval *times)
	Change the last modification and access time of a file.
ssize_t	sftp_write (SFTP_FILE *file, const void *buf, size_t count)
	Write to a file using an opened sftp file handle.

---

Function Documentation

int sftp_async_read	(	SFTP_FILE *	file,
		void *	data,
		u32	len,
		u32	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 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.

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

int sftp_async_read_begin	(	SFTP_FILE *	file,
		u32	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()

void sftp_attributes_free

(

SFTP_ATTRIBUTES *

file

)

Free a sftp attribute structure.

Parameters:

file

The sftp attribute structure to free.

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:

The canonicalize path, NULL on error.

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.

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.

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

See also:

sftp_open()

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

int sftp_dir_close

(

SFTP_DIR *

dir

)

Deprecated:

Use sftp_closedir() instead.

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

int sftp_file_close

(

SFTP_FILE *

file

)

Deprecated:

Use sftp_close() instead.

void sftp_free

(

SFTP_SESSION *

sftp

)

Close and deallocate a sftp session.

Parameters:

sftp

The sftp session handle to free.

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.

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

int sftp_init

(

SFTP_SESSION *

sftp

)

Initialize the sftp session with the server.

Parameters:

sftp

The sftp session to initialize.

Returns:

0 on success, < 0 on error with ssh error set.

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.

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.

SFTP_SESSION* sftp_new

(

SSH_SESSION *

session

)

Start a new sftp session.

Parameters:

session

The ssh session to use.

Returns:

A new sftp session or NULL on error.

SFTP_FILE* sftp_open	(	SFTP_SESSION *	session,
		const char *	file,
		int	flags,
		mode_t	mode
	)

Open a file on the server.

Parameters:

	session	The sftp session handle.
	file	The file to be opened.
	access	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.

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

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 recieve read data.
	count	Size of the buffer in bytes.

Returns:

Number of bytes written, < 0 on error with ssh and sftp error set.

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

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.

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.

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.

int sftp_rm	(	SFTP_SESSION *	sftp,
		const char *	file
	)

Deprecated:

Use sftp_unlink() instead.

int sftp_rmdir	(	SFTP_SESSION *	sftp,
		const char *	directory
	)

Remove a directoy.

Parameters:

	sftp	The sftp session handle.
	directory	The directory to remove.

Returns:

0 on success, < 0 on error with ssh and sftp error set.

int sftp_seek	(	SFTP_FILE *	file,
		u32	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.

int sftp_seek64	(	SFTP_FILE *	file,
		u64	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.

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.

int sftp_setstat	(	SFTP_SESSION *	sftp,
		const char *	file,
		SFTP_ATTRIBUTES *	attr
	)

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

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.

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.

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.

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.

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

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.

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.

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