* 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

@@ -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,17 +98,14 @@ 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;
     gmt = gmtime(&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;

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