Improve documentation by mentioning the free functions

Related: https://gitlab.com/libssh/libssh-mirror/-/issues/3
Signed-off-by: Jakub Jelen <jjelen@redhat.com>
Reviewed-by: Andreas Schneider <asn@cryptomilk.org>

src/channels.c

@@ -80,6 +80,9 @@ static ssh_channel channel_from_msg(ssh_session session, ssh_buffer packet);
  * @param[in]  session  The ssh session to use.
  *
  * @return              A pointer to a newly allocated channel, NULL on error.
+ *                      The channel needs to be freed with ssh_channel_free().
+ *
+ * @see ssh_channel_free()
  */
 ssh_channel ssh_channel_new(ssh_session session)
 {

src/dh.c

@@ -711,7 +711,8 @@ static char *ssh_get_b64_unpadded(const unsigned char *hash, size_t len)
  *
  * @param  len          Length of the buffer to convert.
  *
- * @return Returns the allocated fingerprint hash or NULL on error.
+ * @return Returns the allocated fingerprint hash or NULL on error. The caller
+ *         needs to free the memory using ssh_string_free_char().
  *
  * @see ssh_string_free_char()
  */

src/misc.c

@@ -834,7 +834,7 @@ const void *_ssh_list_pop_head(struct ssh_list *list){
  * dirname breaks a null-terminated pathname string into a directory component.
  * In the usual case, ssh_dirname() returns the string up to, but not including,
  * the final '/'. Trailing '/' characters are  not  counted as part of the
- * pathname. The caller must free the memory.
+ * pathname. The caller must free the memory using ssh_string_free_char().
  *
  * @param[in]  path     The path to parse.
  *
@@ -842,7 +842,10 @@ const void *_ssh_list_pop_head(struct ssh_list *list){
  *                      If path does not contain a slash, c_dirname() returns
  *                      the string ".".  If path is a string "/", it returns
  *                      the string "/". If path is NULL or an empty string,
- *                      "." is returned.
+ *                      "." is returned. The memory needs to be freed using
+ *                      ssh_string_free_char().
+ *
+ * @see ssh_string_free_char()
  */
 char *ssh_dirname (const char *path) {
   char *new = NULL;
@@ -897,7 +900,10 @@ char *ssh_dirname (const char *path) {
  * @return              The filename of path or NULL if we can't allocate
  *                      memory. If path is the string "/", basename returns
  *                      the string "/". If path is NULL or an empty string,
- *                      "." is returned.
+ *                      "." is returned. The caller needs to free this memory
+ *                      ssh_string_free_char().
+ *
+ * @see ssh_string_free_char()
  */
 char *ssh_basename (const char *path) {
   char *new = NULL;
@@ -1032,7 +1038,10 @@ int ssh_mkdirs(const char *pathname, mode_t mode)
  *
  * @param[in]  d        The directory to expand.
  *
- * @return              The expanded directory, NULL on error.
+ * @return              The expanded directory, NULL on error. The caller
+ *                      needs to free the memory using ssh_string_free_char().
+ *
+ * @see ssh_string_free_char()
  */
 char *ssh_path_expand_tilde(const char *d) {
     char *h = NULL, *r;
@@ -1101,7 +1110,10 @@ char *ssh_path_expand_tilde(const char *d) {
  *              %l local hostname
  *              %r remote username
  *              %p remote port
- * @returns Expanded string.
+ * @returns Expanded string. The caller needs to free the memory using
+ *          ssh_string_free_char().
+ *
+ * @see ssh_string_free_char()
  */
 char *ssh_path_expand_escape(ssh_session session, const char *s) {
     char host[NI_MAXHOST] = {0};
@@ -1844,7 +1856,10 @@ err:
  * @param[in]  replace      String to be replaced is stored in replace.
  *
  * @returns  src_replaced a pointer that points to the replaced string.
- * NULL if allocation fails or if src is NULL.
+ * NULL if allocation fails or if src is NULL. The returned memory needs to be
+ * freed using ssh_string_free_char().
+ *
+ * @see ssh_string_free_char()
  */
 char *ssh_strreplace(const char *src, const char *pattern, const char *replace)
 {

src/options.c

@@ -57,11 +57,12 @@
  * @param src           The session to use to copy the options.
  *
  * @param dest          A pointer to store the allocated session with duplicated
- *                      options. You have to free the memory.
+ *                      options. You have to free the memory using ssh_free()
  *
  * @returns             0 on success, -1 on error with errno set.
  *
  * @see ssh_session_connect()
+ * @see ssh_free()
  */
 int ssh_options_copy(ssh_session src, ssh_session *dest)
 {

src/pki.c

@@ -811,7 +811,7 @@ void ssh_signature_free(ssh_signature sig)
  * @param[in]  auth_data Private data passed to the auth function.
  *
  * @param[out] pkey     A pointer where the allocated key can be stored. You
- *                      need to free the memory.
+ *                      need to free the memory using ssh_key_free()
  *
  * @return  SSH_ERROR in case of error, SSH_OK otherwise.
  *
@@ -874,9 +874,11 @@ int ssh_pki_import_privkey_base64(const char *b64_key,
  * @param[in]  auth_data Private data passed to the auth function.
  *
  * @param[out] b64_key  A pointer to store the allocated base64 encoded key. You
- *                      need to free the buffer.
+ *                      need to free the buffer using ssh_string_from_char().
  *
  * @return     SSH_OK on success, SSH_ERROR on error.
+ *
+ * @see ssh_string_free_char()
  */
 int ssh_pki_export_privkey_base64(const ssh_key privkey,
                                   const char *passphrase,
@@ -931,7 +933,7 @@ int ssh_pki_export_privkey_base64(const ssh_key privkey,
  * @param[in]  auth_data Private data passed to the auth function.
  *
  * @param[out] pkey     A pointer to store the allocated ssh_key. You need to
- *                      free the key.
+ *                      free the key using ssh_key_free().
  *
  * @returns SSH_OK on success, SSH_EOF if the file doesn't exist or permission
  *          denied, SSH_ERROR otherwise.
@@ -1600,7 +1602,7 @@ fail:
  * @param[in]  type     The type of the key to format.
  *
  * @param[out] pkey     A pointer where the allocated key can be stored. You
- *                      need to free the memory.
+ *                      need to free the memory using ssh_key_free().
  *
  * @return              SSH_OK on success, SSH_ERROR on error.
  *
@@ -1648,7 +1650,7 @@ int ssh_pki_import_pubkey_base64(const char *b64_key,
  *                      6.6 "Public Key Algorithms".
  *
  * @param[out] pkey     A pointer where the allocated key can be stored. You
- *                      need to free the memory.
+ *                      need to free the memory using ssh_key_free().
  *
  * @return              SSH_OK on success, SSH_ERROR on error.
  *
@@ -1735,7 +1737,10 @@ bool ssh_pki_is_uri(const char *cmp)
  *
  * @param[in] priv_uri Private PKCS #11 URI.
  *
- * @returns pointer to the public PKCS #11 URI
+ * @returns pointer to the public PKCS #11 URI. You need to free
+ *          the memory using ssh_string_free_char().
+ *
+ * @see ssh_string_free_char().
  */
 char *ssh_pki_export_pub_uri_from_priv_uri(const char *priv_uri)
 {
@@ -1755,7 +1760,7 @@ char *ssh_pki_export_pub_uri_from_priv_uri(const char *priv_uri)
  *                      PKCS #11 URI corresponding to the public key.
  *
  * @param[out] pkey     A pointer to store the allocated public key. You need to
- *                      free the memory.
+ *                      free the memory using ssh_key_free().
  *
  * @returns SSH_OK on success, SSH_EOF if the file doesn't exist or permission
  *          denied, SSH_ERROR otherwise.
@@ -1878,7 +1883,7 @@ int ssh_pki_import_pubkey_file(const char *filename, ssh_key *pkey)
  * @param[in]  type     The type of the cert to format.
  *
  * @param[out] pkey     A pointer where the allocated key can be stored. You
- *                      need to free the memory.
+ *                      need to free the memory using ssh_key_free().
  *
  * @return              SSH_OK on success, SSH_ERROR on error.
  *
@@ -1899,7 +1904,7 @@ int ssh_pki_import_cert_base64(const char *b64_cert,
  *                      6.6 "Public Key Algorithms".
  *
  * @param[out] pkey     A pointer where the allocated key can be stored. You
- *                      need to free the memory.
+ *                      need to free the memory using ssh_key_free().
  *
  * @return              SSH_OK on success, SSH_ERROR on error.
  *
@@ -1916,7 +1921,7 @@ int ssh_pki_import_cert_blob(const ssh_string cert_blob,
  * @param[in]  filename The path to the certificate.
  *
  * @param[out] pkey     A pointer to store the allocated certificate. You need to
- *                      free the memory.
+ *                      free the memory using ssh_key_free().
  *
  * @returns SSH_OK on success, SSH_EOF if the file doesn't exist or permission
  *          denied, SSH_ERROR otherwise.
@@ -1937,11 +1942,13 @@ int ssh_pki_import_cert_file(const char *filename, ssh_key *pkey)
  *                      rsa : length of the key in bits (e.g. 1024, 2048, 4096)
  *                      dsa : length of the key in bits (e.g. 1024, 2048, 3072)
  * @param[out] pkey     A pointer to store the allocated private key. You need
- *                      to free the memory.
+ *                      to free the memory using ssh_key_free().
  *
  * @return              SSH_OK on success, SSH_ERROR on error.
  *
  * @warning             Generating a key pair may take some time.
+ *
+ * @see ssh_key_free()
  */
 int ssh_pki_generate(enum ssh_keytypes_e type, int parameter,
         ssh_key *pkey){
@@ -2031,7 +2038,7 @@ error:
  * @param[in]  privkey  The private key to get the public key from.
  *
  * @param[out] pkey     A pointer to store the newly allocated public key. You
- *                      NEED to free the key.
+ *                      NEED to free the key using ssh_key_free().
  *
  * @return              SSH_OK on success, SSH_ERROR on error.
  *
@@ -2069,11 +2076,11 @@ int ssh_pki_export_privkey_to_pubkey(const ssh_key privkey,
  *                      from.
  *
  * @param[out] pblob    A pointer to store the newly allocated key blob. You
- *                      NEED to free it.
+ *                      need to free it using ssh_string_free().
  *
  * @return              SSH_OK on success, SSH_ERROR otherwise.
  *
- * @see SSH_STRING_FREE()
+ * @see ssh_string_free()
  */
 int ssh_pki_export_pubkey_blob(const ssh_key key,
                                ssh_string *pblob)
@@ -2099,11 +2106,11 @@ int ssh_pki_export_pubkey_blob(const ssh_key key,
  * @param[in] key       The key to hash
  *
  * @param[out] b64_key  A pointer to store the allocated base64 encoded key. You
- *                      need to free the buffer.
+ *                      need to free the buffer using ssh_string_free_char()
  *
  * @return              SSH_OK on success, SSH_ERROR on error.
  *
- * @see SSH_STRING_FREE_CHAR()
+ * @see ssh_string_free_char()
  */
 int ssh_pki_export_pubkey_base64(const ssh_key key,
                                  char **b64_key)

src/pki_container_openssh.c

@@ -49,7 +49,7 @@
  *                            code.
  *
  * @param[out] pkey     A pointer where the allocated key can be stored. You
- *                      need to free the memory.
+ *                      need to free the memory using ssh_key_free().
  *
  * @return              SSH_OK on success, SSH_ERROR on error.
  *

src/session.c

@@ -1057,7 +1057,7 @@ void ssh_clean_pubkey_hash(unsigned char **hash) {
  * @param[in]  session  The session to get the key from.
  *
  * @param[out] key      A pointer to store the allocated key. You need to free
- *                      the key.
+ *                      the key using ssh_key_free().
  *
  * @return              SSH_OK on success, SSH_ERROR on errror.
  *
@@ -1101,7 +1101,7 @@ int ssh_get_publickey(ssh_session session, ssh_key *key)
  *
  * @param[in]  type     The type of the hash you want.
  *
- * @param[in]  hash     A pointer to store the allocated buffer. It can be
+ * @param[out]  hash    A pointer to store the allocated buffer. It can be
  *                      freed using ssh_clean_pubkey_hash().
  *
  * @param[in]  hlen     The length of the hash.