-.\" You can view this file with:
-.\" nroff -man [file]
-.\" $Id$
-.\"
-.TH curl_getdate 3 "5 March 2001" "libcurl 7.0" "libcurl Manual"
+.\" **************************************************************************
+.\" * _ _ ____ _
+.\" * Project ___| | | | _ \| |
+.\" * / __| | | | |_) | |
+.\" * | (__| |_| | _ <| |___
+.\" * \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at http://curl.haxx.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" **************************************************************************
+.TH curl_getdate 3 "12 Aug 2005" "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 a date string to number of seconds
.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.
+\fIcurl_getdate(3)\fP returns the number of seconds since the Epoch, January
+1st 1970 00:00:00 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.
.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 english
+abbreviations, 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
-general you should instead use the specific realtive time compared to
+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
+(using english): `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.
+
+If the year is larger than 2037 on systems with 32 bit time_t, this function
+will return 0x7fffffff (since that is the largest possible signed 32 bit
+number).
+
+Having a 64 bit time_t is not a guarantee that dates beyond 03:14:07 UTC,
+January 19, 2038 will work fine. On systems with a 64 bit time_t but with a
+crippled mktime(), \fIcurl_getdate(3)\fP will return -1 in this case.
.SH "SEE ALSO"
-.BR
-.SH BUGS
-Surely there are some, you tell me!
+.BR curl_easy_escape "(3), " curl_easy_unescape "(3), "
+.BR CURLOPT_TIMECONDITION "(3), " CURLOPT_TIMEVALUE "(3) "
projects / platform / upstream / curl.git / blobdiff