kc3-lang/smtp

diff --git a/Makefile b/Makefile
index 158f639..d1f1216 100644
--- a/Makefile
+++ b/Makefile
@@ -78,6 +78,7 @@ CWARN.gcc += -Wvector-operation-performance
 
 CWARN.clang += -Weverything
 CWARN.clang += -Wno-format-nonliteral
+CWARN.clang += -Wno-documentation-deprecated-sync
 CWARN.clang += -fcomment-block-commands=retval
 
 CFLAGS += $(CWARN)
diff --git a/README.md b/README.md
index ccb3c1e..905fbbe 100644
--- a/README.md
+++ b/README.md
@@ -118,9 +118,7 @@ example, the program checks for an error at the end of the mail session after
 calling smtp_close. We can do this because if an error occurs in any of the
 prior functions, the error will continue to propagate through any future
 function calls until either closing the SMTP context using smtp_close or by
-resetting the error condition using smtp_status_code_set. However, make sure to
-review the smtp_status_code_set function prior to using that option for
-clearing the error message to avoid any undefined behavior.
+resetting the error condition using smtp_status_code_clear.
 
 ## Technical Documentation
 See the [Technical Documentation](https://www.somnisoft.com/smtp-client/technical-documentation/index.html) generated from Doxygen.
diff --git a/src/smtp.c b/src/smtp.c
index b89d464..8298110 100644
--- a/src/smtp.c
+++ b/src/smtp.c
@@ -3186,6 +3186,15 @@ smtp_status_code_get(const struct smtp *const smtp){
 }
 
 enum smtp_status_code
+smtp_status_code_clear(struct smtp *const smtp){
+  enum smtp_status_code old_status;
+
+  old_status = smtp_status_code_get(smtp);
+  smtp_status_code_set(smtp, SMTP_STATUS_OK);
+  return old_status;
+}
+
+enum smtp_status_code
 smtp_status_code_set(struct smtp *const smtp,
                      enum smtp_status_code status_code){
   if((unsigned)status_code >= SMTP_STATUS__LAST){
diff --git a/src/smtp.h b/src/smtp.h
index 239fd7b..8d606f1 100644
--- a/src/smtp.h
+++ b/src/smtp.h
@@ -298,6 +298,15 @@ enum smtp_status_code
 smtp_status_code_get(const struct smtp *const smtp);
 
 /**
+ * Clear the current error code set in the SMTP client context.
+ *
+ * @param[in,out] smtp SMTP client context.
+ * @return             Previous error code before clearing.
+ */
+enum smtp_status_code
+smtp_status_code_clear(struct smtp *const smtp);
+
+/**
  * Set the error status of the SMTP client context and return the same code.
  *
  * This allows the caller to clear an error status to SMTP_STATUS_OK
@@ -305,8 +314,10 @@ smtp_status_code_get(const struct smtp *const smtp);
  * work correctly for clearing the SMTP_STATUS_PARAM and SMTP_STATUS_FILE
  * errors. Do not use this to clear any other error codes.
  *
- * @param[in] smtp        SMTP client context.
- * @param[in] status_code See @ref smtp_status_code.
+ * @deprecated Use @ref smtp_status_code_clear instead.
+ *
+ * @param[in] smtp            SMTP client context.
+ * @param[in] new_status_code See @ref smtp_status_code.
  * @return See @ref smtp_status_code.
  */
 enum smtp_status_code
diff --git a/test/test.c b/test/test.c
index f0bd51f..2f88beb 100644
--- a/test/test.c
+++ b/test/test.c
@@ -2220,7 +2220,7 @@ smtp_func_test_all_status_code_get(struct smtp_test_config *const config){
   smtp_status_code_set(config->smtp, SMTP_STATUS_NOMEM);
   rc = smtp_status_code_get(config->smtp);
   assert(rc == SMTP_STATUS_NOMEM);
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
 
   rc = smtp_close(config->smtp);
   assert(rc == SMTP_STATUS_OK);
@@ -2840,7 +2840,7 @@ smtp_func_test_all_address(struct smtp_test_config *const config){
   rc = smtp_mail(config->smtp,
                  "This email should not have a FROM address in the header.");
   assert(rc == SMTP_STATUS_PARAM);
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
 
   /* FROM address contains UTF-8 characters. */
   smtp_header_clear_all(config->smtp);
@@ -3685,7 +3685,7 @@ test_failure_address_add(struct smtp_test_config *const config){
   assert(rc == SMTP_STATUS_NOMEM);
 
   /* Invalid email address. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   rc = smtp_address_add(config->smtp,
                         SMTP_ADDRESS_FROM,
                         "<invalid>",
@@ -3693,7 +3693,7 @@ test_failure_address_add(struct smtp_test_config *const config){
   assert(rc == SMTP_STATUS_PARAM);
 
   /* Invalid email name. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   rc = smtp_address_add(config->smtp,
                         SMTP_ADDRESS_FROM,
                         config->email_from,
@@ -3701,7 +3701,7 @@ test_failure_address_add(struct smtp_test_config *const config){
   assert(rc == SMTP_STATUS_PARAM);
 
   /* Wrap when trying to increase size of address list. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_si_add_size_t_ctr = 0;
   rc = smtp_address_add(config->smtp,
                         SMTP_ADDRESS_FROM,
@@ -3711,7 +3711,7 @@ test_failure_address_add(struct smtp_test_config *const config){
   assert(rc == SMTP_STATUS_NOMEM);
 
   /* Memory allocation failed while trying to increase size of address list. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_realloc_ctr = 0;
   rc = smtp_address_add(config->smtp,
                         SMTP_ADDRESS_FROM,
@@ -3721,7 +3721,7 @@ test_failure_address_add(struct smtp_test_config *const config){
   assert(rc == SMTP_STATUS_NOMEM);
 
   /* Failed to duplicate email string. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_malloc_ctr = 0;
   rc = smtp_address_add(config->smtp,
                         SMTP_ADDRESS_FROM,
@@ -3731,7 +3731,7 @@ test_failure_address_add(struct smtp_test_config *const config){
   assert(rc == SMTP_STATUS_NOMEM);
 
   /* Failed to duplicate name string. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_malloc_ctr = 1;
   rc = smtp_address_add(config->smtp,
                         SMTP_ADDRESS_FROM,
@@ -3766,7 +3766,7 @@ test_failure_attachment_add(struct smtp_test_config *const config){
 
 
   /* Invalid SMTP status code. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_PARAM);
+  smtp_status_code_clear(config->smtp);
   rc = smtp_attachment_add_mem(config->smtp,
                                "valid",
                                "test",
@@ -3775,7 +3775,7 @@ test_failure_attachment_add(struct smtp_test_config *const config){
 
 
   /* Invalid filename parameter. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   rc = smtp_attachment_add_mem(config->smtp,
                                "\"invalid\"",
                                "test",
@@ -3783,7 +3783,7 @@ test_failure_attachment_add(struct smtp_test_config *const config){
   assert(rc == SMTP_STATUS_PARAM);
 
   /* Wrap when increasing the attachment list size. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_si_add_size_t_ctr = 0;
   rc = smtp_attachment_add_mem(config->smtp,
                                "valid",
@@ -3793,7 +3793,7 @@ test_failure_attachment_add(struct smtp_test_config *const config){
   g_smtp_test_err_si_add_size_t_ctr = -1;
 
   /* Memory allocation failure while increasing the attachment list size. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_realloc_ctr = 0;
   rc = smtp_attachment_add_mem(config->smtp,
                                "valid",
@@ -3803,7 +3803,7 @@ test_failure_attachment_add(struct smtp_test_config *const config){
   g_smtp_test_err_realloc_ctr = -1;
 
   /* Memory allocation failure while using smtp_strdup on file name. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_malloc_ctr = 0;
   rc = smtp_attachment_add_mem(config->smtp,
                                "valid",
@@ -3814,7 +3814,7 @@ test_failure_attachment_add(struct smtp_test_config *const config){
 
 
   /* Memory allocation failure while using smtp_base64_encode. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_calloc_ctr = 0;
   rc = smtp_attachment_add_mem(config->smtp,
                                "valid",
@@ -3824,7 +3824,7 @@ test_failure_attachment_add(struct smtp_test_config *const config){
   g_smtp_test_err_calloc_ctr = -1;
 
   /* Memory allocation failure when splitting base64 lines into chunks. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_calloc_ctr = 1;
   rc = smtp_attachment_add_mem(config->smtp,
                                "valid",
@@ -3834,19 +3834,19 @@ test_failure_attachment_add(struct smtp_test_config *const config){
   g_smtp_test_err_calloc_ctr = -1;
 
   /* Invalid SMTP status code. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_PARAM);
+  smtp_status_code_clear(config->smtp);
   rc = smtp_attachment_add_fp(config->smtp, "test", stdin);
   assert(rc == SMTP_STATUS_PARAM);
 
   /* @ref smtp_ffile_get_contents memory allocation failure. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_realloc_ctr = 0;
   rc = smtp_attachment_add_fp(config->smtp, "test", stdin);
   g_smtp_test_err_realloc_ctr = -1;
   assert(rc == SMTP_STATUS_NOMEM);
 
   /* @ref smtp_ffile_get_contents fread error. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   fp = fopen("COPYING", "r");
   assert(fp);
   g_smtp_test_err_ferror_ctr = 0;
@@ -3857,7 +3857,7 @@ test_failure_attachment_add(struct smtp_test_config *const config){
   assert(fp_rc == 0);
 
   /* @ref smtp_file_get_contents memory allocation failure. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_realloc_ctr = 0;
   rc = smtp_attachment_add_path(config->smtp, "test", "COPYING");
   g_smtp_test_err_realloc_ctr = -1;
@@ -3898,35 +3898,35 @@ test_failure_header_add(struct smtp_test_config *const config){
   assert(rc == SMTP_STATUS_NOMEM);
 
   /* Invalid header key. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   rc = smtp_header_add(config->smtp,
                        "invalid:",
                        "value");
   assert(rc == SMTP_STATUS_PARAM);
 
   /* Invalid header value. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   rc = smtp_header_add(config->smtp,
                        "key",
                        "invalid\n");
   assert(rc == SMTP_STATUS_PARAM);
 
   /* Wrap when increasing the header list size. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_si_add_size_t_ctr = 0;
   rc = smtp_header_add(config->smtp, "key", "value");
   g_smtp_test_err_si_add_size_t_ctr = -1;
   assert(rc == SMTP_STATUS_NOMEM);
 
   /* Memory allocation failure while trying to increase header list size. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_realloc_ctr = 0;
   rc = smtp_header_add(config->smtp, "key", "value");
   g_smtp_test_err_realloc_ctr = -1;
   assert(rc == SMTP_STATUS_NOMEM);
 
   /* Failed to strdup header key. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_malloc_ctr = 0;
   rc = smtp_header_add(config->smtp,
                        "key",
@@ -3935,7 +3935,7 @@ test_failure_header_add(struct smtp_test_config *const config){
   assert(rc == SMTP_STATUS_NOMEM);
 
   /* Failed to strdup header value. */
-  smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  smtp_status_code_clear(config->smtp);
   g_smtp_test_err_malloc_ctr = 1;
   rc = smtp_header_add(config->smtp,
                        "key",
@@ -3970,7 +3970,7 @@ test_failure_status_code_set(struct smtp_test_config *const config){
   rc = smtp_status_code_set(config->smtp, SMTP_STATUS__LAST);
   assert(rc == SMTP_STATUS_PARAM);
 
-  rc = smtp_status_code_set(config->smtp, SMTP_STATUS_OK);
+  rc = smtp_status_code_clear(config->smtp);
   assert(rc == SMTP_STATUS_OK);
 
   rc = smtp_close(config->smtp);