libssh: The libssh SFTP API

libssh 0.12.1 The SSH library

Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Functions
The libssh SFTP API

SFTP handling functions. More...

## Data Structures
struct | sftp_statvfs_struct
| SFTP statvfs structure. More...
struct | sftp_limits_struct
| SFTP limits structure. More...
struct | sftp_name_id_map_struct
| SFTP names map structure to store the mapping between ids and names. More...

## Macros
#define | LIBSFTP_VERSION 3
#define | SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
#define | SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */

## Typedefs
typedef struct sftp_session_struct * | sftp_session
| SFTP session handle.
typedef struct sftp_limits_struct * | sftp_limits_t
typedef struct sftp_aio_struct * | sftp_aio
typedef struct sftp_name_id_map_struct * | sftp_name_id_map

## 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.
SSH_DEPRECATED 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.
SSH_DEPRECATED 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 void | sftp_aio_free (sftp_aio aio)
| Deallocate memory corresponding to a sftp aio handle.
LIBSSH_API ssize_t | sftp_aio_begin_read (sftp_file file, size_t len, sftp_aio *aio)
| Start an asynchronous read from a file using an opened sftp file handle.
LIBSSH_API ssize_t | sftp_aio_wait_read (sftp_aio *aio, void *buf, size_t buf_size)
| Wait for an asynchronous read to complete and store the read data in the supplied buffer.
LIBSSH_API ssize_t | sftp_aio_begin_write (sftp_file file, const void *buf, size_t len, sftp_aio *aio)
| Start an asynchronous write to a file using an opened sftp file handle.
LIBSSH_API ssize_t | sftp_aio_wait_write (sftp_aio *aio)
| Wait for an asynchronous write to complete.
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_lsetstat (sftp_session sftp, const char *file, sftp_attributes attr)
| This request is like setstat (excluding mode and size) but sets file attributes on symlinks themselves.
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 int | sftp_hardlink (sftp_session sftp, const char *oldpath, const char *newpath)
| Create a hard 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 sftp_limits_t | sftp_limits (sftp_session sftp)
| Get information about the various limits the server might impose.
LIBSSH_API void | sftp_limits_free (sftp_limits_t limits)
| Free the memory of an allocated limits.
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 char * | sftp_expand_path (sftp_session sftp, const char *path)
| Canonicalize path using expan.nosp@m.d-pa.nosp@m.th@op.nosp@m.enss.nosp@m.h.com extension.
LIBSSH_API char * | sftp_home_directory (sftp_session sftp, const char *username)
| Get the specified user's home directory.
LIBSSH_API sftp_name_id_map | sftp_name_id_map_new (uint32_t count)
| Create a new sftp_name_id_map struct.
LIBSSH_API void | sftp_name_id_map_free (sftp_name_id_map map)
| Free the memory of an allocated sftp_name_id_map struct.
LIBSSH_API int | sftp_get_users_groups_by_id (sftp_session sftp, sftp_name_id_map users_map, sftp_name_id_map groups_map)
| Retrieves usernames and group names based on provided user and group IDs.
LIBSSH_API sftp_session | sftp_server_new (ssh_session session, ssh_channel chan)
| Create a new sftp server session.
SSH_DEPRECATED 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)
| Reads the next SFTP client message from the session.
LIBSSH_API void | sftp_client_message_free (sftp_client_message msg)
| Free an SFTP client message and its associated resources.
LIBSSH_API uint8_t | sftp_client_message_get_type (sftp_client_message msg)
| Get the SFTP client message type.
LIBSSH_API const char * | sftp_client_message_get_filename (sftp_client_message msg)
| Get the filename associated with an SFTP client message.
LIBSSH_API void | sftp_client_message_set_filename (sftp_client_message msg, const char *newname)
| Set the filename associated with an SFTP client message.
LIBSSH_API const char * | sftp_client_message_get_data (sftp_client_message msg)
| Get the data field of an SFTP client message as a string.
LIBSSH_API uint32_t | sftp_client_message_get_flags (sftp_client_message msg)
| Get the flags associated with an SFTP client message.
LIBSSH_API const char * | sftp_client_message_get_submessage (sftp_client_message msg)
| Get the submessage name associated with an SFTP client message.
LIBSSH_API int | sftp_send_client_message (sftp_session sftp, sftp_client_message msg)
| Send an SFTP client message.
LIBSSH_API int | sftp_reply_name (sftp_client_message msg, const char *name, sftp_attributes attr)
| Send an SFTP NAME reply for a client message.
LIBSSH_API int | sftp_reply_handle (sftp_client_message msg, ssh_string handle)
| Send an SFTP HANDLE reply for a client message.
LIBSSH_API ssh_string | sftp_handle_alloc (sftp_session sftp, void *info)
| Allocate a new SFTP handle slot.
LIBSSH_API int | sftp_reply_attr (sftp_client_message msg, sftp_attributes attr)
| Send an SFTP ATTRS reply for a client message.
LIBSSH_API void * | sftp_handle (sftp_session sftp, ssh_string handle)
| Resolve an SFTP handle to its stored info.
LIBSSH_API int | sftp_reply_status (sftp_client_message msg, uint32_t status, const char *message)
| Send an SFTP STATUS reply.
LIBSSH_API int | sftp_reply_names_add (sftp_client_message msg, const char *file, const char *longname, sftp_attributes attr)
| Add one name entry to a multi-name SFTP reply.
LIBSSH_API int | sftp_reply_names (sftp_client_message msg)
| Send a multi-name SFTP reply.
LIBSSH_API int | sftp_reply_data (sftp_client_message msg, const void *data, int len)
| Send an SFTP DATA reply.
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

## Typedef Documentation

## ◆ sftp_session

typedef struct sftp_session_struct* sftp_session

SFTP session handle.

This type represents an active SFTP session associated with an SSH channel. It is created and destroyed via the libssh SFTP API and is internally managed by libssh. It is used by applications to perform SFTP operations such as file access and directory management.

The internal structure of this type is opaque and must not be accessed directly by applications.

See also
  sftp_new
  sftp_free

## Function Documentation

## ◆ sftp_aio_begin_read()

LIBSSH_API ssize_t sftp_aio_begin_read | ( | sftp_file | file,
|  | size_t | len,
|  | sftp_aio * | aio )

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_aio_begin_read() and sftp_aio_wait_read().

- The first step is to call sftp_aio_begin_read(). This function sends a read request to the sftp server, dynamically allocates memory to store information about the sent request and provides the caller an sftp aio handle to that memory.
- The second step is to call sftp_aio_wait_read() and pass it the address of a location storing the sftp aio handle provided by sftp_aio_begin_read().

These two functions do not close the open sftp file handle passed to sftp_aio_begin_read() irrespective of whether they fail or not.

It is the responsibility of the caller to ensure that the open sftp file handle passed to sftp_aio_begin_read() must not be closed before the corresponding call to sftp_aio_wait_read(). After sftp_aio_wait_read() returns, it is caller's decision whether to immediately close the file by calling sftp_close() or to keep it open and perform some more operations on it.

This function caps the length a user is allowed to read from an sftp file, the value of len parameter after capping is returned on success.

The value used for the cap is same as the value of the max_read_length field of the sftp_limits_t returned by sftp_limits().

Parameters

  file | The opened sftp file handle to be read from.
  len | Number of bytes to read.
  aio | Pointer to a location where the sftp aio handle (corresponding to the sent request) should be stored.

Returns
  On success, the number of bytes the server is requested to read (value of len parameter after capping). On error, SSH_ERROR with sftp and ssh errors set.

Warning
  When calling this function, the internal file offset is updated corresponding to the number of bytes requested to read.
  A call to sftp_aio_begin_read() sends a request to the server. When the server answers, libssh allocates memory to store it until sftp_aio_wait_read() is called. Not calling sftp_aio_wait_read() will lead to memory leaks.

See also
  sftp_aio_wait_read()
  sftp_aio_free()
  sftp_open()
  sftp_close()
  sftp_get_error()
  ssh_get_error()

## ◆ sftp_aio_begin_write()

LIBSSH_API ssize_t sftp_aio_begin_write | ( | sftp_file | file,
|  | const void * | buf,
|  | size_t | len,
|  | sftp_aio * | aio )

Start an asynchronous write to a file using an opened sftp file handle.

Its goal is to avoid the slowdowns related to the request/response pattern of a synchronous write. To do so, you must call 2 functions :

sftp_aio_begin_write() and sftp_aio_wait_write().

- The first step is to call sftp_aio_begin_write(). This function sends a write request to the sftp server, dynamically allocates memory to store information about the sent request and provides the caller an sftp aio handle to that memory.
- The second step is to call sftp_aio_wait_write() and pass it the address of a location storing the sftp aio handle provided by sftp_aio_begin_write().

These two functions do not close the open sftp file handle passed to sftp_aio_begin_write() irrespective of whether they fail or not.

It is the responsibility of the caller to ensure that the open sftp file handle passed to sftp_aio_begin_write() must not be closed before the corresponding call to sftp_aio_wait_write(). After sftp_aio_wait_write() returns, it is caller's decision whether to immediately close the file by calling sftp_close() or to keep it open and perform some more operations on it.

This function caps the length a user is allowed to write to an sftp file, the value of len parameter after capping is returned on success.

The value used for the cap is same as the value of the max_write_length field of the sftp_limits_t returned by sftp_limits().

Parameters

  file | The opened sftp file handle to write to.
  buf | Pointer to the buffer containing data to write.
  len | Number of bytes to write.
  aio | Pointer to a location where the sftp aio handle (corresponding to the sent request) should be stored.

Returns
  On success, the number of bytes the server is requested to write (value of len parameter after capping). On error, SSH_ERROR with sftp and ssh errors set.

Warning
  When calling this function, the internal file offset is updated corresponding to the number of bytes requested to write.
  A call to sftp_aio_begin_write() sends a request to the server. When the server answers, libssh allocates memory to store it until sftp_aio_wait_write() is called. Not calling sftp_aio_wait_write() will lead to memory leaks.

See also
  sftp_aio_wait_write()
  sftp_aio_free()
  sftp_open()
  sftp_close()
  sftp_get_error()
  ssh_get_error()

## ◆ sftp_aio_free()

LIBSSH_API void sftp_aio_free | ( | sftp_aio | aio | ) |

Deallocate memory corresponding to a sftp aio handle.

This function deallocates memory corresponding to the aio handle returned by the sftp_aio_begin_*() functions. Users can use this function to free memory corresponding to an aio handle for an outstanding async i/o request on encountering some error.

Parameters

  aio | sftp aio handle corresponding to which memory has to be deallocated.

See also
  sftp_aio_begin_read()
  sftp_aio_wait_read()
  sftp_aio_begin_write()
  sftp_aio_wait_write()

## ◆ sftp_aio_wait_read()

LIBSSH_API ssize_t sftp_aio_wait_read | ( | sftp_aio * | aio,
|  | void * | buf,
|  | size_t | buf_size )

Wait for an asynchronous read to complete and store the read data in the supplied buffer.

A pointer to an sftp aio handle should be passed while calling this function. Except when the return value is SSH_AGAIN, this function releases the memory corresponding to the supplied aio handle and assigns NULL to that aio handle using the passed pointer to that handle.

If the file is opened in non-blocking mode and the request hasn't been executed yet, this function returns SSH_AGAIN and must be called again using the same sftp aio handle.

Parameters

  aio | Pointer to the sftp aio handle returned by sftp_aio_begin_read().
  buf | Pointer to the buffer in which read data will be stored.
  buf_size | Size of the buffer in bytes. It should be bigger or equal to the length parameter of the sftp_aio_begin_read() call.

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 sftp aio handle may never return.

See also
  sftp_aio_begin_read()
  sftp_aio_free()

## ◆ sftp_aio_wait_write()

LIBSSH_API ssize_t sftp_aio_wait_write | ( | sftp_aio * | aio | ) |

Wait for an asynchronous write to complete.

A pointer to an sftp aio handle should be passed while calling this function. Except when the return value is SSH_AGAIN, this function releases the memory corresponding to the supplied aio handle and assigns NULL to that aio handle using the passed pointer to that handle.

If the file is opened in non-blocking mode and the request hasn't been executed yet, this function returns SSH_AGAIN and must be called again using the same sftp aio handle.

Parameters

  aio | Pointer to the sftp aio handle returned by sftp_aio_begin_write().

Returns
  Number of bytes written on success, 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 sftp aio handle may never return.

See also
  sftp_aio_begin_write()
  sftp_aio_free()

## ◆ sftp_async_read()

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

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

LIBSSH_API void sftp_client_message_free | ( | sftp_client_message | msg | ) |

Free an SFTP client message and its associated resources.

Releases all dynamically allocated fields in the SFTP client message (such as filename, submessage, data, handle, attributes, and cached buffers) and then frees the message structure itself. The function does nothing if msg is NULL.

Parameters

  [in] | msg | The SFTP client message to free, or NULL.

## ◆ sftp_client_message_get_data()

LIBSSH_API const char * sftp_client_message_get_data | ( | sftp_client_message | msg | ) |

Get the data field of an SFTP client message as a string.

Converts the internal ssh_string data field to a string on first use and caches the result in the message. Subsequent calls return the cached pointer.

Parameters

  [in] | msg | The SFTP client message.

Returns
  The data as string, or NULL on error.

## ◆ sftp_client_message_get_filename()

LIBSSH_API const char * sftp_client_message_get_filename | ( | sftp_client_message | msg | ) |

Get the filename associated with an SFTP client message.

Returns the filename carried by the given SFTP client message, if the message type includes a filename field (for example OPEN, REMOVE, RENAME).

Parameters

  [in] | msg | The SFTP client message.

Returns
  Filename string, or NULL if no filename is associated with the message.

## ◆ sftp_client_message_get_flags()

LIBSSH_API uint32_t sftp_client_message_get_flags | ( | sftp_client_message | msg | ) |

Get the flags associated with an SFTP client message.

Returns the flags field stored in the given SFTP client message. The exact meaning of the flags depends on the SFTP message type (for example, open or stat flags).

Parameters

  [in] | msg | The SFTP client message.

Returns
  The flags value as an unsigned 32-bit integer.

## ◆ sftp_client_message_get_submessage()

LIBSSH_API const char * sftp_client_message_get_submessage | ( | sftp_client_message | msg | ) |

Get the submessage name associated with an SFTP client message.

Returns the submessage string stored in the given SFTP client message. This is typically used for vendor-specific SFTP operations.

Parameters

  [in] | msg | The SFTP client message.

Returns
  The submessage name as a string, or NULL if no submessage is associated with the message.

## ◆ sftp_client_message_get_type()

LIBSSH_API uint8_t sftp_client_message_get_type | ( | sftp_client_message | msg | ) |

Get the SFTP client message type.

Returns the SFTP packet type associated with the given client message (for example SSH_FXP_READ, SSH_FXP_WRITE, SSH_FXP_OPEN, ...).

Parameters

  [in] | msg | The SFTP client message.

Returns
  The SFTP message type as an unsigned 8-bit value.

## ◆ sftp_client_message_set_filename()

LIBSSH_API void sftp_client_message_set_filename | ( | sftp_client_message | msg,
|  | const char * | newname )

Set the filename associated with an SFTP client message.

Replaces the current filename stored in the client message with a copy of the given `newname` string.

Parameters

  [in] | msg | The SFTP client message to modify.
  [in] | newname | The new filename to store in the message.

@warn On failure, the filename in the message is set to NULL. Users of sftp_client_message_get_filename() need to check the return value!

## ◆ 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_expand_path()

LIBSSH_API char * sftp_expand_path | ( | sftp_session | sftp,
|  | const char * | path )

Canonicalize path using expan.nosp@m.d-pa.nosp@m.th@op.nosp@m.enss.nosp@m.h.com extension.

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_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:656

## ◆ 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_client_message()

LIBSSH_API sftp_client_message sftp_get_client_message | ( | sftp_session | sftp | ) |

Reads the next SFTP client message from the session.

Reads a single SFTP packet from the given SFTP session and converts it into a parsed sftp_client_message structure.

Parameters

  [in] | sftp | The SFTP session to read from.

Returns
  A newly allocated sftp_client_message on success; NULL if no packet is available or an error occurs.

## ◆ 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_get_users_groups_by_id()

LIBSSH_API int sftp_get_users_groups_by_id | ( | sftp_session | sftp,
|  | sftp_name_id_map | users_map,
|  | sftp_name_id_map | groups_map )

Retrieves usernames and group names based on provided user and group IDs.

The retrieved names are stored in the names field of the sftp_name_id_map structure. In case a uid or gid is not found, an empty string is stored.

This calls the "users-groups-by-id@openssh.com" extension. You should check if the extension is supported using:

int supported = sftp_extension_supported(sftp,
"users-groups-by-id@openssh.com", "1");

Parameters

  sftp | The SFTP session handle.
  users_map | A pointer to a sftp_name_id_map struct with the user IDs. Can be NULL if only group names are needed.
  groups_map | A pointer to a sftp_name_id_map struct with the group IDs. Can be NULL if only user names are needed.

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

Note
  The caller needs to free the memory used for the maps later using sftp_name_id_map_free().

See also
  sftp_get_error()

## ◆ sftp_handle()

LIBSSH_API void * sftp_handle | ( | sftp_session | sftp,
|  | ssh_string | handle )

Resolve an SFTP handle to its stored info.

Decodes the 4-byte `handle` value, checks bounds and returns the pointer stored in the corresponding handle slot in the SFTP session.

Parameters

  [in] | sftp | The SFTP session.
  [in] | handle | The handle value as ssh_string.

Returns
  The stored pointer on success, or NULL if the handle table is not initialized, the handle size is invalid, or the index is out of range.

## ◆ sftp_handle_alloc()

LIBSSH_API ssh_string sftp_handle_alloc | ( | sftp_session | sftp,
|  | void * | info )

Allocate a new SFTP handle slot.

Finds a free handle slot in the SFTP session, stores the given `info` there and returns a 4-byte ssh_string that encodes the handle index.

Parameters

  [in] | sftp | The SFTP session.
  [in] | info | Info to be stored in the handle slot.

Returns
  A new handle as ssh_string on success; NULL if no slot is available or on memory allocation failure.

## ◆ sftp_hardlink()

LIBSSH_API int sftp_hardlink | ( | sftp_session | sftp,
|  | const char * | oldpath,
|  | const char * | newpath )

Create a hard link.

Parameters

  sftp | The sftp session handle.
  oldpath | Specifies the pathname of the file for which the new hardlink is to be created.
  newpath | Specifies the pathname of the hardlink to be created.

Returns
  0 on success, -1 on error with ssh and sftp error set.

See also
  sftp_get_error()

## ◆ sftp_home_directory()

LIBSSH_API char * sftp_home_directory | ( | sftp_session | sftp,
|  | const char * | username )

Get the specified user's home directory.

This calls the "home-directory" extension. You should check if the extension is supported using:

int supported = sftp_extension_supported(sftp, "home-directory", "1");

Parameters

  sftp | The sftp session handle.
  username | username of the user whose home directory is requested.

Returns
  On success, a newly allocated string containing the absolute real-path of the home directory of the user. NULL on error. The caller needs to free the memory using ssh_string_free_char().

## ◆ 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_limits()

LIBSSH_API sftp_limits_t sftp_limits | ( | sftp_session | sftp | ) |

Get information about the various limits the server might impose.

Parameters

  sftp | The sftp session handle.

Returns
  A limits structure or NULL on error.

See also
  sftp_get_error()

## ◆ sftp_limits_free()

LIBSSH_API void sftp_limits_free | ( | sftp_limits_t | limits | ) |

Free the memory of an allocated limits.

Parameters

  limits | The limits to free.

## ◆ sftp_lsetstat()

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

This request is like setstat (excluding mode and size) but sets file attributes on symlinks themselves.

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 symbolic link 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_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_name_id_map_free()

LIBSSH_API void sftp_name_id_map_free | ( | sftp_name_id_map | map | ) |

Free the memory of an allocated sftp_name_id_map struct.

Parameters

  map | A pointer to the sftp_name_id_map struct to free.

## ◆ sftp_name_id_map_new()

LIBSSH_API sftp_name_id_map sftp_name_id_map_new | ( | uint32_t | count | ) |

Create a new sftp_name_id_map struct.

Parameters

  count | The number of ids/names to store in the map.

Returns
  A pointer to the newly allocated sftp_name_id_map struct.

## ◆ 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. The session must be in blocking mode since most sftp_* functions do not support the non-blocking API.

Returns
  A new sftp session or NULL on error.

See also
  sftp_free()
  sftp_init()
  ssh_set_blocking()

## ◆ 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. The session must be in blocking mode since most sftp_* functions do not support the non-blocking API.
  channel | An open session channel with subsystem already allocated

Returns
  A new sftp session or NULL on error.

See also
  sftp_free()
  ssh_set_blocking()

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

This function caps the length a user is allowed to read from an sftp file.

The value used for the cap is same as the value of the max_read_length field of the sftp_limits_t returned by sftp_limits().

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 read, < 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_reply_attr()

LIBSSH_API int sftp_reply_attr | ( | sftp_client_message | msg,
|  | sftp_attributes | attr )

Send an SFTP ATTRS reply for a client message.

Builds and sends an SSH_FXP_ATTRS packet in response to the given SFTP client message, encoding the message id and the provided file attributes.

Parameters

  [in] | msg | The SFTP client message being answered.
  [in] | attr | The file attributes to return to the client.

Returns
  0 on success; -1 on memory allocation failure or packet send error.

## ◆ sftp_reply_data()

LIBSSH_API int sftp_reply_data | ( | sftp_client_message | msg,
|  | const void * | data,
|  | int | len )

Send an SFTP DATA reply.

Sends an SSH_FXP_DATA packet for the given client message, containing the provided data buffer and its length.

Parameters

  [in] | msg | The SFTP client message to reply to.
  [in] | data | The data buffer to send.
  [in] | len | Number of bytes from data to send.

Returns
  0 on success; -1 on memory allocation or packet send error.

## ◆ sftp_reply_handle()

LIBSSH_API int sftp_reply_handle | ( | sftp_client_message | msg,
|  | ssh_string | handle )

Send an SFTP HANDLE reply for a client message.

Builds and sends an SSH_FXP_HANDLE packet in response to the given SFTP client message, containing the provided file `handle`. The message id is taken from the client message and the handle is encoded as an SSH string.

Parameters

  [in] | msg | The SFTP client message being answered.
  [in] | handle | The file handle to return to the client.

Returns
  0 on success; -1 on memory allocation failure or packet send error.

## ◆ sftp_reply_name()

LIBSSH_API int sftp_reply_name | ( | sftp_client_message | msg,
|  | const char * | name,
|  | sftp_attributes | attr )

Send an SFTP NAME reply for a client message.

Builds and sends an SSH_FXP_NAME packet in response to the given SFTP client message, containing a single filename and its attributes. The function encodes the message id, the count of returned names (always 1), the filename fields and the provided attributes.

Parameters

  [in] | msg | The SFTP client message being answered.
  [in] | name | The filename to return to the client.
  [in] | attr | The file attributes associated with the filename.

Returns
  0 on success; -1 on memory allocation failure or packet send error.

## ◆ sftp_reply_names()

LIBSSH_API int sftp_reply_names | ( | sftp_client_message | msg | ) |

Send a multi-name SFTP reply.

Sends an SSH_FXP_NAME packet for the given client message using the accumulated name entries stored in msg->attrbuf and msg->attr_num. After sending, the buffer and counter are reset.

Parameters

  [in] | msg | The SFTP client message to reply to.

Returns
  0 on success; -1 on memory allocation or packet send error.

## ◆ sftp_reply_names_add()

LIBSSH_API int sftp_reply_names_add | ( | sftp_client_message | msg,
|  | const char * | file,
|  | const char * | longname,
|  | sftp_attributes | attr )

Add one name entry to a multi-name SFTP reply.

Appends a `file` name, `longname` and attributes to the buffered NAME reply stored in the client message. Can be called multiple times before the reply is sent.

Parameters

  [in] | msg | The SFTP client message being prepared.
  [in] | file | The filename to add.
  [in] | longname | The long name to add.
  [in] | attr | The file attributes for this entry.

Returns
  0 on success; -1 on memory allocation or buffer write error.

## ◆ sftp_reply_status()

LIBSSH_API int sftp_reply_status | ( | sftp_client_message | msg,
|  | uint32_t | status,
|  | const char * | message )

Send an SFTP STATUS reply.

Sends an SSH_FXP_STATUS packet for the given client message, including the `status` code and an optional human readable `message`. The language tag is sent as an empty string.

Parameters

  [in] | msg | The SFTP client message to reply to.
  [in] | status | The SFTP status code to send (e.g. SSH_FX_OK, SSH_FX_FAILURE).
  [in] | message | Optional text message describing the status, or NULL.

Returns
  0 on success; -1 on memory allocation or packet send 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_send_client_message()

LIBSSH_API int sftp_send_client_message | ( | sftp_session | sftp,
|  | sftp_client_message | msg )

Send an SFTP client message.

Writes the given client message as a packet using the stored message type and complete_message buffer. Can be used in case of proxying.

Parameters

  [in] | sftp | The SFTP session.
  [in] | msg | The client message to send.

Returns
  0 on success; -1 on error from sftp_packet_write().

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

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

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

This function caps the length a user is allowed to write to an sftp file.

The value used for the cap is same as the value of the max_write_length field of the sftp_limits_t returned by sftp_limits().

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