shinys000114/libssh
1
0
Fork 0
mirror of https://git.libssh.org/projects/libssh.git synced 2026-03-24 20:40:09 +09:00
Code Issues Packages Projects Releases Wiki Activity

doc: add missing Doxygen comments and fix documentation style

Browse Source 
- Add missing @brief, @param, and @return docs across src/ and include/
- Fix blank lines between doc comments and function definitions
- Move function docs from headers to corresponding .c files
- Use named constants (SSH_OK, SSH_ERROR, SSH_TIMEOUT_INFINITE) in docs
- Fix parameter ordering in error.c, buffer.c, log.c docs
- Place #ifdef-guarded docs inside their respective #ifdef blocks

Signed-off-by: Sudharshan Hegde <sudharshanhegde68@gmail.com>
Reviewed-by: Jakub Jelen <jjelen@redhat.com>
This commit is contained in:
Sudharshan Hegde
2026-03-10 18:16:42 +05:30
committed by Jakub Jelen
parent e927820082
commit 9478de8082
19 changed files with 484 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/doc_coverage.sh
View File

@@ -49,4 +49,4 @@ ALL_FUNC=$(echo "$FUNC_LINES" | sed -e "s/$F_CUT_BEFORE//g" -e "s/$F_CUT_AFTER//
ALL_FUNC=$(echo "$ALL_FUNC" | sort - | uniq | wc -l)
# percentage of the documented functions
awk "BEGIN {printf \"Documentation coverage is %.2f%\n\", 100 - (${UNDOC_FUNC}/${ALL_FUNC}*100)}"
awk "BEGIN {printf \"Documentation coverage is %.2f%%\n\", 100 - (${UNDOC_FUNC}/${ALL_FUNC}*100)}"

7
include/libssh/bind_config.h
View File

@@ -57,10 +57,11 @@ enum ssh_bind_config_opcode_e {
BIND_CFG_MAX /* Keep this one last in the list */
};
/* @brief Parse configuration file and set the options to the given ssh_bind
/**
* @brief Parse configuration file and set the options to the given ssh_bind
*
* @params[in] sshbind The ssh_bind context to be configured
* @params[in] filename The path to the configuration file
* @param[in] sshbind The ssh_bind context to be configured
* @param[in] filename The path to the configuration file
*
* @returns 0 on successful parsing the configuration file, -1 on error
*/

34
include/libssh/callbacks.h
View File

@@ -538,12 +538,9 @@ typedef struct ssh_socket_callbacks_struct *ssh_socket_callbacks;
* automatically passed through.
*
* @param list list of callbacks
*
* @param cbtype type of the callback
*
* @param c callback name
*
* @param va_args parameters to be passed
* @param ... Parameters to be passed to the callback.
*/
#define ssh_callbacks_execute_list(list, cbtype, c, ...) \
do { \
@@ -585,9 +582,18 @@ typedef struct ssh_socket_callbacks_struct *ssh_socket_callbacks;
_cb = ssh_iterator_value(_cb_type, _cb_i); \
if (ssh_callbacks_exists(_cb, _cb_name))
/** @internal
* @brief Execute the current callback in an ssh_callbacks_iterate() loop.
*
* @param _cb_name The name of the callback field to invoke.
* @param ... Parameters to be passed to the callback.
*/
#define ssh_callbacks_iterate_exec(_cb_name, ...) \
_cb->_cb_name(__VA_ARGS__, _cb->userdata)
/** @internal
* @brief End an ssh_callbacks_iterate() loop.
*/
#define ssh_callbacks_iterate_end() \
} \
} while(0)
@@ -1060,8 +1066,18 @@ LIBSSH_API int ssh_remove_channel_callbacks(ssh_channel channel,
* @{
*/
/** @brief Callback for thread mutex operations (init, destroy, lock, unlock).
*
* @param lock Pointer to the mutex lock.
*
* @return 0 on success, non-zero on error.
*/
typedef int (*ssh_thread_callback) (void **lock);
/** @brief Callback to retrieve the current thread identifier.
*
* @return The unique identifier of the calling thread.
*/
typedef unsigned long (*ssh_thread_id_callback) (void);
struct ssh_threads_callbacks_struct {
const char *type;
@@ -1172,10 +1188,20 @@ typedef int (*ssh_jump_verify_knownhost_callback)(ssh_session session,
typedef int (*ssh_jump_authenticate_callback)(ssh_session session,
void *userdata);
/**
* @brief Callback collection for managing an SSH proxyjump connection.
*
* Set these callbacks to control knownhost verification and authentication
* on the jump host before the final destination is reached.
*/
struct ssh_jump_callbacks_struct {
/** Userdata passed to each callback. */
void *userdata;
/** Called before connecting to the jump host. */
ssh_jump_before_connection_callback before_connection;
/** Called to verify the jump host's identity. */
ssh_jump_verify_knownhost_callback verify_knownhost;
/** Called to authenticate on the jump host. */
ssh_jump_authenticate_callback authenticate;
};

6
include/libssh/misc.h
View File

@@ -70,9 +70,15 @@ struct ssh_iterator {
const void *data;
};
/**
* @brief Holds connection details for an SSH proxyjump host.
*/
struct ssh_jump_info_struct {
/** Hostname or IP address of the jump host. */
char *hostname;
/** Username to authenticate with on the jump host. */
char *username;
/** Port number of the jump host. */
int port;
};

5
include/libssh/server.h
View File

@@ -35,6 +35,11 @@
extern "C" {
#endif
/**
* @brief Options for configuring an SSH server bind session.
*
* Used with ssh_bind_options_set() to configure server-side options.
*/
enum ssh_bind_options_e {
SSH_BIND_OPTIONS_BINDADDR,
SSH_BIND_OPTIONS_BINDPORT,

70
include/libssh/sftp.h
View File

@@ -64,6 +64,7 @@ extern "C" {
#endif /* _MSC_VER */
#endif /* _WIN32 */
/** @brief The SFTP protocol version implemented by this library. */
#define LIBSFTP_VERSION 3
typedef struct sftp_attributes_struct* sftp_attributes;
@@ -90,10 +91,76 @@ typedef struct sftp_request_queue_struct* sftp_request_queue;
* @see sftp_free
*/
typedef struct sftp_session_struct* sftp_session;
/**
* @brief Handle for an SFTP status message received from the server.
*
* This type represents a status response returned by the SFTP server in
* reply to a client request. It carries a numeric status code and an optional
* human-readable error message. This type is used internally by libssh and
* is not part of the public API.
*
* @see sftp_status_message_struct
*/
typedef struct sftp_status_message_struct* sftp_status_message;
/**
* @brief Handle for SFTP file system statistics.
*
* This type represents file system statistics as reported by the SFTP server,
* analogous to the POSIX @c statvfs structure. It is obtained via
* sftp_statvfs() or sftp_fstatvfs() and must be freed with
* sftp_statvfs_free().
*
* @see sftp_statvfs_struct
* @see sftp_statvfs
* @see sftp_fstatvfs
* @see sftp_statvfs_free
*/
typedef struct sftp_statvfs_struct* sftp_statvfs_t;
/**
* @brief Handle for SFTP server limits information.
*
* This type represents the server-reported SFTP limits such as the maximum
* packet, read, and write lengths and the maximum number of open handles.
* It is obtained via sftp_limits() and must be freed with sftp_limits_free().
*
* @see sftp_limits_struct
* @see sftp_limits
* @see sftp_limits_free
*/
typedef struct sftp_limits_struct* sftp_limits_t;
/**
* @brief Handle for an asynchronous SFTP I/O operation.
*
* This type represents an in-flight asynchronous SFTP read or write request.
* It is allocated by sftp_aio_begin_read() or sftp_aio_begin_write() and
* consumed by the corresponding sftp_aio_wait_read() or sftp_aio_wait_write()
* call. If the wait call is not reached, the handle must be freed explicitly
* with sftp_aio_free() to avoid memory leaks.
*
* @see sftp_aio_begin_read
* @see sftp_aio_wait_read
* @see sftp_aio_begin_write
* @see sftp_aio_wait_write
* @see sftp_aio_free
*/
typedef struct sftp_aio_struct* sftp_aio;
/**
* @brief Handle for an SFTP name-to-id mapping.
*
* This type stores a mapping between numeric user or group IDs and their
* corresponding names. It is allocated via sftp_name_id_map_new(), populated
* by sftp_get_users_groups_by_id(), and freed with sftp_name_id_map_free().
*
* @see sftp_name_id_map_struct
* @see sftp_name_id_map_new
* @see sftp_get_users_groups_by_id
* @see sftp_name_id_map_free
*/
typedef struct sftp_name_id_map_struct *sftp_name_id_map;
struct sftp_session_struct {
@@ -392,7 +459,6 @@ LIBSSH_API sftp_session sftp_new(ssh_session session);
*/
LIBSSH_API sftp_session sftp_new_channel(ssh_session session, ssh_channel channel);
/**
* @brief Close and deallocate a sftp session.
*
@@ -1582,7 +1648,9 @@ LIBSSH_API void sftp_handle_remove(sftp_session sftp, void *handle);
#define SFTP_EXTENDED SSH_FXP_EXTENDED
/* openssh flags */
/** @brief statvfs flag: file system is mounted read-only. */
#define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
/** @brief statvfs flag: file system does not support setuid/setgid. */
#define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
#ifdef __cplusplus

21
include/libssh/sftpserver.h
View File

@@ -43,17 +43,35 @@ extern "C" {
* @{
*/
/**
* @brief Macro to declare an SFTP message callback function.
*
* @param name The name of the callback function to declare.
*/
#define SSH_SFTP_CALLBACK(name) \
static int name(sftp_client_message message)
/**
* @brief Callback for handling SFTP client messages.
*
* @param message The SFTP client message to handle.
*
* @return 0 on success, -1 on error.
*/
typedef int (*sftp_server_message_callback)(sftp_client_message message);
/**
* @brief Maps an SFTP message type to its handler callback.
*/
struct sftp_message_handler
{
/** The name of the SFTP operation (e.g. "read", "write"). */
const char *name;
/** The extended operation name for SSH_FXP_EXTENDED requests, or NULL. */
const char *extended_name;
/** The SFTP message type code (e.g. SSH_FXP_READ). */
uint8_t type;
/** The callback function to invoke for this message type. */
sftp_server_message_callback cb;
};
@@ -61,6 +79,7 @@ LIBSSH_API int sftp_channel_default_subsystem_request(ssh_session session,
ssh_channel channel,
const char *subsystem,
void *userdata);
LIBSSH_API int sftp_channel_default_data_callback(ssh_session session,
ssh_channel channel,
void *data,

16
src/buffer.c
View File

@@ -109,6 +109,11 @@ static void buffer_verify(ssh_buffer buf)
}
#else
/** @internal
* @brief No-op stub for buffer_verify when debug checks are disabled.
*
* @param x The buffer to verify (ignored).
*/
#define buffer_verify(x)
#endif
@@ -964,9 +969,12 @@ static int ssh_buffer_pack_allocate_va(struct ssh_buffer_struct *buffer,
/** @internal
* @brief Add multiple values in a buffer on a single function call
*
* @param[in] buffer The buffer to add to
* @param[in] format A format string of arguments.
* @param[in] argc Number of arguments passed after format.
* @param[in] ap A va_list of arguments.
*
* @returns SSH_OK on success
* SSH_ERROR on error
* @see ssh_buffer_add_format() for format list values.
@@ -1112,6 +1120,9 @@ ssh_buffer_pack_va(struct ssh_buffer_struct *buffer,
* 'P': size_t, void * (len of data, pointer to data)
* only pushes data.
* 'B': bignum (pushed as SSH string)
* @param[in] argc Number of arguments passed after format.
* @param[in] ... Arguments as described by the format string.
*
* @returns SSH_OK on success
* SSH_ERROR on error
* @warning when using 'P' with a constant size (e.g. 8), do not
@@ -1148,7 +1159,9 @@ int _ssh_buffer_pack(struct ssh_buffer_struct *buffer,
* @brief Get multiple values from a buffer on a single function call
* @param[in] buffer The buffer to get from
* @param[in] format A format string of arguments.
* @param[in] argc Number of arguments passed in the va_list.
* @param[in] ap A va_list of arguments.
*
* @returns SSH_OK on success
* SSH_ERROR on error
* @see ssh_buffer_get_format() for format list values.
@@ -1411,6 +1424,9 @@ cleanup:
* 'P': size_t, void ** (len of data, pointer to data)
* only pulls data.
* 'B': bignum * (pulled as SSH string)
* @param[in] argc Number of arguments passed after format.
* @param[in] ... Arguments as described by the format string.
*
* @returns SSH_OK on success
* SSH_ERROR on error
* @warning when using 'P' with a constant size (e.g. 8), do not

23
src/config.c
View File

@@ -1684,11 +1684,12 @@ int ssh_config_parse_line_cli(ssh_session session, const char *line)
true);
}
/* @brief Parse configuration from a file pointer
/**
* @brief Parse configuration from a file pointer
*
* @params[in] session The ssh session
* @params[in] fp A valid file pointer
* @params[in] global Whether the config is global or not
* @param[in] session The ssh session
* @param[in] fp A valid file pointer
* @param[in] global Whether the config is global or not
*
* @returns 0 on successful parsing the configuration file, -1 on error
*/
@@ -1710,10 +1711,11 @@ int ssh_config_parse(ssh_session session, FILE *fp, bool global)
return 0;
}
/* @brief Parse configuration file and set the options to the given session
/**
* @brief Parse configuration file and set the options to the given session
*
* @params[in] session The ssh session
* @params[in] filename The path to the ssh configuration file
* @param[in] session The ssh session
* @param[in] filename The path to the ssh configuration file
*
* @returns 0 on successful parsing the configuration file, -1 on error
*/
@@ -1748,10 +1750,11 @@ int ssh_config_parse_file(ssh_session session, const char *filename)
return rv;
}
/* @brief Parse configuration string and set the options to the given session
/**
* @brief Parse configuration string and set the options to the given session
*
* @params[in] session The ssh session
* @params[in] input Null terminated string containing the configuration
* @param[in] session The ssh session
* @param[in] input Null terminated string containing the configuration
*
* @returns SSH_OK on successful parsing the configuration string,
* SSH_ERROR on error

5
src/error.c
View File

@@ -43,11 +43,9 @@
* @brief Registers an error with a description.
*
* @param error The place to store the error.
*
* @param code The class of error.
*
* @param function The name of the calling function.
* @param descr The description, which can be a format string.
*
* @param ... The arguments for the format string.
*/
void _ssh_set_error(void *error,
@@ -76,6 +74,7 @@ void _ssh_set_error(void *error,
* @brief Registers an out of memory error
*
* @param error The place to store the error.
* @param function The name of the calling function.
*
*/
void _ssh_set_error_oom(void *error, const char *function)

10
src/legacy.c
View File

@@ -770,6 +770,16 @@ ssh_string ssh_get_pubkey(ssh_session session)
****************************************************************************/
#ifdef WITH_SERVER
/**
* @brief Accept an incoming SSH connection on a bind socket.
*
* @deprecated Use ssh_bind_accept() instead.
*
* @param session The SSH session to accept the connection on.
*
* @return SSH_OK on success, SSH_ERROR on error.
*/
int ssh_accept(ssh_session session) {
return ssh_handle_key_exchange(session);
}

45
src/log.c
View File

@@ -109,6 +109,16 @@ static void ssh_log_custom(ssh_logging_callback log_fn,
log_fn(verbosity, function, buf, ssh_get_log_userdata());
}
/** @internal
* @brief Dispatch a pre-formatted log message to the active logging backend.
*
* If a custom logging callback is registered, the message is passed to it.
* Otherwise, the message is written to stderr.
*
* @param verbosity The verbosity level of the message.
* @param function The name of the calling function.
* @param buffer The already-formatted log message string.
*/
void ssh_log_function(int verbosity,
const char *function,
const char *buffer)
@@ -123,6 +133,15 @@ void ssh_log_function(int verbosity,
ssh_log_stderr(verbosity, function, buffer);
}
/** @internal
* @brief Format a log message from a va_list and dispatch it for logging.
*
* @param verbosity The verbosity level of the message.
* @param function The name of the calling function.
* @param format A printf-style format string.
* @param va Pointer to the variable argument list
* for the format string.
*/
void ssh_vlog(int verbosity,
const char *function,
const char *format,
@@ -134,6 +153,15 @@ void ssh_vlog(int verbosity,
ssh_log_function(verbosity, function, buffer);
}
/** @internal
* @brief Log a message if the given verbosity does not
* exceed the global log level.
*
* @param verbosity The verbosity level of the message.
* @param function The name of the calling function.
* @param format A printf-style format string.
* @param ... Additional arguments corresponding to the format string.
*/
void _ssh_log(int verbosity,
const char *function,
const char *format, ...)
@@ -149,6 +177,15 @@ void _ssh_log(int verbosity,
/* LEGACY */
/** @brief Log a message using the verbosity level of the given session.
*
* @deprecated Use the SSH_LOG() macro instead.
*
* @param session The SSH session whose verbosity level is checked.
* @param verbosity The verbosity level of the message.
* @param format A printf-style format string.
* @param ... Arguments as described by the format string.
*/
void ssh_log(ssh_session session,
int verbosity,
const char *format, ...)
@@ -164,9 +201,14 @@ void ssh_log(ssh_session session,
/** @internal
* @brief log a SSH event with a common pointer
*
* Works for both ssh_session and ssh_bind as both embed ssh_common_struct.
*
* @param common The SSH/bind session.
* @param verbosity The verbosity of the event.
* @param function The name of the calling function.
* @param format The format string of the log entry.
* @param ... Additional arguments corresponding to the format string.
*/
void ssh_log_common(struct ssh_common_struct *common,
int verbosity,
@@ -221,6 +263,9 @@ int ssh_set_log_callback(ssh_logging_callback cb) {
return SSH_OK;
}
/** @internal
* @brief Clear the thread-local logging callback, reverting to stderr logging.
*/
void
_ssh_reset_log_cb(void)
{

151
src/misc.c
View File

@@ -127,7 +127,13 @@ static char *ssh_get_user_home_dir_internal(void)
return NULL;
}
/* we have read access on file */
/** @internal
* @brief Check whether the current process has read access to a file.
*
* @param[in] file Path to the file to check.
*
* @return 1 if the file is readable, 0 otherwise.
*/
int ssh_file_readaccess_ok(const char *file)
{
if (_access(file, 4) < 0) {
@@ -208,11 +214,11 @@ struct tm *ssh_localtime(const time_t *timer, struct tm *result)
return result;
}
/**
* @brief Get username from the calling process.
/** @internal
* @brief Get the username of the currently running process.
*
* @return An allocated string with the user on success, NULL on failure. The
* caller is responsible for freeing returned string.
* @return A newly allocated string with the username, or NULL on error.
* The caller is responsible for freeing it.
*/
char *ssh_get_local_username(void)
{
@@ -240,6 +246,13 @@ char *ssh_get_local_username(void)
return NULL;
}
/** @internal
* @brief Check whether a string is a valid IPv4 address.
*
* @param[in] str The string to check.
*
* @return 1 if the string is a valid IPv4 address, 0 otherwise.
*/
int ssh_is_ipaddr_v4(const char *str)
{
struct sockaddr_storage ss;
@@ -263,6 +276,13 @@ int ssh_is_ipaddr_v4(const char *str)
return 0;
}
/** @internal
* @brief Check whether a string is a valid IPv4 or IPv6 address.
*
* @param[in] str The string to check.
*
* @return 1 if valid IP address, 0 if not, -1 on memory error.
*/
int ssh_is_ipaddr(const char *str)
{
int rc = SOCKET_ERROR;
@@ -328,7 +348,13 @@ static char *ssh_get_user_home_dir_internal(void)
return szPath;
}
/* we have read access on file */
/** @internal
* @brief Check whether the current process has read access to a file.
*
* @param[in] file Path to the file to check.
*
* @return 1 if the file is readable, 0 otherwise.
*/
int ssh_file_readaccess_ok(const char *file)
{
if (access(file, R_OK) < 0) {
@@ -363,11 +389,11 @@ int ssh_dir_writeable(const char *path)
return 0;
}
/**
* @brief Get username from the calling process.
/** @internal
* @brief Get the username of the currently running process.
*
* @return An allocated string with the name on success, NULL on failure. The
* caller is responsible for freeing returned string.
* @return A newly allocated string with the username, or NULL on error.
* The caller is responsible for freeing it.
*/
char *ssh_get_local_username(void)
{
@@ -393,6 +419,13 @@ char *ssh_get_local_username(void)
return name;
}
/** @internal
* @brief Check whether a string is a valid IPv4 address.
*
* @param[in] str The string to check.
*
* @return 1 if the string is a valid IPv4 address, 0 otherwise.
*/
int ssh_is_ipaddr_v4(const char *str)
{
int rc = -1;
@@ -406,6 +439,13 @@ int ssh_is_ipaddr_v4(const char *str)
return 0;
}
/** @internal
* @brief Check whether a string is a valid IPv4 or IPv6 address.
*
* @param[in] str The string to check.
*
* @return 1 if valid IP address, 0 if not, -1 on memory error.
*/
int ssh_is_ipaddr(const char *str)
{
int rc = -1;
@@ -440,6 +480,17 @@ int ssh_is_ipaddr(const char *str)
#endif /* _WIN32 */
/** @internal
* @brief Get the home directory of the current user.
*
* If a session is provided and a cached value exists, it is returned directly.
* Otherwise the home directory is looked up and cached in the session.
*
* @param[in] session The SSH session to cache the result in, or NULL.
*
* @return A newly allocated string with the home directory path, or NULL
* on error. The caller is responsible for freeing it.
*/
char *ssh_get_user_home_dir(ssh_session session)
{
char *szPath = NULL;
@@ -463,6 +514,14 @@ char *ssh_get_user_home_dir(ssh_session session)
return szPath;
}
/** @internal
* @brief Convert a string to lowercase.
*
* @param[in] str The string to convert.
*
* @return A newly allocated lowercase copy of the string, or NULL on error.
* The caller is responsible for freeing it.
*/
char *ssh_lowercase(const char* str)
{
char *new = NULL, *p = NULL;
@@ -483,6 +542,15 @@ char *ssh_lowercase(const char* str)
return new;
}
/** @internal
* @brief Format a host and port into a "[host]:port" string.
*
* @param[in] host The hostname or IP address.
* @param[in] port The port number.
*
* @return A newly allocated string of the form "[host]:port", or NULL
* on error. The caller is responsible for freeing it.
*/
char *ssh_hostport(const char *host, int port)
{
char *dest = NULL;
@@ -788,6 +856,11 @@ const char *ssh_version(int req_version)
return NULL;
}
/** @internal
* @brief Create a new empty linked list.
*
* @return A newly allocated ssh_list, or NULL on memory error.
*/
struct ssh_list *ssh_list_new(void)
{
struct ssh_list *ret = malloc(sizeof(struct ssh_list));
@@ -798,6 +871,13 @@ struct ssh_list *ssh_list_new(void)
return ret;
}
/** @internal
* @brief Free a linked list and all its iterator nodes.
*
* The data pointed to by each node is not freed.
*
* @param[in] list The list to free.
*/
void ssh_list_free(struct ssh_list *list)
{
struct ssh_iterator *ptr = NULL, *next = NULL;
@@ -812,6 +892,13 @@ void ssh_list_free(struct ssh_list *list)
SAFE_FREE(list);
}
/** @internal
* @brief Get the first iterator of a linked list.
*
* @param[in] list The list to iterate.
*
* @return Pointer to the first iterator, or NULL if the list is empty.
*/
struct ssh_iterator *ssh_list_get_iterator(const struct ssh_list *list)
{
if (!list)
@@ -819,6 +906,14 @@ struct ssh_iterator *ssh_list_get_iterator(const struct ssh_list *list)
return list->root;
}
/** @internal
* @brief Find the iterator pointing to a specific value in the list.
*
* @param[in] list The list to search.
* @param[in] value The data pointer to find.
*
* @return The iterator pointing to the value, or NULL if not found.
*/
struct ssh_iterator *ssh_list_find(const struct ssh_list *list, void *value)
{
struct ssh_iterator *it = NULL;
@@ -894,6 +989,14 @@ int ssh_list_append(struct ssh_list *list, const void *data)
return SSH_OK;
}
/** @internal
* @brief Prepend an element at the beginning of the list.
*
* @param[in] list The list to prepend to.
* @param[in] data The element to prepend.
*
* @return `SSH_OK` on success, `SSH_ERROR` on error.
*/
int ssh_list_prepend(struct ssh_list *list, const void *data)
{
struct ssh_iterator *it = NULL;
@@ -919,6 +1022,12 @@ int ssh_list_prepend(struct ssh_list *list, const void *data)
return SSH_OK;
}
/** @internal
* @brief Remove an element from the list by its iterator.
*
* @param[in] list The list to remove from.
* @param[in] iterator The iterator pointing to the element to remove.
*/
void ssh_list_remove(struct ssh_list *list, struct ssh_iterator *iterator)
{
struct ssh_iterator *ptr = NULL, *prev = NULL;
@@ -1257,6 +1366,12 @@ char *ssh_path_expand_tilde(const char *d)
return r;
}
/** @internal
* @brief Get the hostname of the local machine.
*
* @return A newly allocated string with the hostname, or NULL on error.
* The caller is responsible for freeing it.
*/
char *ssh_get_local_hostname(void)
{
char host[NI_MAXHOST] = {0};
@@ -1359,6 +1474,7 @@ err:
/** @internal
* @brief expands a string in function of session options
*
* @param[in] session The SSH session providing option values for expansion.
* @param[in] s Format string to expand. Known parameters:
* - %d user home directory (~)
* - %h target host name
@@ -1791,6 +1907,15 @@ void burn_free(void *ptr, size_t len)
}
#if !defined(HAVE_STRNDUP)
/** @internal
* @brief Compatibility implementation of strndup for systems that lack it.
*
* @param[in] s The string to duplicate.
* @param[in] n Maximum number of characters to copy.
*
* @return A newly allocated null-terminated string, or NULL on error.
*/
char *strndup(const char *s, size_t n)
{
char *x = NULL;
@@ -1811,7 +1936,11 @@ char *strndup(const char *s, size_t n)
}
#endif /* ! HAVE_STRNDUP */
/* Increment 64b integer in network byte order */
/** @internal
* @brief Increment a 64-bit counter stored in network byte order.
*
* @param[in,out] counter Pointer to an 8-byte buffer holding the counter.
*/
void
uint64_inc(unsigned char *counter)
{

24
src/options.c
View File

@@ -288,6 +288,20 @@ int ssh_options_copy(ssh_session src, ssh_session *dest)
return 0;
}
/** @internal
* @brief Set a key exchange algorithm list option on the session.
*
* Supports prefix modifiers: '+' to append, '-' to remove, '^' to prepend
* to the default algorithm list.
*
* @param[in] session The SSH session.
* @param[in] algo The algorithm type to configure.
* @param[in] list The algorithm list string.
* @param[out] place Pointer to the string to store
* the resulting algorithm list.
*
* @return `SSH_OK` on success, `SSH_ERROR` on error.
*/
int ssh_options_set_algo(ssh_session session,
enum ssh_kex_types_e algo,
const char *list,
@@ -2081,6 +2095,16 @@ out:
return r;
}
/** @internal
* @brief Apply default values for unset session options.
*
* Sets default SSH directory and username if not already configured,
* and resolves any remaining option expansions.
*
* @param[in] session The SSH session to apply defaults to.
*
* @return `SSH_OK` on success, `SSH_ERROR` on error.
*/
int ssh_options_apply(ssh_session session)
{
char *tmp = NULL;

34
src/poll.c
View File

@@ -84,16 +84,33 @@ struct ssh_poll_ctx_struct {
#ifdef HAVE_POLL
#include <poll.h>
/** @internal
* @brief Initialize the poll subsystem. No-op when native poll is available.
*/
void ssh_poll_init(void)
{
return;
}
/** @internal
* @brief Clean up the poll subsystem. No-op when native poll is available.
*/
void ssh_poll_cleanup(void)
{
return;
}
/** @internal
* @brief Wait for events on a set of file descriptors.
*
* @param fds Array of pollfd structures specifying the file descriptors.
* @param nfds Number of file descriptors in the array.
* @param timeout Timeout in milliseconds, `SSH_TIMEOUT_INFINITE`
* to block indefinitely.
*
* @return Number of file descriptors with events, 0 on timeout,
* -1 on error.
*/
int ssh_poll(ssh_pollfd_t *fds, nfds_t nfds, int timeout)
{
return poll((struct pollfd *)fds, nfds, timeout);
@@ -321,16 +338,33 @@ static int bsd_poll(ssh_pollfd_t *fds, nfds_t nfds, int timeout)
return rc;
}
/** @internal
* @brief Initialize the poll subsystem using the BSD poll emulation.
*/
void ssh_poll_init(void)
{
ssh_poll_emu = bsd_poll;
}
/** @internal
* @brief Clean up the poll subsystem, resetting to the BSD poll emulation.
*/
void ssh_poll_cleanup(void)
{
ssh_poll_emu = bsd_poll;
}
/** @internal
* @brief Wait for events on a set of file descriptors.
*
* @param fds Array of pollfd structures specifying the file descriptors.
* @param nfds Number of file descriptors in the array.
* @param timeout Timeout in milliseconds, `SSH_TIMEOUT_INFINITE`
* to block indefinitely.
*
* @return Number of file descriptors with events, 0 on timeout,
* -1 on error.
*/
int ssh_poll(ssh_pollfd_t *fds, nfds_t nfds, int timeout)
{
return (ssh_poll_emu)(fds, nfds, timeout);

4
src/session.c
View File

@@ -1010,7 +1010,9 @@ int ssh_get_version(ssh_session session) {
/**
* @internal
* @brief Callback to be called when the socket received an exception code.
* @param user is a pointer to session
* @param code The exception code from the socket layer.
* @param errno_code The errno value associated with the exception.
* @param user Pointer to the SSH session.
*/
void ssh_socket_exception_callback(int code, int errno_code, void *user){
ssh_session session = (ssh_session)user;

27
src/sftpserver.c
View File

@@ -948,6 +948,14 @@ void *sftp_handle(sftp_session sftp, ssh_string handle)
return sftp->handles[val];
}
/**
* @brief Remove an SFTP file or directory handle from the session.
*
* @param sftp The SFTP session.
* @param handle The handle to remove.
*
* @see sftp_handle_alloc()
*/
void sftp_handle_remove(sftp_session sftp, void *handle)
{
int i;
@@ -2071,16 +2079,19 @@ sftp_channel_default_subsystem_request(ssh_session session,
}
/**
* @brief Default data callback for sftp server
* @brief Default channel data callback for an SFTP server subsystem.
*
* @param[in] session The ssh session
* @param[in] channel The ssh channel with SFTP session opened
* @param[in] data The data to be processed.
* @param[in] len The length of input data to be processed
* @param[in] is_stderr Unused channel flag for stderr flagging
* @param[in] userdata The pointer to sftp_session
* Processes incoming data on the channel and dispatches it to the SFTP
* server message handler.
*
* @return number of bytes processed, -1 when error occurs.
* @param[in] session The SSH session.
* @param[in] channel The SSH channel carrying the SFTP data.
* @param[in] data The received data buffer.
* @param[in] len The length of the data buffer.
* @param[in] is_stderr Unused; SFTP does not use the stderr stream.
* @param[in] userdata Pointer to the sftp_session handle.
*
* @return Number of bytes processed on success, `SSH_ERROR` on error.
*/
int
sftp_channel_default_data_callback(UNUSED_PARAM(ssh_session session),

31
src/socket.c
View File

@@ -65,6 +65,9 @@ struct sockaddr_un {
* @{
*/
/** @internal
* @brief Represents the possible states of an SSH socket connection.
*/
enum ssh_socket_states_e {
SSH_SOCKET_NONE,
SSH_SOCKET_CONNECTING,
@@ -1063,12 +1066,26 @@ int ssh_socket_get_poll_flags(ssh_socket s)
}
#ifdef _WIN32
/** @internal
* @brief Set a socket file descriptor to non-blocking mode.
*
* @param fd The socket file descriptor to configure.
*
* @return `SSH_OK` on success, `SSH_ERROR` on error.
*/
int ssh_socket_set_nonblocking(socket_t fd)
{
u_long nonblocking = 1;
return ioctlsocket(fd, FIONBIO, &nonblocking);
}
/** @internal
* @brief Set a socket file descriptor to blocking mode.
*
* @param fd The socket file descriptor to configure.
*
* @return `SSH_OK` on success, `SSH_ERROR` on error.
*/
int ssh_socket_set_blocking(socket_t fd)
{
u_long nonblocking = 0;
@@ -1076,11 +1093,25 @@ int ssh_socket_set_blocking(socket_t fd)
}
#else /* _WIN32 */
/** @internal
* @brief Set a socket file descriptor to non-blocking mode.
*
* @param fd The socket file descriptor to configure.
*
* @return `SSH_OK` on success, `SSH_ERROR` on error.
*/
int ssh_socket_set_nonblocking(socket_t fd)
{
return fcntl(fd, F_SETFL, O_NONBLOCK);
}
/** @internal
* @brief Set a socket file descriptor to blocking mode.
*
* @param fd The socket file descriptor to configure.
*
* @return 0 on success, -1 on error.
*/
int ssh_socket_set_blocking(socket_t fd)
{
return fcntl(fd, F_SETFL, 0);

9
src/threads.c
View File

@@ -62,6 +62,9 @@ int ssh_threads_init(void)
return rc;
}
/** @internal
* @brief Finalize and clean up the threading backend of the crypto libraries.
*/
void ssh_threads_finalize(void)
{
crypto_thread_finalize();
@@ -83,6 +86,12 @@ int ssh_threads_set_callbacks(struct ssh_threads_callbacks_struct *cb)
return rc;
}
/** @internal
* @brief Get the type identifier of the currently active threading callbacks.
*
* @return A string identifying the threading backend, or NULL if no
* callbacks are registered.
*/
const char *ssh_threads_get_type(void)
{
if (user_callbacks != NULL) {