shinys000114/libssh
1
0
Fork 0
mirror of https://git.libssh.org/projects/libssh.git synced 2026-02-06 18:29:50 +09:00
Code Issues Packages Projects Releases Wiki Activity

Improve doxygen documentation

Browse Source 
Signed-off-by: Nikhil V <nikhilgreyshines@gmail.com>
Reviewed-by: Jakub Jelen <jjelen@redhat.com>
This commit is contained in:
Nikhil V
2025-12-06 10:51:35 +05:30
committed by Jakub Jelen
parent f8d943afda
commit 4feb0dd79d
10 changed files with 1121 additions and 663 deletions
Download Patch File Download Diff File Expand all files Collapse all files

301
src/socket.c
View File

@@ -112,8 +112,14 @@ static ssize_t ssh_socket_unbuffered_write(ssh_socket s,
uint32_t len);
/**
* \internal
* \brief inits the socket system (windows specific)
* @internal
*
* @brief Initialize socket support for libssh.
*
* Initializes the socket subsystem, calling WSAStartup() on Windows and
* ssh_poll_init() on all platforms. Can be called multiple times.
*
* @return 0 on success; -1 on Windows socket initialization failure.
*/
int ssh_socket_init(void)
{
@@ -135,7 +141,12 @@ int ssh_socket_init(void)
}
/**
* @brief Cleanup the socket system.
* @internal
*
* @brief Cleanup socket support for libssh.
*
* Cleans up the socket subsystem, calling ssh_poll_cleanup() on all platforms
* and WSACleanup() on Windows. Can be called multiple times.
*/
void ssh_socket_cleanup(void)
{
@@ -148,10 +159,17 @@ void ssh_socket_cleanup(void)
}
}
/**
* \internal
* \brief creates a new Socket object
* @internal
*
* @brief Allocate and initialize a new SSH socket structure.
*
* Creates a new ssh_socket structure associated with the given session,
* initializes input/output buffers and sets default socket state.
*
* @param[in] session The SSH session to associate with the socket.
*
* @return A new ssh_socket on success; NULL on memory allocation failure.
*/
ssh_socket ssh_socket_new(ssh_session session)
{
@@ -189,8 +207,13 @@ ssh_socket ssh_socket_new(ssh_session session)
/**
* @internal
* @brief Reset the state of a socket so it looks brand-new
* @param[in] s socket to rest
*
* @brief Reset the state of a socket, so it looks brand new.
*
* Clears the file descriptor, reinitializes input/output buffers, frees
* the poll handle if present, and resets all socket state flags.
*
* @param[in] s The SSH socket to reset.
*/
void ssh_socket_reset(ssh_socket s)
{
@@ -219,24 +242,36 @@ void ssh_socket_reset(ssh_socket s)
* @param s socket to set callbacks on.
* @param callbacks a ssh_socket_callback object reference.
*/
void ssh_socket_set_callbacks(ssh_socket s, ssh_socket_callbacks callbacks)
{
s->callbacks = callbacks;
}
/**
* @internal
*
* @brief Mark an SSH socket as connected.
*
* Sets the socket state to connected and configures the poll handle
* to wait for `POLLIN` and `POLLOUT` events (needed for non-blocking connect).
*
* @param[in] s The SSH socket.
* @param[in] p The poll handle to configure, or NULL.
*/
void ssh_socket_set_connected(ssh_socket s, struct ssh_poll_handle_struct *p)
{
s->state = SSH_SOCKET_CONNECTED;
/* POLLOUT is the event to wait for in a nonblocking connect */
/* `POLLOUT` is the event to wait for in a non-blocking connect */
if (p != NULL) {
ssh_poll_set_events(p, POLLIN | POLLOUT);
}
}
/**
* @brief SSH poll callback. This callback will be used when an event
* caught on the socket.
* @internal
*
* @brief SSH poll callback. This callback will be used when an
* event caught on the socket.
*
* @param p Poll object this callback belongs to.
* @param fd The raw socket.
@@ -416,8 +451,15 @@ ssh_poll_handle ssh_socket_get_poll_handle(ssh_socket s)
return s->poll_handle;
}
/** \internal
* \brief Deletes a socket object
/**
* @internal
*
* @brief Deletes a socket object.
*
* Closes the socket connection, frees input/output buffers and
* releases the socket structure memory.
*
* @param[in] s The SSH socket to free, or NULL.
*/
void ssh_socket_free(ssh_socket s)
{
@@ -430,6 +472,20 @@ void ssh_socket_free(ssh_socket s)
SAFE_FREE(s);
}
/**
* @internal
*
* @brief Connect an SSH socket to a Unix domain socket.
*
* Creates a Unix domain socket connection to the given @p path and associates
* it with the SSH socket.
*
* @param[in] s The SSH socket to connect.
* @param[in] path Path to the Unix domain socket.
*
* @return `SSH_OK` on success; `SSH_ERROR` on socket creation, connect, or fd
* setup failure.
*/
int ssh_socket_unix(ssh_socket s, const char *path)
{
struct sockaddr_un sunaddr;
@@ -466,8 +522,17 @@ int ssh_socket_unix(ssh_socket s, const char *path)
return ssh_socket_set_fd(s, fd);
}
/** \internal
* \brief closes a socket
/**
* @internal
*
* @brief Close an SSH socket.
*
* Closes the socket file descriptor if open, saves the last error code,
* frees the poll handle if unlocked, and marks the socket state as closed.
* On Unix, attempts to terminate and wait for any running proxy command
* process.
*
* @param[in] s The SSH socket to close.
*/
void ssh_socket_close(ssh_socket s)
{
@@ -545,24 +610,48 @@ int ssh_socket_set_fd(ssh_socket s, socket_t fd)
return SSH_OK;
}
/** \internal
* \brief returns the input file descriptor of the socket
/**
* @internal
*
* @brief Returns the input file descriptor of a socket.
*
* @param[in] s The SSH socket.
*
* @return The socket file descriptor (socket_t).
*/
socket_t ssh_socket_get_fd(ssh_socket s)
{
return s->fd;
}
/** \internal
* \brief returns nonzero if the socket is open
/**
* @internal
*
* @brief Check if an SSH socket is open.
*
* @param[in] s The SSH socket.
*
* @return Non-zero if socket is open, 0 if closed or invalid.
*/
int ssh_socket_is_open(ssh_socket s)
{
return s->fd != SSH_INVALID_SOCKET;
}
/** \internal
* \brief read len bytes from socket into buffer
/**
* @internal
*
* @brief Perform an unbuffered read from an SSH socket.
*
* Reads @p len bytes from the socket file descriptor directly into @p buffer,
* using `recv()` if the descriptor is a socket, or `read()` otherwise.
* Updates internal error and state flags based on the result.
*
* @param[in] s The SSH socket.
* @param[out] buffer Buffer to read data into.
* @param[in] len Maximum number of bytes to read.
*
* @return Number of bytes read on success, or -1 on error.
*/
static ssize_t ssh_socket_unbuffered_read(ssh_socket s,
void *buffer,
@@ -594,8 +683,21 @@ static ssize_t ssh_socket_unbuffered_read(ssh_socket s,
return rc;
}
/** \internal
* \brief writes len bytes from buffer to socket
/**
* @internal
*
* @brief Perform an unbuffered write to an SSH socket.
*
* Writes @p len bytes from @p buffer to the socket file descriptor,
* using `send()` if the descriptor is a socket or `write()` otherwise.
* Updates internal error and state flags, and re-enables POLLOUT
* polling if a poll handle exists.
*
* @param[in] s The SSH socket.
* @param[in] buffer Buffer containing data to write.
* @param[in] len Number of bytes to write.
*
* @return Number of bytes written on success, or -1 on error.
*/
static ssize_t ssh_socket_unbuffered_write(ssh_socket s,
const void *buffer,
@@ -636,8 +738,18 @@ static ssize_t ssh_socket_unbuffered_write(ssh_socket s,
return w;
}
/** \internal
* \brief returns nonzero if the current socket is in the fd_set
/**
* @internal
*
* @brief Check if SSH socket file descriptor is set in an fd_set.
*
* Tests if the socket's file descriptor is present in the
* given @p set (fd_set) . Returns 0 if the socket has no valid file descriptor.
*
* @param[in] s The SSH socket.
* @param[in] set The fd_set to test against.
*
* @return Non-zero if the socket fd is set in the fd_set, 0 otherwise.
*/
int ssh_socket_fd_isset(ssh_socket s, fd_set *set)
{
@@ -647,10 +759,17 @@ int ssh_socket_fd_isset(ssh_socket s, fd_set *set)
return FD_ISSET(s->fd,set);
}
/** \internal
* \brief sets the current fd in a fd_set and updates the max_fd
/**
* @internal
*
* @brief Add SSH socket file descriptor to an fd_set.
*
* Adds the socket's file descriptor to the given @p set (fd_set)
* and updates @p max_fd if this socket has the highest file descriptor number.
* @param[in] s The SSH socket.
* @param[in,out] set The fd_set to add the socket to.
* @param[in,out] max_fd the maximum fd value.
*/
void ssh_socket_fd_set(ssh_socket s, fd_set *set, socket_t *max_fd)
{
if (s->fd == SSH_INVALID_SOCKET) {
@@ -666,10 +785,21 @@ void ssh_socket_fd_set(ssh_socket s, fd_set *set, socket_t *max_fd)
}
}
/** \internal
* \brief buffered write of data
* \returns SSH_OK, or SSH_ERROR
* \warning has no effect on socket before a flush
/**
* @internal
*
* @brief Write data to an SSH socket output buffer.
*
* Adds the data to the socket's output @p buffer and calls a nonblocking
* flush attempt to send buffered data.
*
* @param[in] s The SSH socket.
* @param[in] buffer Data to write.
* @param[in] len Number of bytes to write.
*
* @return `SSH_OK` on success; `SSH_ERROR` on buffer allocation failure.
*
* @warning It has no effect on socket before a flush.
*/
int ssh_socket_write(ssh_socket s, const void *buffer, uint32_t len)
{
@@ -684,10 +814,22 @@ int ssh_socket_write(ssh_socket s, const void *buffer, uint32_t len)
return SSH_OK;
}
/** \internal
* \brief starts a nonblocking flush of the output buffer
/**
* @internal
*
* @brief Starts a nonblocking flush of the output buffer.
*
* Sends all buffered data from the socket's output buffer.
* If the socket is not open, marks the session as dead and calls an
* exception callback or sets a fatal error. If the socket cannot currently
* accept data, polls for writable events and returns `SSH_AGAIN`.
* On write errors, closes the socket and signals the error. Updates
* byte counters on successful writes.
*
* @param[in] s The SSH socket.
*
* @return `SSH_OK` if all data was sent; `SSH_AGAIN` if the operation should
* be retried later; `SSH_ERROR` on fatal socket error.
*/
int ssh_socket_nonblocking_flush(ssh_socket s)
{
@@ -767,26 +909,79 @@ int ssh_socket_nonblocking_flush(ssh_socket s)
return SSH_OK;
}
/**
* @internal
*
* @brief Set the SSH socket write_wontblock flag.
*
* Marks the socket as ready for nonblocking writes (`write_wontblock = 1`).
* Used by the poll system when POLLOUT becomes available.
*
* @param[in] s The SSH socket.
*/
void ssh_socket_set_write_wontblock(ssh_socket s)
{
s->write_wontblock = 1;
}
/**
* @internal
*
* @brief Set the SSH socket read_wontblock flag.
*
* Marks the socket as ready for nonblocking reads (`read_wontblock = 1`).
* Used by the poll system when POLLIN becomes available.
*
* @param[in] s The SSH socket.
*/
void ssh_socket_set_read_wontblock(ssh_socket s)
{
s->read_wontblock = 1;
}
/**
* @internal
*
* @brief Set the SSH socket exception flag.
*
* Marks the socket as having an exception condition (`data_except = 1`).
*
* @param[in] s The SSH socket.
*/
void ssh_socket_set_except(ssh_socket s)
{
s->data_except = 1;
}
/**
* @internal
*
* @brief Check if SSH socket data is available for reading.
*
* Returns true if the socket is ready for nonblocking reads
* (`read_wontblock` flag is set).
*
* @param[in] s The SSH socket.
*
* @return 1 if data is available, 0 otherwise.
*/
int ssh_socket_data_available(ssh_socket s)
{
return s->read_wontblock;
}
/**
* @internal
*
* @brief Check if SSH socket is writable.
*
* Returns true if the socket is ready for nonblocking writes
* (`write_wontblock` flag is set).
*
* @param[in] s The SSH socket.
*
* @return 1 if socket is writable, 0 otherwise.
*/
int ssh_socket_data_writable(ssh_socket s)
{
return s->write_wontblock;
@@ -806,7 +1001,19 @@ int ssh_socket_buffered_write_bytes(ssh_socket s)
return ssh_buffer_get_len(s->out_buffer);
}
/**
* @internal
*
* @brief Get the current status of an SSH socket.
*
* Checks the input/output buffers and exception flag to determine socket
* status: `SSH_READ_PENDING` if input data available, `SSH_WRITE_PENDING`
* if output data pending, `SSH_CLOSED_ERROR` if exception occurred.
*
* @param[in] s The SSH socket.
*
* @return Socket status flags.
*/
int ssh_socket_get_status(ssh_socket s)
{
int r = 0;
@@ -826,6 +1033,18 @@ int ssh_socket_get_status(ssh_socket s)
return r;
}
/**
* @internal
*
* @brief Get SSH socket poll flags from the poll handle.
*
* Checks the poll handle events and returns `SSH_READ_PENDING` if POLLIN
* is set, `SSH_WRITE_PENDING` if POLLOUT is set.
*
* @param[in] s The SSH socket.
*
* @return Socket status flags based on poll events.
*/
int ssh_socket_get_poll_flags(ssh_socket s)
{
int r = 0;
@@ -872,8 +1091,8 @@ int ssh_socket_set_blocking(socket_t fd)
* @param host hostname or ip address to connect to.
* @param port port number to connect to.
* @param bind_addr address to bind to, or NULL for default.
* @returns SSH_OK socket is being connected.
* @returns SSH_ERROR error while connecting to remote host.
* @returns `SSH_OK` socket is being connected.
* @returns `SSH_ERROR` error while connecting to remote host.
*/
int ssh_socket_connect(ssh_socket s,
const char *host,
@@ -958,8 +1177,8 @@ ssh_execute_command(const char *command, socket_t in, socket_t out)
* This call will always be nonblocking.
* @param s socket to connect.
* @param command Command to execute.
* @returns SSH_OK socket is being connected.
* @returns SSH_ERROR error while executing the command.
* @returns `SSH_OK` socket is being connected.
* @returns `SSH_ERROR` error while executing the command.
*/
int
ssh_socket_connect_proxycommand(ssh_socket s, const char *command)