diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/libcurl/curl_getdate.3 | 116 |
1 files changed, 64 insertions, 52 deletions
diff --git a/docs/libcurl/curl_getdate.3 b/docs/libcurl/curl_getdate.3 index 6e936cf13..65a0e738b 100644 --- a/docs/libcurl/curl_getdate.3 +++ b/docs/libcurl/curl_getdate.3 @@ -4,35 +4,36 @@ .\" .TH curl_getdate 3 "5 March 2001" "libcurl 7.0" "libcurl Manual" .SH NAME -curl_getdate - Convert an date in a ASCII string to number of seconds since -January 1, 1970 +curl_getdate - Convert an date string to number of seconds since January 1, +1970 .SH SYNOPSIS .B #include <curl/curl.h> .sp -.BI "time_t curl_getdate(char *" datestring ", time_t *"now" ); +.BI "time_t curl_getdate(char *" datestring ", time_t *"now" );" .ad .SH DESCRIPTION -This function returns the number of seconds since January 1st 1970, for the -date and time that the -.I datestring -parameter specifies. The -.I now -parameter is there and should hold the current time to allow the datestring to -specify relative dates/times. Read further in the date string parser section -below. +This function returns the number of seconds since January 1st 1970 in the UTC +time zone, for the date and time that the \fIdatestring\fP parameter +specifies. The \fInow\fP parameter is not used, pass a NULL there. + +\fBNOTE:\fP This function was rewritten for the 7.12.2 release and this +documentation covers the functionality of the new one. The new one is not +feature-complete with the old one, but most of the formats supported by the +new one was supported by the old too. .SH PARSING DATES AND TIMES -A "date" is a string, possibly empty, containing many items separated by -whitespace. The whitespace may be omitted when no ambiguity arises. The -empty string means the beginning of today (i.e., midnight). Order of the -items is immaterial. A date string may contain many flavors of items: +A "date" is a string containing several items separated by whitespace. The +order of the items is immaterial. A date string may contain many flavors of +items: .TP 0.8i .B calendar date items -This can be specified in a number of different ways. Including 1970-09-17, 70-9-17, 70-09-17, 9/17/72, 24 September 1972, 24 Sept 72, 24 Sep 72, Sep 24, 1972, 24-sep-72, 24sep72. -The year can also be omitted, for example: 9/17 or "sep 17". +Can be specified several ways. Month names can only be three-letter +abbrivations, numbers can be zero-prefixed and the year may use 2 or 4 digits. +Examples: 06 Nov 1994, 06-Nov-94 and Nov-94 6. .TP .B time of the day items -This string specifies the time on a given day. Syntax supported includes: -18:19:0, 18:19, 6:19pm, 18:19-0500 (for specifying the time zone as well). +This string specifies the time on a given day. You must specify it with 6 +digits with two colons: HH:MM:SS. To not include the time in a date string, +will make the function assume 00:00:00. Example: 18:19:21. .TP .B time zone items Specifies international time zone. There are a few acronyms supported, but in @@ -40,41 +41,52 @@ general you should instead use the specific relative time compared to UTC. Supported formats include: -1200, MST, +0100. .TP .B day of the week items -Specifies a day of the week. If this is mentioned alone it means that day of -the week in the future. - -Days of the week may be spelled out in full: `Sunday', `Monday', etc or they -may be abbreviated to their first three letters, optionally followed by a -period. The special abbreviations `Tues' for `Tuesday', `Wednes' for -`Wednesday' and `Thur' or `Thurs' for `Thursday' are also allowed. - -A number may precede a day of the week item to move forward supplementary -weeks. It is best used in expression like `third monday'. In this context, -`last DAY' or `next DAY' is also acceptable; they move one week before or -after the day that DAY by itself would represent. -.TP -.B relative items -A relative item adjusts a date (or the current date if none) forward or -backward. Example syntax includes: "1 year", "1 year ago", "2 days", "4 -weeks". - -The string `tomorrow' is worth one day in the future (equivalent to `day'), -the string `yesterday' is worth one day in the past (equivalent to `day ago'). +Specifies a day of the week. Days of the week may be spelled out in full: +`Sunday', `Monday', etc or they may be abbreviated to their first three +letters. This is usually not info that adds anything. .TP .B pure numbers -If the decimal number is of the form YYYYMMDD and no other calendar date item -appears before it in the date string, then YYYY is read as the year, MM as the -month number and DD as the day of the month, for the specified calendar date. +If a decimal number of the form YYYYMMDD appears, then YYYY is read as the +year, MM as the month number and DD as the day of the month, for the specified +calendar date. .PP +.SH EXAMPLES +.nf +Sun, 06 Nov 1994 08:49:37 GMT +Sunday, 06-Nov-94 08:49:37 GMT +Sun Nov 6 08:49:37 1994 +06 Nov 1994 08:49:37 GMT +06-Nov-94 08:49:37 GMT +Nov 6 08:49:37 1994 +06 Nov 1994 08:49:37 +06-Nov-94 08:49:37 +1994 Nov 6 08:49:37 +GMT 08:49:37 06-Nov-94 Sunday +94 6 Nov 08:49:37 +1994 Nov 6 +06-Nov-94 +Sun Nov 6 94 +1994.Nov.6 +Sun/Nov/6/94/GMT +Sun, 06 Nov 1994 08:49:37 CET +06 Nov 1994 08:49:37 EST +Sun, 12 Sep 2004 15:05:58 -0700 +Sat, 11 Sep 2004 21:32:11 +0200 +20040912 15:05:58 -0700 +20040911 +0200 +.fi +.SH STANDARDS +This parser was written to handle date formats specified in RFC 822 (including +the update in RFC 1123) using time zone name or time zone delta and RFC 850 +(obsoleted by RFC 1036) and ANSI C's asctime() format. These formats are the +only ones RFC2616 says HTTP applications may use. .SH RETURN VALUE -This function returns zero when it fails to parse the date string. Otherwise -it returns the number of seconds as described. -.SH AUTHORS -Originally written by Steven M. Bellovin <smb@research.att.com> while at the -University of North Carolina at Chapel Hill. Later tweaked by a couple of -people on Usenet. Completely overhauled by Rich $alz <rsalz@bbn.com> and Jim -Berets <jberets@bbn.com> in August, 1990. +This function returns -1 when it fails to parse the date string. Otherwise it +returns the number of seconds as described. +.SH REWRITE +The former version of this function was built with yacc and was not only very +large, it was also never quite understood and it wasn't possible to build with +non-GNU tools since only Bison could make it thread-safe! -It has been modified extensively since imported to curl. -.SH "SEE ALSO" -.BR GNU date(1) +The rewrite was done for 7.12.2. The new one is much smaller and use simpler +code. |