ИМЯ¶

getdate, getdate_r - разделяет строку дата+время на отдельные части

LIBRARY¶

Standard C library (libc, -lc)

СИНТАКСИС¶

#include <time.h>

struct tm *getdate(const char *string);

extern int getdate_err;

int getdate_r(const char *restrict string, struct tm *restrict res);

getdate():

    _XOPEN_SOURCE >= 500

getdate_r():

    _GNU_SOURCE

ОПИСАНИЕ¶

Функция getdate() преобразует строковое представление даты и времени из буфера, на который указывает string в разделённое на компоненты время. Разделённое время сохраняется в структуре tm и указатель на неё возвращается в качестве результата. Структура tm находится в статической области и, таким образом, будет перезаписана при следующих вызовах getdate().

В отличие от strptime(3), (которая имеет аргумент format), функция getdate() использует форматы, содержащиеся в файле, полный путь к которому содержится в переменной окружения DATEMSK. Первая строка файла, которая совпадает с полученной входной строкой, будет использована для преобразования.

Проверка на совпадение производится без учета регистра. Лишние пробелы как в шаблоне, так и в преобразуемой строке игнорируются.

Описатели преобразования, которые могут быть указаны в шаблоне, соответствуют используемым в strptime(3). Кроме того, понимается ещё один описатель POSIX.1-2001:

%Z

Имя часового пояса. Не реализован в glibc.

Если указан %Z, то структура с разделённым временем инициализируется значениями в соответствие с текущим временем указанного часового пояса. В противном случае, структура инициализируется разделённым временем в соответствии с текущим местным временем (как при вызове localtime(3)).

Если указан только день недели, то берётся ближайший день или завтрашний.

Если указан только месяц (и не указан год), то берётся первый месяц, эквивалентный заданному, или следующий. Если не указан день, то это будет первый день месяца.

When no hour, minute, and second are given, the current hour, minute, and second are taken.

Если не указана дата, но мы знаем час, то будет взят первый час, равный заданному, начиная с текущего часа.

Функция getdate_r() является расширением GNU и предоставляет реентерабельную версию getdate(). Она не использует глобальную переменную для сообщения об ошибках и статический буфер для возвращаемого разделённого времени, она возвращает ошибки как результат функции, а разделённое время возвращается в выделенном вызывающем буфере, на который указывает аргумент res.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ¶

При успешном выполнении getdate() возвращает указатель на struct tm. В противном случае возвращается NULL, а глобальная переменная getdate_err содержит один из номеров ошибок, перечисленных ниже. Изменения errno не определены.

При успешном выполнении getdate_r() возвращает 0; при ошибке возвращается одно из значений ошибки, перечисленных далее.

ОШИБКИ¶

Следующие ошибки возвращаются в getdate_err (для getdate()) или как результат функции (для getdate_r()):

1

Переменная окружения DATEMSK не определена или её значение — пустая строка.

2

Файл шаблонов, заданный DATEMSK, не может быть открыт на чтение.

3

Не удалось получить информацию о состоянии файла.

4

Файл шаблонов не является обычным файлом.

5

Произошла ошибка при чтении файла шаблонов.

6

Не удалось выделить память (недостаточно памяти).

7

В файле нет строки, совпавшей с входной.

8

Неверный формат входной строки.

СРЕДА ОКРУЖЕНИЯ¶

DATEMSK

Файл, содержащий шаблоны форматирования.

TZ

LC_TIME

Переменные, используемые strptime(3).

АТРИБУТЫ¶

Описание терминов данного раздела смотрите в attributes(7).

ВЕРСИИ¶

В описании POSIX.1 для strptime(3) содержится преобразуемые описатели использующие модификатор %E или %O, хотя эти описатели не указаны для getdate(). В glibc, getdate() реализована посредством strptime(3), таким образом поддерживаются все возможные описатели.

СТАНДАРТЫ¶

POSIX.1-2008.

ИСТОРИЯ¶

POSIX.1-2001.

ПРИМЕРЫ¶

Программа, представленная далее, вызывает getdate() для каждого своего аргумента командной строки и при каждом вызове печатаются значения полей полученной структуры tm. Следующий сеанс показывает работу программы:

$ TFILE=$PWD/tfile
$ echo '%A' > $TFILE       # Full name of the day of the week
$ echo '%T' >> $TFILE      # Time (HH:MM:SS)
$ echo '%F' >> $TFILE      # ISO date (YYYY-MM-DD)
$ date
$ export DATEMSK=$TFILE
$ ./a.out Tuesday '2009-12-28' '12:22:33'
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

#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
int
main(int argc, char *argv[])
{


    struct tm *tmp;


    for (size_t j = 1; j < argc; j++) {


        tmp = getdate(argv[j]);


        if (tmp == NULL) {


            printf("Call %zu failed; getdate_err = %d\n",


                   j, getdate_err);


            continue;


        }


        printf("Call %zu (\"%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);
}

СМОТРИТЕ ТАКЖЕ¶

time(2), localtime(3), setlocale(3), strftime(3), strptime(3)

ПЕРЕВОД¶

Русский перевод этой страницы руководства разработал Azamat Hackimov <azamat.hackimov@gmail.com>, Dmitry Bolkhovskikh <d20052005@yandex.ru>, Vladislav <ivladislavefimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику по его адресу электронной почты или по адресу списка рассылки русских переводчиков.