From aa315bd6b7c585f9da548995173e3c1abe5044e3 Mon Sep 17 00:00:00 2001
From: Joe Orton <jorton@redhat.com>
Date: Thu, 23 Nov 2023 14:13:13 +0000
Subject: [PATCH] * src/ne_dates.c, src/ne_dates.h: Throughout: update comments
 to current   RFC standards. Add nonnull return attributes. Clarify API error
 cases.

---
 src/ne_dates.c | 14 ++++----------
 src/ne_dates.h | 49 +++++++++++++++++++++++++++++--------------------
 2 files changed, 33 insertions(+), 30 deletions(-)

diff --git a/src/ne_dates.c b/src/ne_dates.c
index c82d7103..3f0c3c88 100644
--- a/src/ne_dates.c
+++ b/src/ne_dates.c
@@ -49,8 +49,8 @@
 #define ISO8601_FORMAT_M "%04d-%02d-%02dT%02d:%02d:%lf-%02d:%02d"
 #define ISO8601_FORMAT_P "%04d-%02d-%02dT%02d:%02d:%lf+%02d:%02d"
 
-/* RFC1123: Sun, 06 Nov 1994 08:49:37 GMT */
-#define RFC1123_FORMAT "%3s, %02d %3s %4d %02d:%02d:%02d GMT"
+/* IMF-fixdate: Sun, 06 Nov 1994 08:49:37 GMT */
+#define IMFFIX_FORMAT "%3s, %02d %3s %4d %02d:%02d:%02d GMT"
 /* RFC850:  Sunday, 06-Nov-94 08:49:37 GMT */
 #define RFC1036_FORMAT "%10s %2d-%3s-%2d %2d:%2d:%2d GMT"
 /* asctime: Wed Jun 30 21:49:08 1993 */
@@ -98,8 +98,6 @@ time_t gmt_to_local_win32(void)
 }
 #endif
 
-/* Returns the time/date GMT, in RFC1123-type format: eg
- *  Sun, 06 Nov 1994 08:49:37 GMT. */
 char *ne_rfc1123_date(time_t anytime) {
     struct tm *gmt;
     char *ret;
@@ -107,8 +105,7 @@ char *ne_rfc1123_date(time_t anytime) {
     if (gmt == NULL)
 	return NULL;
     ret = ne_malloc(29 + 1); /* dates are 29 chars long */
-/*  it goes: Sun, 06 Nov 1994 08:49:37 GMT */
-    ne_snprintf(ret, 30, RFC1123_FORMAT,
+    ne_snprintf(ret, 30, IMFFIX_FORMAT,
 		rfc1123_weekdays[gmt->tm_wday], gmt->tm_mday, 
 		short_months[gmt->tm_mon], 1900 + gmt->tm_year, 
 		gmt->tm_hour, gmt->tm_min, gmt->tm_sec);
@@ -161,8 +158,6 @@ time_t ne_iso8601_parse(const char *date)
     return result + GMTOFF(gmt);
 }
 
-/* Takes an RFC1123-formatted date string and returns the time_t.
- * Returns (time_t)-1 if the parse fails. */
 time_t ne_rfc1123_parse(const char *date) 
 {
     struct tm gmt = {0};
@@ -171,7 +166,7 @@ time_t ne_rfc1123_parse(const char *date)
     time_t result;
     
     /* it goes: Sun, 06 Nov 1994 08:49:37 GMT */
-    if (sscanf(date, RFC1123_FORMAT,
+    if (sscanf(date, IMFFIX_FORMAT,
                wkday, &gmt.tm_mday, mon, &gmt.tm_year, &gmt.tm_hour,
                &gmt.tm_min, &gmt.tm_sec) != 7)
         return (time_t) -1;
@@ -249,7 +244,6 @@ time_t ne_asctime_parse(const char *date)
     return result + GMTOFF(gmt);
 }
 
-/* HTTP-date parser */
 time_t ne_httpdate_parse(const char *date)
 {
     time_t tmp;
diff --git a/src/ne_dates.h b/src/ne_dates.h
index 484dfdf5..78e68c42 100644
--- a/src/ne_dates.h
+++ b/src/ne_dates.h
@@ -28,26 +28,35 @@
 
 NE_BEGIN_DECLS
 
-/* Date manipulation routines as per RFC1123 and RFC1036 */
-
-/* Return current date/time in RFC1123 format */
-char *ne_rfc1123_date(time_t anytime);
-
-/* Returns time from date/time using the subset of the ISO8601 format
- * referenced in RFC2518 (e.g as used in the creationdate property in
- * the DAV: namespace). */
-time_t ne_iso8601_parse(const char *date);
-
-/* Returns time from date/time in RFC1123 format */
-time_t ne_rfc1123_parse(const char *date);
-
-time_t ne_rfc1036_parse(const char *date);
-
-/* Parses asctime date string */
-time_t ne_asctime_parse(const char *date);
-
-/* Parse an HTTP-date as per RFC2616 */
-time_t ne_httpdate_parse(const char *date);
+/* Convert time to a string following the Internet Message Format RFC
+ * standard (historically known as "RFC1123", currently known as
+ * RFC5322). Returns a malloc-allocated string, or NULL if there is an
+ * error converting the time. */
+char *ne_rfc1123_date(time_t anytime)
+    ne_attribute_malloc;
+
+/* Parses a date/time using the the ISO8601 format. Returns -1 on
+ * error. */
+time_t ne_iso8601_parse(const char *date)
+    ne_attribute((nonnull));
+
+/* Parses a date/time using the the IMF-fixdate format (historically
+ * known as "RFC1123". Returns -1 on error. */
+time_t ne_rfc1123_parse(const char *date)
+    ne_attribute((nonnull));
+
+/* Parses a date/time using the the RFC1036 format. Returns -1 on
+ * error. */
+time_t ne_rfc1036_parse(const char *date)
+    ne_attribute((nonnull));
+
+/* Parses a libc "asctime" format date. Returns -1 on error. */
+time_t ne_asctime_parse(const char *date)
+    ne_attribute((nonnull));
+
+/* Parse an HTTP-date as perq RFC2616. Returns -1 on error. */
+time_t ne_httpdate_parse(const char *date)
+    ne_attribute((nonnull));
 
 NE_END_DECLS