libssh  0.5.2
Functions
The libssh SFTP API

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.
int sftp_async_read_begin (sftp_file file, uint32_t 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_eof (sftp_dir dir)
 Tell if the directory has reached EOF (End Of File).
int sftp_extension_supported (sftp_session sftp, const char *name, const char *data)
 Check if the given extension is supported.
unsigned int sftp_extensions_get_count (sftp_session sftp)
 Get the count of extensions provided by the server.
const char * sftp_extensions_get_data (sftp_session sftp, unsigned int indexn)
 Get the data of the extension provided by the server.
const char * sftp_extensions_get_name (sftp_session sftp, unsigned int indexn)
 Get the name of the extension provided by the server.
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.
sftp_statvfs_t sftp_fstatvfs (sftp_file file)
 Get information about a mounted file system.
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 accesstype, 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_rmdir (sftp_session sftp, const char *directory)
 Remove a directoy.
int sftp_seek (sftp_file file, uint32_t new_offset)
 Seek to a specific location in a file.
int sftp_seek64 (sftp_file file, uint64_t 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.
sftp_statvfs_t sftp_statvfs (sftp_session sftp, const char *path)
 Get information about a mounted file system.
void sftp_statvfs_free (sftp_statvfs_t statvfs_o)
 Free the memory of an allocated statvfs.
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.
uint64_t 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.

Server responses

Responses returned by the sftp server.

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

Function Documentation

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()
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()
void sftp_attributes_free ( sftp_attributes  file)

Free a sftp attribute structure.

Parameters:
fileThe sftp attribute structure to free.
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.
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.
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.
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()
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.
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()
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");
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.
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.
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.
void sftp_free ( sftp_session  sftp)

Close and deallocate a sftp session.

Parameters:
sftpThe sftp session handle to free.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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()
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.
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.
void sftp_rewind ( sftp_file  file)

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

Parameters:
fileOpen sftp file handle.
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.
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.
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.
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.
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.
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.
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.
void sftp_statvfs_free ( sftp_statvfs_t  statvfs_o)

Free the memory of an allocated statvfs.

Parameters:
statvfs_oThe statvfs to free.
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.
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.
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.
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.
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.
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()