GETDATE - Linux手册页
Linux程序员手册 第3部分
更新日期： 2020-06-09
名称
getdate，getdate_r-将日期加时间字符串转换为细分时间
语法
＃包括
struct tm * getdate(const char * string);
extern int getdate_err;
＃包括
int getdate_r(const char * string，struct tm * res);
glibc的功能测试宏要求(请参阅feature_test_macros(7))：
getdate()：
- _XOPEN_SOURCE>= 500
- _GNU_SOURCE
说明
函数getdate()将包含在字符串指向的缓冲区中的日期和时间的字符串表示形式转换为细分时间。分解时间存储在tm结构中，并返回指向该结构的指针作为函数结果。此tm结构是在静态存储中分配的，因此，它将被进一步调用getdate()覆盖。
与strptime(3)(具有format参数)相反，getdate()使用在环境变量DATEMSK中给出其完整路径名的文件中找到的格式。文件中与给定输入字符串匹配的第一行用于转换。
匹配不区分大小写。模式或要转换的字符串中的多余空格都将被忽略。
模式可以包含的转换规范是为strptime(3)给出的。 POSIX.1-2001中指定了另一种转换规范：
- %Z
- 时区名称。这在glibc中未实现。
当给出％Z时，将使用对应于给定时区中当前时间的值来初始化包含细分时间的结构。否则，将结构初始化为与当前本地时间相对应的细分时间(例如通过调用localtime(3))。
如果仅给出星期几，则将当天视为今天或之后的第一天。
如果只给出月份(没有年份)，则该月份被视为等于或低于当前月份的第一个月。如果没有给出日期，则为该月的第一天。
如果未指定小时，分钟和秒，则采用当前的小时，分钟和秒。
如果没有给出日期，但我们知道小时，则该小时被视为等于或大于当前小时的第一个此类小时。
getdate_r()是GNU扩展，它提供了getdate()的可重入版本。它不是使用全局变量报告错误，也不使用静态缓冲区返回中断时间，而是通过函数结果值返回错误，并在由参数res指向的调用者分配的缓冲区中返回中断时间。
返回值
成功时，getdate()返回指向结构tm的指针。否则，它将返回NULL并将全局变量getdate_err设置为如下所示的错误号之一。 errno的更改未指定。
成功时，getdate_r()返回0；否则，返回0。如果出现错误，它将返回如下所示的错误号之一。
错误说明
通过getdate_err(对于getdate())或作为函数结果(对于getdate_r())返回以下错误：
- 1
- 未定义DATEMSK环境变量，或者它的值是一个空字符串。
- 2
- 无法打开DATEMSK指定的模板文件进行读取。
- 3
- 无法获取文件状态信息。
- 4
- 模板文件不是常规文件。
- 5
- 读取模板文件时遇到错误。
- 6
- 内存分配失败(没有足够的可用内存)。
- 7
- 文件中没有与输入匹配的行。
- 8
- 输入规范无效。
环境
- DATEMSK
- 包含格式模式的文件。
- TZ, LC_TIME
- strptime(3)使用的变量。
属性
有关本节中使用的术语的说明，请参见attribute(7)。
| Interface | Attribute | Value |
| getdate() | Thread safety | MT-Unsafe race:getdate env locale |
| getdate_r() | Thread safety | MT-Safe env locale |
遵循规范
POSIX.1-2001，POSIX.1-2008。
备注
strptime(3)的POSIX.1规范包含使用％E或％O修饰符的转换规范，而对于getdate()没有给出此类规范。在glibc中，使用strptime(3)实现了getdate()，因此两者都支持完全相同的转换。
示例
下面的程序为其每个命令行参数调用getdate()，并且对于每个调用在返回的tm结构的字段中显示值。以下shell会话演示了程序的操作：
$ TFILE=$PWD/tfile
$ echo aq%Aaq > $TFILE # Full name of the day of the week
$ echo aq%Taq >> $TFILE # ISO date (YYYY-MM-DD)
$ echo aq%Faq >> $TFILE # Time (HH:MM:SS)
$ date
$ export DATEMSK=$TFILE
$ ./a.out Tuesday aq2009-12-28aq aq12:22:33aq
Sun Sep 7 06:03:36 CEST 2008
Call 1 ("Tuesday") succeeded:
tm_sec = 36
tm_min = 3
tm_hour = 6
tm_mday = 9
tm_mon = 8
tm_year = 108
tm_wday = 2
tm_yday = 252
tm_isdst = 1
Call 2 ("2009-12-28") succeeded:
tm_sec = 36
tm_min = 3
tm_hour = 6
tm_mday = 28
tm_mon = 11
tm_year = 109
tm_wday = 1
tm_yday = 361
tm_isdst = 0
Call 3 ("12:22:33") succeeded:
tm_sec = 33
tm_min = 22
tm_hour = 12
tm_mday = 7
tm_mon = 8
tm_year = 108
tm_wday = 0
tm_yday = 250
tm_isdst = 1
Program source
#define _GNU_SOURCE
#include <time.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{
struct tm *tmp;
int j;
for (j = 1; j < argc; j++) {
tmp = getdate(argv[j]);
if (tmp == NULL) {
printf("Call %d failed; getdate_err = %d\n",
j, getdate_err);
continue;
}
printf("Call %d (\"%s\") succeeded:\n", j, argv[j]);
printf(" tm_sec = %d\n", tmp->tm_sec);
printf(" tm_min = %d\n", tmp->tm_min);
printf(" tm_hour = %d\n", tmp->tm_hour);
printf(" tm_mday = %d\n", tmp->tm_mday);
printf(" tm_mon = %d\n", tmp->tm_mon);
printf(" tm_year = %d\n", tmp->tm_year);
printf(" tm_wday = %d\n", tmp->tm_wday);
printf(" tm_yday = %d\n", tmp->tm_yday);
printf(" tm_isdst = %d\n", tmp->tm_isdst);
}
exit(EXIT_SUCCESS);
}
出版信息
这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。
