Table of Contents
Table of Contents
libssh2_session_init_ex — initialize a libssh2 session handle
#include <libssh2.h> LIBSSH2_SESSION * libssh2_session_init_ex(LIBSSH2_ALLOC_FUNC *allocfunc, LIBSSH2_FREE_FUNC *freefunc, LIBSSH2_REALLOC_FUNC *reallocfunc void *data); LIBSSH2_SESSION * libssh2_session_init();
The libssh2_session_init_ex() function initializes an SSH2 session and returns a session handle of type LIBSSH2_SESSION. If provided, libssh2 will use the allocfunc, freefunc and reallocfunc parameters for all internal memory management calls. In this case, the data parameter may optionally be passed to the provided callbacks.
As a convenience, the libssh2_session_init() macro is provided, which uses the system's memory management.
libssh2_banner_set — set the SSH prococol banner for the local client
#include <libssh2.h> #include <libssh2_sftp.h> int libssh2_banner_set(LIBSSH2_SESSION *session, char *banner);
This function sets the banner that will be sent to the remote host when the SSH session is started with libssh2_session_startup(). This is optional; a banner corresponding to the protocol and libssh2 version will be sent by default.
On success, 0 is returned. In case of failure, -1 is returned and libssh2_session_last_error() may be called to retrieve the error that occurred.
libssh2_session_method_pref — set preferred key exchange method
#include <libssh2.h> int libssh2_session_method_pref(LIBSSH2_SESSION *session, int method_type, char *prefs);
This function sets preferred methods for key exchange and related algorithms for session. method_type denotes the type of preference to set, and prefs contains a comma-separated list of methods relevant to that preference. method_type may be one of the following:
Key exchange method names. Supported values:
Diffie-Hellman key exchange with SHA-1 as hash, and Oakley Group 2 (see RFC 2409).
Diffie-Hellman key exchange with SHA-1 as hash, and Oakley Group 14 (see RFC 3526).
Diffie-Hellman key exchange with SHA-1 as hash, using a safe-prime/generator pair (chosen by server) of arbitrary strength (specified by client). (see ietf draft secsh-dh-group-exchange)
Public key algorithms. Supported values:
Based on the Digital Signature Standard (FIPS-186-2)
Based on PKCS#1 (RFC 3447)
Encryption algorithm from client to server. Supported algorithms:
AES in CBC mode, with 256-bit key
Alias for aes256-cbc
AES in CBC mode, with 192-bit key
AES in CBC mode, with 128-bit key
Blowfish in CBC mode
ARCFOUR stream cipher
CAST-128 in CBC mode
three-key 3DES in CBC mode
No encyption
Encryption algorithm from server to client. See LIBSSH2_METHOD_CRYPT_CS for supported algorithms.
Message Authentication Code (MAC) algorithms from client to server. Supported values:
SHA-1 with 20-byte digest and key length
SHA-1 with 20-byte key length and 12-byte digest length
MD5 with 16-byte digest and key length
MD5 with 16-byte key length and 12-byte digest length
RIPEMD-160 algorithm with 20-byte digest length
Alias for hmac-ripemd160
Message Authentication Code (MAC) algorithms from server to client. See LIBSSH2_METHOD_MAC_SC for supported algorithms.
Compression methods from client to server. Supported values:
The "zlib" compression method as described in RFC 1950 and RFC 1951
No compression
Compression methods from server to client. See LIBSSH2_METHOD_COMP_CS for supported compression methods.
If successful, 0 is returned. In case of failure, -1 is returned and libssh2_session_last_error() must be used to find out the error that occurred.
libssh2_session_methods — return the currently active algorithms
#include <libssh2.h> char *libssh2_session_methods(LIBSSH2_SESSION *session, int method_type);
This function returns the methods currently active on session for the given method_type. For a list of valid method_type values, see libssh2_session_method_pref().
If successful, a pointer to a comma-separated list of active methods is returned. In case of failure, NULL is returned and libssh2_session_last_error() must be used to find out the error that occurred.
The returned pointer must NOT be freed.
libssh2_session_callback_set — set a callback function
#include <libssh2.h> void* libssh2_session_callback_set(LIBSSH2_SESSION *session, int cbtype, void *callback);
This function sets a callback function for various events related to session. The cbtype parameter may be one of the following values:
Called when an SSH_MSG_IGNORE packet is received. message/message_len represent the entire payload portion of the packet after decryption and decompression. See LIBSSH2_IGNORE_FUNC.
Called when an SSH_MSG_DEBUG packet is received. See LIBSSH2_DEBUG_FUNC.
Called when an SSH_MSG_DISCONNECT packet is received.
reason corresponds to the SSH Disconnect Codes.
If the connection is uncleanly terminated then this callback will not be triggered.
See LIBSSH2_DISCONNECT_FUNC.
Called when a Message Authentication Code (MAC) error occurs at any time during the session lifetime. See LIBSSH2_MACERROR_FUNC.
On success, the previous callback for the given cbtype is returned. Otherwise, NULL is returned.
libssh2_session_startup — start ssh2 on a socket
libssh2_session_disconnect_ex — disconnect a session
#include <libssh2.h> int libssh2_session_disconnect_ex(LIBSSH2_SESSION *session, int reason, char *description, char *lang); int libssh2_session_disconnect(LIBSSH2_SESSION *session, char *description);
libssh2_session_disconnect_ex() sends a disconnect message to the remote host associated with session, along with a reason symbol and a verbose description.
As a convenience, the macro libssh2_session_disconnect() is provided. It calls libssh2_session_disconnect_ex() with reason set to SSH_DISCONNECT_BY_APPLICATION and lang set to an empty string.
On success, 0 is returned. In case of error, -1 is returned, and the errorcode can be retrieved with libssh2_session_last_error().
libssh2_session_abstract — return a pointer to a session's abstract pointer
This function returns a void** pointer to the void *abstract value passed to libssh2_session_init_ex().
libssh2_session_last_error — return the last error code
#include <libssh2.h> int libssh2_session_last_error(LIBSSH2_SESSION *session, char **errmsg, int *errmsg_len, int want_buf);
This function returns session's last error code reported by a previous libssh2 function call. A verbose description of the specific error is copied into errmsg, up to errmsg_len bytes. If want_buf is non-zero, the string placed into errmsg must be freed by the calling program. Otherwise it is assumed to be owned by libssh2.
Table of Contents
libssh2_hostkey_hash — return a hash of the remote host's key
#include <libssh2.h> unsigned char * libssh2_hostkey_hash(LIBSSH2_SESSION *session, int hashtype);
This function returns a hash of the remote host's key . A session with the remote host should be established beforehand, by calling libssh2_session_startup(). The hashtype can be determined by passing one of the following:
If an error occurs, NULL will be returned.
The returned string is not NULL-terminated. The length of the returned string is either 16 bytes in case of MD5, or 20 bytes when SHA1 is used. The returned string is static storage, and must not be freed.
libssh2_userauth_password_ex — authenticate a session with username and password
#include <libssh2.h> int libssh2_userauth_password_ex(LIBSSH2_SESSION *session, char *username, int username_len, char *password, int password_len, LIBSSH2_PASSWD_CHANGEREQ_FUNC *passwdchangefunc); int libssh2_userauth_password(LIBSSH2_SESSION *session, char *username, char *password);
The libssh2_userauth_password_ex() function authenticates a session using username and password of length username_len and password_len, respectively. passwdchangefunc will be called if the remote host requests a password change.
As a convenience, the libssh2_userauth_password() macro is provided, which works out the lengths of the username and password provided, and supplies to callback function for changing the password on request. In this case, the LIBSSH2_ERROR_PASSWORD_EXPIRED error code will be returned.
If successful, 0 is returned. In case of error, -1 is returned and libssh2_session_last_error() will returned the error that occurred. See below for a list of errorcodes that may be returned.
libssh2_userauth_publickey_fromfile — authenticate a session with a public key, read from a file
#include <libssh2.h> int libssh2_userauth_publickey_fromfile(LIBSSH2_SESSION *session, char *username, char *publickey, char *privatekey, char *passphrase);
This function authenticates a session as username using a key pair found in the publickey and privatekey files, and passphrase if provided.
0 is returned if authentication succeeds. In case of error, -1 is returned, and libssh2_session_last_error() will return one of the errorcodes below.
libssh2_userauth_list — list the authentication methods supported by a server
#include <libssh2.h> char *libssh2_userauth_list(LIBSSH2_SESSION *session, char *username, int username_len);
This function provides a list of authentication methods supported by the server associated with session. An optional username may be provided, the length of which is passed in username_len.
On success, a NULL-terminated string containing a comma-separated list of authentication methods is returned. This string must be freed after use.
If the server accepts an unauthenticated session for the given username, NULL is returned and libssh2_userauth_authenticated() will return a non-zero value.
If an error occurred, NULL will be returned and libssh2_session_last_error() must be used to find out which error occurred.
Table of Contents
libssh2_channel_open_ex — establish a generic session channel
#include <libssh2.h> LIBSSH2_CHANNEL *libssh2_channel_ex(LIBSSH2_SESSION *session, char *channel_type, int channel_type_len, int window_size, int packet_size); LIBSSH2_CHANNEL *libssh2_channel_open_session(LIBSSH2_SESSION *session);
The libssh2_channel_open_ex() function opens a generic channel on the given session. The channel_type is according to the SSH2 specification, for example "session". channel_type_len is the length of the channel_type string. window_size specifies the inital window size for the new channel, and packet_size sets the maximum packet size to be sent over the channel.
As a convencience, the libssh2_channel_open_session() macro is provided, which defaults channel_type to "session", window_size to 65536 and packet_size to 16384.
On success, a new LIBSSH2_CHANNEL handle is returned. In case of error, NULL is returned, and the error can be retrieved with libssh2_session_last_error().
libssh2_channel_setenv_ex — set an environment variable on the channel
#include <libssh2.h> int libssh2_channel_setenv_ex(LIBSSH2_CHANNEL, char *varname, int varname_len, char *value, int value_len); int libssh2_channel_setenv(LIBSSH2_CHANNEL, char *varname, char *value);
The libssh2_channel_setenv_ex() function sets environment variable varname to value on channel. varname_len and value_len are the lengths of the respective variables.
As a convenience, the libssh2_channel_setenv() macro is provided, which fills in the lengths of varname and value.
If successful, 0 is returned. In case of error, or the remote host refuses to allow this environment variable to be set, -1 is returned and the errorcode can be retrieved with libssh2_session_last_error().
libssh2_channel_request_pty_ex — request a terminal on a channel
#include <libssh2.h> int libssh2_channel_request_pty_ex(LIBSSH2_CHANNEL, char *terminaltype, int terminaltype_len char *modes, int modes_len, int width, int height, int width_px, int height_px); int libssh2_channel_request_pty(LIBSSH2_CHANNEL, char *terminaltype);
The libssh2_channel_request_pty_ex() function requests a terminal on the channel. The terminaltype is a terminal identifier from termcap or terminfo, and terminaltype_len is the length of this string. It will be made available as the TERM environment variable.
The optional width_px and height_px parameters inform the remote end of the local terminal's dimensions in pixels. If provided, the width and height parameters override width_px and height_px, and specify the dimensions of the local terminal in characters.
The modes parameter is used to communicate to the remote host the capabilities the local terminal supports. Refer to the SSH Connection Protocol standard for detailed information on this parameter. modes_len specifies the length of the modes parameter.
As a convenience, the libssh2_channel_request_pty() function is provided, which supplies the length of the passed in terminaltype parameter, sets width to 80 and height to 24.
On success, 0 is returned. In case of failure, -1 is returned and the error can be retrieved with libssh2_session_last_error().
libssh2_channel_process_startup — request a shell on a channel
#include <libssh2.h> int libssh2_channel_process_startup(LIBSSH2_CHANNEL, char *request, int request_len, char *message, int message_len); int libssh2_channel_shell(LIBSSH2_CHANNEL); int libssh2_channel_exec(LIBSSH2_CHANNEL, char *command); int libssh2_channel_subsystem(LIBSSH2_CHANNEL, char *subsystem);
libssh2_channel_process_startup() starts a process on the remote host associated with channel. The process type is passed in request, and an optional message, specific to the request, may be passed. request_len and message_len are the lengths of the respective parameters.
As a convenience, the following macros are defined:
libssh2_channel_shell() starts a shell on the remote host.
libssh2_channel_exec() runs command on the remote host.
libssh2_channel_subsystem() runs subsystem on the remote host.
On success, 0 is returned. In case of failure, -1 is returned and the errorcode can be retrieved with libssh2_session_last_error().
libssh2_channel_read_ex — read from a channel
#include <libssh2.h> int libssh2_channel_read_ex(LIBSSH2_CHANNEL *channel, int stream_id, char *buf, size_t buflen); int libssh2_channel_read(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen); int libssh2_channel_read_stderr(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen);
libssh2_channel_read_ex() reads up to buflen bytes from channel, and stores these in buf. The stream_id can be either 0 to read from the channel's standard input, or SSH_EXTENDED_DATA_STDERR, for the channel's standard error. The number of bytes read is returned.
As a convenience, the macros libssh2_channel_read() and libssh2_channel_read_stderr() are provided. These call libssh2_channel_read_ex() with stream_id set to the channel's standard output and standard error, respectively.
libssh2_channel_write_ex — write to a channel
#include <libssh2.h> int libssh2_channel_write_ex(LIBSSH2_CHANNEL *channel, int stream_id, char *buf, size_t buflen); int libssh2_channel_write(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen); int libssh2_channel_write_stderr(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen);
libssh2_channel_write_ex() writes buflen bytes from buf to a channel. The stream_id can be either 0 to write to the channel's standard output, or SSH_EXTENDED_DATA_STDERR, for the channel's standard error.
As a convenience, the macros libssh2_channel_write() and libssh2_channel_write_stderr() are provided. These call libssh2_channel_write_ex() with stream_id set to the channel's standard output and standard error, respectively.
Returns the number of bytes written if successful, or -1 in case of error. In this case, the errorcode can be retrieved with libssh2_session_last_error().
libssh2_channel_handle_extended_data — set extended data handling mode
#include <libssh2.h> void libssh2_channel_handle_extended_data(LIBSSH2_CHANNEL *channel, int ignore_mode);
This function sets the extended data behaviour on channel. ignore_mode may be one of the following:
Keep data in separate channels, i.e. use libssh2_channel_read_stderr() to read extended data. This is the default.
Ignore all extended data.
Merge extended data into regular channel input.
libssh2_channel_flush_ex — flush a channel
#include <libssh2.h> int libssh2_channel_flush_ex(LIBSSH2_CHANNEL *channel, int streamid); int libssh2_channel_flush(LIBSSH2_CHANNEL *channel); int libssh2_channel_flush_stderr(LIBSSH2_CHANNEL *channel);
This function flushes all queued data on channel. stream_id may be either 0 for the channel's stdout, or SSH_EXTENDED_DATA_STDERR for stderr.
As a convenience, the libssh2_channel_flush() and libssh2_channel_flush_stderr() macros are provided, which set stream_id to the respective values.
On success, the total number of bytes flushed is returned. In case of error, -1 is returned, and the error can be retrieved with libssh2_session_last_error().
libssh2_channel_set_blocking — enable or disable blocking on a channel
#include <libssh2.h> void libssh2_channel_set_blocking(LIBSSH2_CHANNEL *channel, int blocking);
libssh2_channel_send_eof — send EOF to remote server
Send an EOF to the remote server on this channel.
Returns 0 if successful, or -1 in case of failure. In this case, the errorcode can be retrieved with libssh2_session_last_error().
libssh2_channel_close — close a channel
This function closes the specified channel.
On success, 0 is returned. In case of error, -1 is returned and the errorcode can be retrieved with libssh2_session_last_error().
libssh2_channel_direct_tcpip_ex — Tunnel a TCP connection through an SSH session
#include <libssh2.h> LIBSSH2_CHANNEL *libssh2_channel_direct_tcpip_ex(LIBSSH2_SESSION *session, char *host, int port, char *shost, int sport); LIBSSH2_CHANNEL *libssh2_channel_direct_tcpip(LIBSSH2_SESSION *session, char *host, int port);
This function creates a TCP connection from the remote host associated with session to host on TCP port, and associates this connection with a new channel.
The shost and sport parameters specify the address and port the remote host should bind to for this connection.
As a convenience, the libssh2_channel_direct_tcpip() function is provided, which sets the shost and sport parameters to "127.0.0.1" and "22", respectively.
On success, a new LIBSSH2_CHANNEL handle is returned. In case of error, NULL is returned, and the error can be retrieved with libssh2_session_last_error().
libssh2_channel_forward_listen_ex — set up a forwarded TCP port
#include <libssh2.h> LIBSSH2_LISTENER *libssh2_channel_forward_listen_ex(LIBSSH2_SESSION *session, char *host, int port, int *bound_port, int queue_maxsize); LIBSSH2_LISTENER *libssh2_channel_forward_listen(LIBSSH2_SESSION *session, int port);
This function sets up a listening TCP port on the remote host, connections to which will be forwarded across the encrypted SSH2 session.
The host parameter, if not NULL, represents the address the remote host will bind the port to. It defaults to "0.0.0.0". The port parameter specifies the port to listen on, but may be 0 if the server may choose a free port. In this case, the port that was bound is returned in the bound_port pointer, if not NULL. The queue_maxsize parameter specifies the maximum number of queued connection requests that will be allowed before the remote server refuses new connections on the port.
As a convenience, the libssh2_channel_forward_listen() macro is provided, which sets the host and bound_port parameters to NULL, and the queue_maxsize parameter to 16.
If successful, this function returns a LIBSSH2_LISTENER handle. In case of error, NULL is returned and libssh2_session_last_error() can be used to find out more details.
libssh2_channel_forward_cancel — cancel a forwarded TCP port
This function cancels a previously request TCP port forwarding associated with listener.
On success, 0 is returned. In case of failure, -1 is returned and libssh2_session_last_error() must be used to find out the error that occurred.
libssh2_channel_forward_accept — accept a connection on a TCP port
#include <libssh2.h> LIBSSH2_CHANNEL *libssh2_channel_forward_accept(LIBSSH2_LISTENER *listener);
This function accepts an incoming connection on the forwarded TCP port associated with listener.
On success, a new LIBSSH2_CHANNEL handle is returned. In case of error, NULL is returned.
Table of Contents
libssh2_scp_recv — request a remote file via SCP
#include <libssh2.h> LIBSSH2_CHANNEL *libssh2_scp_recv(LIBSSH2_SESSION *session, char *path, struct stat *sb);
This function opens a channel on session and requests a file via the SCP protocol. The filename is passed in the path parameter. If the sb parameter is passed in, it should point to a stat structure, which will be filled in with the remote file's modification times, access times, and permission modes. See stat(2) for details on this structure.
If successful, this function returns a LIBSSH2_CHANNEL pointer, via which the file can be retrieved with calls to libssh2_channel_read_ex(). In case of error, NULL is returned and libssh2_session_last_error() can be used to find out more details.
libssh2_scp_send_ex — Send a file via SCP
#include <libssh2.h> LIBSSH2_CHANNEL *libssh2_scp_send_ex(LIBSSH2_SESSION *session, char *path, int mode, size_t filesize, long mtime, long atime); LIBSSH2_CHANNEL *libssh2_scp_send(LIBSSH2_SESSION *session, char *path, int mode, size_t filesize);
This function requests a file send via SCP to the remote host associated with session. The remote filename will be the same as (the basename of) path. The mode (permissions), filesize, mtime (last modification time) and atime (last access time) are passed to the remote host.
As a convenience, the libssh2_scp_send() macro is provided, which sets the mtime and atime parameters to 0.
This function returns a new LIBSSH2_CHANNEL handle, which should be used in successive calls to libssh2_channel_write_ex() to send the file. In case of error, NULL is returned and libssh2_session_last_error() can be used to find out more details.
Table of Contents
libssh2_sftp_init — start an SFTP session
#include <libssh2.h> #include <libssh2_sftp.h> LIBSSH2_SFTP *libssh2_sftp_init(LIBSSH2_SESSION *session);
This function starts an SFTP channel on session.
On success, a LIBSSH2_SFTP handle is returned. In case of failure, NULL is returned, and libssh2_session_last_error() can be used to retrieve the error that occurred.
libssh2_sftp_shutdown — shut down an SFTP session
#include <libssh2.h> #include <libssh2_sftp.h> int libssh2_sftp_shutdown(LIBSSH2_SFTP *sftp);
libssh2_sftp_open_ex — open and possibly create a file on a remote host
#include <libssh2.h> #include <libssh2_sftp.h> LIBSSH2_SFTP_HANDLE *libssh2_sftp_open_ex(LIBSSH2_SFTP *sftp, char *filename, int filename_len, unsigned long flags, long mode, int open_type); LIBSSH2_SFTP_HANDLE *libssh2_sftp_open(LIBSSH2_SFTP *sftp, char *filename, unsigned long flags, long mode); LIBSSH2_SFTP_HANDLE *libssh2_sftp_opendir(LIBSSH2_SFTP *sftp, char *path);
The libssh2_sftp_open_ex() function attempts to open filename (with length filename_len) on the sftp session.
The flags parameter is either 0, or a combination of the following:
Open the file for reading (POSIX: O_RDONLY)
Open the file for writing (POSIX: O_WRONLY)
The file is opened in append mode (POSIX: O_APPEND)
If the file does not exist, it will be created (POSIX: O_CREAT)
If the file already exists, truncate it to 0 length (POSIX: O_TRUNC)
Attempts to acquire an exclusive write lock, when used together with SSH2_FXF_CREAT (POSIX: O_EXCL)
The mode parameter is ignored if an existing file is opened. If a new file is created, it corresponds to the permissions field in a LIBSSH2_SFTP_ATTRIBUTES structure.
The open_type parameter can be either LIBSSH2_SFTP_OPENFILE or LIBSSH2_SFTP_OPENDIR to open a file or directory, respectively.
As a convenience, the libssh2_sftp_open() and libssh2_sftp_opendir() macros are provided. They fill in the filename_len and open_type parameters appropriately.
On success, a new LIBSSH2_SFTP_HANDLE is returned. In case of failure, NULL is returned, and libssh2_session_last_error() can be used to retrieve the error that occurred.
libssh2_sftp_read — read from an SFTP file handle
#include <libssh2.h> #include <libssh2_sftp.h> size_t libssh2_sftp_read(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen);
This function reads up to buffer_maxlen bytes into buffer from handle.
On success, the number of bytes read is returned. In case of failure, -1 is returned and libssh2_session_last_error() can be used to retrieve the error that occurred.
libssh2_sftp_readdir — read an entry from an SFTP directory
#include <libssh2.h> #include <libssh2_sftp.h> int libssh2_sftp_readdir(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen, LIBSSH2_SFTP_ATTRIBUTES *attrs);
This function reads an entry from the directory specified in LIBSSH2_SFTP_HANDLE. The filename is stored into buffer, which is buffer_maxlen bytes long. The file attributes are stored in attrs.
On success, the length of the filename is returned. To get all the entries in a directory, call this function until 0 is returned. In case of error, -1 is returned, and libssh2_session_last_error() can be used to retrieve the error that occurred.
NOTE: the returned filename is not NULL-terminated, this the returned filename length must be used.
libssh2_sftp_write — write data to an SFTP file handle
#include <libssh2.h> #include <libssh2_sftp.h> size_t libssh2_sftp_write(LIBSSH2_SFTP_HANDLE *handle, const char *buffer, size_t count);
This function writes count bytes from buffer to handle.
The function returns the number of bytes written, or -1 in case of error. Use libssh2_session_last_error() to find out which erorr occurred.
libssh2_sftp_fstat_ex — get or set attributes on a file handle
#include <libssh2.h> #include <libssh2_sftp.h> int libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs, int setstat); int libssh2_sftp_fstat(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs); int libssh2_sftp_fsetstat(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs);
If setstat is non-zero, this function passes the attrs structure to the remote host, to be set on the file associated with handle.
If setstat is 0, the attrs structure will be filled with the attributes of the file associated with handle.
As a convenience, the libssh2_sftp_fstat() and libssh2_sftp_fsetstat() macros are provided, which call libssh2_sftp_fstat_ex() with the setstat parameter set to 0 and 1, respectively.
On success, 0 is returned. In case of failure, -1 is returned and libssh2_session_last_error() can be used to find out which error occurred.
libssh2_sftp_seek — set the read/write position indicator to a position within a file
#include <libssh2.h> #include <libssh2_sftp.h> void libssh2_sftp_seek(LIBSSH2_SFTP_HANDLE *handle, size_t offset);
libssh2_sftp_tell — get the current read/write position indicator for a file
#include <libssh2.h> #include <libssh2_sftp.h> size_t libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE *handle);
libssh2_sftp_close_handle — close filehandle
#include <libssh2.h> #include <libssh2_sftp.h> int libssh2_sftp_close_handle(LIBSSH2_SFTP_HANDLE *handle);
This function closes handle.
If successful, 0 is returned. In case of failure, -1 is returned and libssh2_session_last_error() can be used to retrieve the error that occurred.
libssh2_sftp_unlink_ex — delete a file
#include <libssh2.h> #include <libssh2_sftp.h> int libssh2_sftp_unlink_ex(LIBSSH2_SFTP *sftp, char *filename, int filename_len) int libssh2_sftp_unlink(LIBSSH2_SFTP *sftp, char *filename)
This function deletes filename (with length filename_len) from the remote server associated with sftp.
As a convenience, the libssh2_sftp_unlink() macro is provided, which fills in the filename_len parameter appropriately.
On success, 0 is returned. In case of failure, -1 is returned and libssh2_session_last_error() can be used to find out which error occurred.
libssh2_sftp_rename_ex — rename a file
#include <libssh2.h> #include <libssh2_sftp.h> int libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp, char *source_filename, int source_filename_len, char *dest_filename, int dest_filename_len, long flags); int libssh2_sftp_rename(LIBSSH2_SFTP, char *source_filename, char *dest_filename);
The libssh2_sftp_rename_ex() function renames source_filename to dest_filename on the server associated with sftp. source_filename_len and dest_filename_len specify the lengths of the corresponding parameters.
The flags parameter is either 0, or a combination of the following:
Overwrite any existing file with the same name as dest_filename.
If dest_filename already exists and this flag is specified, the rename will be done in an atomic operation.
The server is free to do the rename operation in whatever way it chooses. Any other set flags are to be taken as hints to the server.
As a convenience, the libssh2_sftp_rename() macro is provided, which fills in source_filename_len and dest_filename_len with the appropriate values, and sets flags to all 3 options above.
In case of success, 0 is returned. In case of failure, -1 is returned and libssh2_session_last_error() can be used to find out which error occurred. If the error is LIBSSH2_ERROR_SFTP_PROTOCOL, the application may then call libssh2_sftp_last_error() to get the specific SFTP protocol error.
libssh2_sftp_mkdir_ex — create a directory
#include <libssh2.h> #include <libssh2_sftp.h> int libssh2_sftp_mkdir_ex(LIBSSH2_SFTP *sftp, char *path, int path_len, long mode); int libssh2_sftp_mkdir(LIBSSH2_SFTP *sftp, char *path, long mode);
The libssh2_sftp_mkdir_ex() creates a directory on the server associated with sftp. The directory name is provided in path, and the length of this parameter is provided in path_len. The mode parameter corresponds to the POSIX standard st_mode field as defined in stat(2).
As a convenience, the libssh2_sftp_mkdir() macro is provided, which supplies the appropriate value for path_len.
On success, 0 is returned. In case of failure, -1 is returned and libssh2_session_last_error() can be used to find out which error occurred. If the error is LIBSSH2_ERROR_SFTP_PROTOCOL, the application may then call libssh2_sftp_last_error() to get the specific SFTP protocol error.
libssh2_sftp_rmdir_ex — remove a directory
#include <libssh2.h> #include <libssh2_sftp.h> int libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp, char *path, int path_len); int libssh2_sftp_rmdir(LIBSSH2_SFTP *sftp, char *path);
The libssh2_sftp_rmdir_ex() function removes a directory on the remote system associated with sftp. The directory name is provided in path, and the length of this parameter is provided in path_len.
As a convenience, the libssh2_sftp_rmdir() macro is provided, which supplies the appropriate value for path_len.
On success, 0 is returned. In case of failure, -1 is returned and libssh2_session_last_error() can be used to find out which error occurred. If the error is LIBSSH2_ERROR_SFTP_PROTOCOL, the application may then call libssh2_sftp_last_error() to get the specific SFTP protocol error.
libssh2_sftp_stat_ex — get or set attributes on a file or symbolic link
#include <libssh2.h> #include <libssh2_sftp.h> int libssh2_sftp_stat_ex(LIBSSH2_SFTP *sftp, char *path, int path_len, int stat_type, LIBSSH2_SFTP_ATTRIBUTES *attrs); int libssh2_sftp_stat(LIBSSH2_SFTP *sftp, char *path, LIBSSH2_SFTP_ATTRIBUTES *attrs); int libssh2_sftp_lstat(LIBSSH2_SFTP *sftp, char *path, LIBSSH2_SFTP_ATTRIBUTES *attrs); int libssh2_sftp_setstat(LIBSSH2_SFTP *sftp, char *path, LIBSSH2_SFTP_ATTRIBUTES *attrs);
The libssh2_sftp_stat_ex() function is used to get or set attributes on the remote host associated with sftp. The filename is provided in path, and the length of this string is in path_len. In case of a get operation, the attrs parameter will be filled in with the specified file's attributes. In case of a set operation, the attrs parameter holds the attributes that will be set on the remote file.
The stat_type parameter may be one of the following:
The operation is a setstat.
The operation is a get, and symbolic links will not be followed.
The operation is a get, and symbolic links will be followed.
As a convenience, the libssh2_sftp_setstat(), libssh2_sftp_lstat() and libssh2_sftp_stat() macros are provided. These provide the appropriate value for path_len and set stat_type to the corresponding value.
In case of success, 0 is returned. In case of failure, -1 is returned and libssh2_session_last_error() can be used to find out which error occurred. If the error is LIBSSH2_ERROR_SFTP_PROTOCOL, the application may then call libssh2_sftp_last_error() to get the specific SFTP protocol error.
libssh2_sftp_symlink_ex — read or set a symbolic link
#include <libssh2.h> #include <libssh2_sftp.h> int libssh2_sftp_symlink_ex(LIBSSH2_SFTP *sftp, const char *path, int path_len, char *target, int target_len, int link_type); int libssh2_sftp_symlink(LIBSSH2_SFTP *sftp, char *path, char *target); int libssh2_sftp_readlink(LIBSSH2_SFTP *sftp, char *path, char *target, int max_target_len);
The libssh2_sftp_symlink_ex() function is used to create or read a symbolic link on the remote server associated with sftp.
The link_type parameter may be one of the following:
Create a symbolic link named path, pointing to the file provided in target. The path_len and target_len parameters should contain the length of the respective strings.
Read the target of the symbolic link named path, the length of which is given in path_len. The returned filename will be stored in the buffer pointed to by target. The length of this buffer is specified in target_len.
As a convenience, the libssh2_sftp_symlink() and libssh2_sftp_readlink() macros are provided. These call libssh2_sftp_symlink_ex() with link_type set to the respective values.
In case of success, 0 is returned. In case of failure, -1 is returned and libssh2_session_last_error() can be used to find out which error occurred. If the error is LIBSSH2_ERROR_SFTP_PROTOCOL, the application may then call libssh2_sftp_last_error() to get the specific SFTP protocol error.
libssh2_sftp_realpath — resolve a filename's path
#include <libssh2.h> #include <libssh2_sftp.h> int libssh2_sftp_realpath(LIBSSH2_SFTP *sftp, char *path, char *target, int max_target_len);
In case of success, 0 is returned. In case of failure, -1 is returned and libssh2_session_last_error() can be used to find out which error occurred. If the error is LIBSSH2_ERROR_SFTP_PROTOCOL, the application may then call libssh2_sftp_last_error() to get the specific SFTP protocol error.
libssh2_sftp_last_error — return the last SFTP-specific error code
#include <libssh2.h> #include <libssh2_sftp.h> unsigned long libssh2_sftp_last_error(LIBSSH2_SFTP *sftp);
This function returns the last error specific to SFTP. The error codes are as defined in the SFTP File Transfer Protocol standard. See LIBSSH2_ERROR_SFTP_PROTOCOL for more information.
Data types.
libssh2 session handle
libssh2 channel handle
libssh2 port forwarding handle
libssh2 SFTP handle
libssh2 SFTP file handle
libssh2 SFTP file attribute structure
unsigned long flags; unsigned long filesize; unsigned long uid, gid; unsigned long permissions; unsigned long atime, mtime;
If the flags parameter is anded with one of the following symbols, the respective field in the LIBSSH2_SFTP_ATTRIBUTES structure is meaningful.
The filesize parameter is valid.
The uid and gid (numeric user ID and group ID) parameters are valid.
The permissions parameter is valid. This contains one or more of the following flags:
Mask for file owner permissions
Owner has read permission
Owner has write permission
Owner has execute permission
Mask for group permissions
Group has read permission
Group has write permission
Group has execute permission
Mask for permissions for others (not in group)
Others have read permission
Others have write permisson
Others have execute permission
The atime and mtime parameters are valid. These represent the last access and modification time respectively, and are expressed as elapsed seconds since Jan 1, 1970 (UTC)
Constants.
select channel's standard error output
use an MD5 hash
use an SHA1 hash
open a regular file via SFTP
open a directory via SFTP
the stat operation is a set
the stat operation is a set
the stat operation is a set
resolve any given filename into the real path
create a symbolic link
read the target of a symbolic link
SSH protocol disconnect codes.
Function prototypes.
void *allocfunc(size_t count, void **data)
void freefunc(void *ptr, void **data)
void *reallocfunc(void *ptr, size_t count, void **data)
void passwdchangefunc(LIBSSH2_SESSION *session, char **newpw, int *newpw_len, void **abstract)
void ignorefunc(LIBSSH2_SESSION *session, const char *message, int message_len, void **abstract)
void debugfunc(LIBSSH2_SESSION *session, int always_display, const char *message, int message_len, const char *language, int language_len,void **abstract)
void disconnectfunc(LIBSSH2_SESSION *session, int reason, const char *message, int message_len, const char *language, int language_len, void **abstract)
int macerrorfunc(LIBSSH2_SESSION *session, const char *packet, int packet_len, void **abstract)
Error codes.
The socket is invalid.
No banner was received from the remote host.
Unable to send banner to remote host.
Encryption key exchange with the remote host failed.
An internal memory allocation call failed.
Unable to send data on socket.
The socket was disconnected.
An invalid SSH protocol response was received on the socket.
The username/public key combination was invalid.
The username/public key combination was invalid, or the signature for the supplied public key was invalid.
An invalid SFTP protocol response was received on the socket, or an SFTP operation caused an errorcode to be returned by the server.
In the last case, libssh2_sftp_last_error() will return one of the following error codes:
The file already exists.
The remote server refused the request.
The requested method is not supported.
The requested method type was invalid.
This reference manual is copyright (c) 2005 by Bert Vermeulen. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/). Any comments and questions regarding this document should be sent to docs@libssh2.org.