[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
PATCH: Improve and consolidate ssh_bind_options_set docs
[Thread Prev] | [Thread Next]
- Subject: PATCH: Improve and consolidate ssh_bind_options_set docs
- From: Alan Dunn <amdunn@xxxxxxxxx>
- Reply-to: libssh@xxxxxxxxxx
- Date: Fri, 21 Mar 2014 09:20:45 -0500
- To: libssh@xxxxxxxxxx
Hi folks, The function ssh_bind_options_set is documented twice, the versions disagree in places, and there are a few clarifications I thought could be made. The following patch consolidates all documentation for this function in src/options.c (I am under the impression we're putting documentation by function implementations) and makes some minor language tweaks. This patch applies on top of my ECDSA host key work, but it would be easy to make it apply to the current master; the only difference is the addition of documentation for SSH_BIND_OPTIONS_ECDSAKEY. Thanks, - Alan
From d723fbbd12430bfd99737488b124c18652b2aa77 Mon Sep 17 00:00:00 2001
From: Alan Dunn <amdunn@xxxxxxxxx>
Date: Fri, 21 Mar 2014 08:51:34 -0500
Subject: [PATCH] doc: Improve and consolidate ssh_bind_options_set docs
Signed-off-by: Alan Dunn <amdunn@xxxxxxxxx>
---
include/libssh/server.h | 63 -----------------------------
src/options.c | 101 +++++++++++++++++++++++++----------------------
2 files changed, 53 insertions(+), 111 deletions(-)
diff --git a/include/libssh/server.h b/include/libssh/server.h
index a1b8074..385a10a 100644
--- a/include/libssh/server.h
+++ b/include/libssh/server.h
@@ -81,69 +81,6 @@ typedef struct ssh_bind_callbacks_struct *ssh_bind_callbacks;
*/
LIBSSH_API ssh_bind ssh_bind_new(void);
-/**
- * @brief Set the options for the current SSH server bind.
- *
- * @param sshbind The ssh server bind to configure.
- *
- * @param type The option type to set. This could be one of the
- * following:
- *
- * - SSH_BIND_OPTIONS_BINDADDR
- * The ip address to bind (const char *).
- *
- * - SSH_BIND_OPTIONS_BINDPORT
- * The port to bind (unsigned int).
- *
- * - SSH_BIND_OPTIONS_BINDPORT_STR
- * The port to bind (const char *).
- *
- * - SSH_BIND_OPTIONS_HOSTKEY
- * This specifies the file containing the private host key used
- * by SSHv1. (const char *).
- *
- * - SSH_BIND_OPTIONS_DSAKEY
- * This specifies the file containing the private host dsa key
- * used by SSHv2. (const char *).
- *
- * - SSH_BIND_OPTIONS_RSAKEY
- * This specifies the file containing the private host dsa key
- * used by SSHv2. (const char *).
- *
- * - SSH_BIND_OPTIONS_BANNER
- * That the server banner (version string) for SSH.
- * (const char *).
- *
- * - SSH_BIND_OPTIONS_LOG_VERBOSITY
- * Set the session logging verbosity (int).\n
- * \n
- * The verbosity of the messages. Every log smaller or
- * equal to verbosity will be shown.
- * - SSH_LOG_NOLOG: No logging
- * - SSH_LOG_RARE: Rare conditions or warnings
- * - SSH_LOG_ENTRY: API-accessible entrypoints
- * - SSH_LOG_PACKET: Packet id and size
- * - SSH_LOG_FUNCTIONS: Function entering and leaving
- *
- * - SSH_BIND_OPTIONS_LOG_VERBOSITY_STR
- * Set the session logging verbosity (const char *).\n
- * \n
- * The verbosity of the messages. Every log smaller or
- * equal to verbosity will be shown.
- * - SSH_LOG_NOLOG: No logging
- * - SSH_LOG_RARE: Rare conditions or warnings
- * - SSH_LOG_ENTRY: API-accessible entrypoints
- * - SSH_LOG_PACKET: Packet id and size
- * - SSH_LOG_FUNCTIONS: Function entering and leaving
- * \n
- * See the corresponding numbers in libssh.h.
- *
- * @param value The value to set. This is a generic pointer and the
- * datatype which is used should be set according to the
- * type set.
- *
- * @returns SSH_OK on success, SSH_ERROR on invalid option or parameter.
- */
LIBSSH_API int ssh_bind_options_set(ssh_bind sshbind,
enum ssh_bind_options_e type, const void *value);
diff --git a/src/options.c b/src/options.c
index 1fda0c3..0b26024 100644
--- a/src/options.c
+++ b/src/options.c
@@ -1320,62 +1320,67 @@ static int ssh_bind_set_key(ssh_bind sshbind, char **key_loc,
}
/**
- * @brief This function can set all possible ssh bind options.
+ * @brief Set options for an SSH server bind.
*
- * @param sshbind An allocated ssh bind structure.
+ * @param sshbind The ssh server bind to configure.
*
- * @param type The option type to set. This could be one of the
+ * @param type The option type to set. This should be one of the
* following:
*
- * SSH_BIND_OPTIONS_LOG_VERBOSITY:
- * Set the session logging verbosity (integer).
- *
- * The verbosity of the messages. Every log smaller or
- * equal to verbosity will be shown.
- * SSH_LOG_NOLOG: No logging
- * SSH_LOG_RARE: Rare conditions or warnings
- * SSH_LOG_ENTRY: API-accessible entrypoints
- * SSH_LOG_PACKET: Packet id and size
- * SSH_LOG_FUNCTIONS: Function entering and leaving
- *
- * SSH_BIND_OPTIONS_LOG_VERBOSITY_STR:
- * Set the session logging verbosity (integer).
- *
- * The verbosity of the messages. Every log smaller or
- * equal to verbosity will be shown.
- * SSH_LOG_NOLOG: No logging
- * SSH_LOG_RARE: Rare conditions or warnings
- * SSH_LOG_ENTRY: API-accessible entrypoints
- * SSH_LOG_PACKET: Packet id and size
- * SSH_LOG_FUNCTIONS: Function entering and leaving
- *
- * SSH_BIND_OPTIONS_BINDADDR:
- * Set the bind address.
- *
- * SSH_BIND_OPTIONS_BINDPORT:
- * Set the bind port, default is 22.
- *
- * SSH_BIND_OPTIONS_HOSTKEY:
+ * - SSH_BIND_OPTIONS_HOSTKEY:
* Set the server public key type: ssh-rsa or ssh-dss
- * (string).
- *
- * SSH_BIND_OPTIONS_DSAKEY:
- * Set the path to the ssh host dsa key (string).
- *
- * SSH_BIND_OPTIONS_RSAKEY:
- * Set the path to the ssh host rsa key (string).
- *
- * SSH_BIND_OPTIONS_ECDSAKEY:
- * Set the path to the ssh host ecdsa key (string).
- *
- * SSH_BIND_OPTIONS_BANNER:
- * Set the server banner sent to clients (string).
+ * (const char *).
+ *
+ * - SSH_BIND_OPTIONS_BINDADDR:
+ * Set the IP address to bind (const char *).
+ *
+ * - SSH_BIND_OPTIONS_BINDPORT:
+ * Set the port to bind (unsigned int *).
+ *
+ * - SSH_BIND_OPTIONS_BINDPORT_STR:
+ * Set the port to bind (const char *).
+ *
+ * - SSH_BIND_OPTIONS_LOG_VERBOSITY:
+ * Set the session logging verbosity (int *).
+ * The logging verbosity should have one of the
+ * following values, which are listed in order
+ * of increasing verbosity. Every log message
+ * with verbosity less than or equal to the
+ * logging verbosity will be shown.
+ * - SSH_LOG_NOLOG: No logging
+ * - SSH_LOG_RARE: Rare conditions or warnings
+ * - SSH_LOG_ENTRY: API-accessible entrypoints
+ * - SSH_LOG_PACKET: Packet id and size
+ * - SSH_LOG_FUNCTIONS: Function entering and leaving
+ *
+ * - SSH_BIND_OPTIONS_LOG_VERBOSITY_STR:
+ * Set the session logging verbosity via a
+ * string that will be converted to a numerical
+ * value (e.g. "3") and interpreted according
+ * to the values of
+ * SSH_BIND_OPTIONS_LOG_VERBOSITY above (const
+ * char *).
+ *
+ * - SSH_BIND_OPTIONS_DSAKEY:
+ * Set the path to the ssh host dsa key, SSHv2
+ * only (const char *).
+ *
+ * - SSH_BIND_OPTIONS_RSAKEY:
+ * Set the path to the ssh host rsa key, SSHv2
+ * only (const char *).
+ *
+ * - SSH_BIND_OPTIONS_ECDSAKEY:
+ * Set the path to the ssh host ecdsa key,
+ * SSHv2 only (const char *).
+ *
+ * - SSH_BIND_OPTIONS_BANNER:
+ * Set the server banner sent to clients (const char *).
*
* @param value The value to set. This is a generic pointer and the
- * datatype which is used should be set according to the
- * type set.
+ * datatype which should be used is described at the
+ * corresponding value of type above.
*
- * @return 0 on success, < 0 on error.
+ * @return 0 on success, < 0 on error, invalid option, or parameter.
*/
int ssh_bind_options_set(ssh_bind sshbind, enum ssh_bind_options_e type,
const void *value) {
--
1.7.9.5
Archive administrator: postmaster@lists.cynapses.org