НАИМЕНОВАНИЕ¶

strftime - преобразует дату и время в форматированную строку

БИБЛИОТЕКА¶

Стандартная библиотека языка Си (libc, -lc)

СИНОПСИС¶

#include <time.h>

size_t strftime(size_t max;
                char s[restrict max], size_t max,
                const char *restrict format,
                const struct tm *restrict tm);

size_t strftime_l(size_t max;
                char s[restrict max], size_t max,
                const char *restrict format,
                const struct tm *restrict tm,
                locale_t locale);

ОПИСАНИЕ¶

Функция strftime() форматирует календарное (broken-down time), разбитое на компоненты время tm, согласно спецификации формата format и помещает результат в символьный массив s размером не более max байт (включая завершающий байт null). Структура tm, описывающая календарное время, подробно определена в <time.h>. См. также ctime(3).

Формат представляет собой строку с завершающим байтом null (null‑terminated), которая может содержать несколько специальных последовательностей символов, называемых "спецификациями преобразования" (conversion specifications). Каждая такая последовательность состоит из символа '%' и "символа‑спецификатора преобразования" (conversion specifier character). Все прочие символы являются "обычными последовательностями символов" (ordinary character sequences).

Примечание переводчика. В интернет‑статьях для краткости используют сокращения: «спецификации» или «спецификаторы» вместо «спецификации преобразования»; «определитель спецификации» или «определитель спецификатора» вместо «символ‑спецификатор преобразования».

Символы обычных последовательностей (включая завершающий байт null), копируются из format в массив s без изменений, как есть. А символы, используемые в "спецификации преобразования", заменяются согласно приведённому ниже списку; в нём также указаны поля, используемые в структуре времени tm.

%a

Сокращённое название дня недели в зависимости от текущей локали (вычисляется из tm_wday). (Конкретные названия, используемые в текущей локали, можно получить, вызвав nl_langinfo(3) с аргументом ABDAY_{1–7}.)

%A

Полное название дня недели в зависимости от текущей локали (вычисляется из tm_wday). (Конкретные названия, используемые в текущей локали, можно получить, вызвав nl_langinfo(3) с аргументом DAY_{1–7}.)

%b

Сокращённое название месяца в зависимости от текущей локали (вычисляется из tm_mon). (Конкретные названия, используемые в текущей локали, можно получить, вызвав nl_langinfo(3) с аргументом ABMON_{1–12}.)

%B

Полное название месяца в зависимости от текущей локали (вычисляется из tm_mon). (Конкретные названия, используемые в текущей локали, можно получить, вызвав nl_langinfo(3) с аргументом MON_{1–12}.)

%c

Предпочтительное представление даты и времени для текущей локали. (Конкретный формат, используемый в текущей локали, можно получить, вызвав nl_langinfo(3) с аргументом D_T_FMT для спецификации %c и с аргументом ERA_D_T_FMT для спецификации %Ec.) (В стандарте POSIX это эквивалентно %a %b %e %H:%M:%S %Y.)

%C

Век в виде 2-х значного числа (год/100). (SU) (Спецификация %EC указывает эру.) (Вычисляется из tm_year.)

%d

День месяца в виде десятичного числа (от 01 до 31). (Вычисляется из tm_mday.)

%D

Эквивалентно %m/%d/%y. (Только для американцев, в других странах довольно широко распространён формат %d/%m/%y. Это означает, что в международном контексте этот формат неоднозначен и его не следует использовать.) (SU)

%e

То же, что и %d, день месяца в виде десятичного числа, но вместо начального нуля ставится пробел. (SU) (Вычисляется из tm_mday.)

%E

Модификатор: указывает использовать альтернативный формат (на основе эры); см. далее. (SU)

%F

Эквивалентно %Y-%m-%d (формат даты по стандарту ISO 8601). (C99)

%G

Год на основе недель, с указанием века в виде десятичного числа, по стандарту ISO 8601 (см. ПРИМЕЧАНИЯ). Год как 4-х значное число, соответствующий номеру недели согласно ISO (см. %V). Он имеет тот же формат и значение, что и %Y, за исключением того, что номер недели согласно ISO относится к предыдущему или следующему году, а в этом случае отображается прошедший год. (TZ) (Вычисляется из tm_year, tm_yday и tm_wday.)

%g

То же, что и %G, но без века, то есть 2-х значное число года (00–99). (TZ) (Вычисляется из tm_wday, tm_yday и tm_wday.)

%h

Эквивалентно %b. (SU)

%H

Час как десятичное число в 24-часовом формате (от 00 до 23) (вычисляется из tm_hour).

%I

Час как десятичное число в 12-часовом формате (от 01 до 12) (вычисляется из tm_hour).

%j

День года в виде десятичного числа (от 001 до 366) (вычисляется из tm_yday).

%k

Час (в 24-часовом формате) как десятичное число (от 0 до 23); перед однозначными числами ставится пробел (см. также %H) (вычисляется из tm_hour). (TZ)

%l

Час (в 12-часовом формате) как десятичное число (от 1 до 12); перед однозначными числами ставится пробел (см. также %I) (вычисляется из tm_hour). (TZ)

%m

Месяц в виде десятичного числа (от 01 до 12) (вычисляется из tm_mon).

%M

Минута в виде десятичного числа (от 00 до 59) (вычисляется из tm_min).

%n

Символ новой строки. (SU)

%O

Модификатор: указывает использовать альтернативные цифровые символы; см. далее. (SU)

%p

В зависимости от заданного значения времени используется либо "AM", либо "PM", или соответствующая замена для текущей локали. Полдень обозначается как "PM", а полночь как "AM" (вычисляется из tm_hour). (Конкретные представления, используемые для "AM" и "PM" в текущей локали, можно получить, вызвав nl_langinfo(3) с аргументами AM_STR или PM_STR соответственно.)

%P

Аналогично %p, но в нижнем регистре: "am" или "pm", либо соответствующая замена для текущей локали (вычисляется из tm_hour). (GNU)

%r

Время в формате a.m. или p.m. (SU) (Конкретный формат, используемый в текущей локали, можно получить, вызвав nl_langinfo(3) с аргументом T_FMT_AMPM.) (В стандарте POSIX это эквивалентно %I:%M:%S %p.)

%R

Время в 24-часовом формате (%H:%M). (SU) Вариант с указанием секунд см. далее в спецификации %T.

%s

Количество секунд, прошедших с начала эпохи UNIX-систем, 1970-01-01 00:00:00 +0000 (UTC). (TZ) (Вычисляется из mktime(tm).)

%S

Секунда как десятичное число (от 00 до 60). (До 60 включительно позволяет учитывать високосные секунды.) (Вычисляется из tm_sec.)

%t

Символ табуляции. (SU)

%T

Время в 24-часовом формате с указанием секунд (%H:%M:%S). (SU)

%u

День недели в виде десятичного числа от 1 до 7, понедельник это 1. См. также %w. (Вычисляется из tm_wday.) (SU)

%U

Номер недели текущего года в виде десятичного числа от 00 до 53, начиная с первого воскресенья как первого дня недели 01. См. также %V и %W. (Вычисляется из tm_yday и tm_wday.)

%V

Номер недели текущего года по стандарту ISO 8601 (см. ПРИМЕЧАНИЯ) в виде десятичного числа от 01 до 53, где 01 — это первая неделя, содержащая не менее 4-х дней в новом году. См. также %U и %W. (Вычисляется из tm_year, tm_yday и tm_wday.) (SU)

%w

День недели в виде десятичного числа от 0 до 6, понедельник это 0. См. также %u. (Вычисляется из tm_wday.)

%W

Номер недели текущего года в виде десятичного числа от 00 до 53, начиная с первого понедельника как первого дня недели 01 (вычисляется из tm_yday и tm_wday).

%x

Предпочтительное представление даты для текущей локали без времени. (Конкретный формат, используемый в текущей локали, можно получить, вызвав nl_langinfo(3) с аргументом D_FMT для спецификации %x и с аргументом ERA_D_FMT для спецификации %Ex.) (В стандарте POSIX это эквивалентно %m/%d/%y.)

%X

Предпочтительное представление времени для текущей локали без даты. (Конкретный формат, используемый в текущей локали, можно получить, вызвав nl_langinfo(3) с аргументом T_FMT для спецификации %X и с аргументом ERA_T_FMT для спецификации %EX.) (В стандарте POSIX это эквивалентно %H:%M:%S.)

%y

Год в виде десятичного числа без указания века (от 00 до 99). (Спецификация %Ey указывает год с начала эры, которая задаётся спецификацией %EC.) (Вычисляется из tm_year)

%Y

Год с указанием века в виде 4-х значного числа. (Спецификация %EY соответствует альтернативному представлению полного года.) (Вычисляется из tm_year)

%z

Часовой пояс +hhmm или -hhmm (указывает смещение часов и минут относительно UTC). (SU)

%Z

Название часового пояса или его аббревиатура.

%+

Дата и время в формате date(1). (TZ) (Не поддерживается в glibc2)

%%

Символ '%'.

Некоторые "спецификации преобразования" можно изменить, добавив перед "символом-спецификатора преобразования" модификатор E или O, которые указывают, что следует использовать альтернативный формат. Если альтернативный формат или "спецификация преобразования" не существуют для текущей локали, преобразование будет выполнено так, как будто использовалась исходная, неизменённая "спецификация преобразования". (SU) В Single UNIX Specification упомянуты спецификации преобразования %Ec, %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy, где модификатор O означает использование альтернативных цифровых символов (например, римских цифр), а модификатор E означает использование альтернативного представления, зависящего от текущей локали. Правила, регулирующие представление даты с помощью модификатора E, можно получить, вызвав nl_langinfo(3) с аргументом ERA. Одним из примеров таких альтернативных форм является схема календаря японской эры в языковой локали ja_JP glibc.

Функция strftime_l() эквивалентна strftime(), за исключением того, что использует указанную локаль locale вместо текущей. Поведение не определено, если locale недопустима или LC_GLOBAL_LOCALE.

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

Если длина строки результата, включая завершающий байт null (null‑terminated), не превышает max количество байт, то функция strftime() вернёт количество байт (за исключением завершающего байта null), помещённых в массив s. Если длина строки результата (включая завершающий байт null) превысит max количество байт, то функция strftime() вернёт "0", а содержимое массива будет не определено.

Обратите внимание, возвращаемое значение "0" не всегда означает ошибку. Например, во многих локалях спецификация %p возвращает пустую строку (так как в них отсутствует понятие "AM" и "PM"). Пустая строка format также вернёт пустую строку.

ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ¶

Используются переменные окружения TZ и LC_TIME.

АТРИБУТЫ¶

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

СТАНДАРТЫ¶

strftime()

C11, POSIX.1-2008.

strftime_l()

POSIX.1-2008.

ИСТОРИЯ¶

strftime()

SVr4, C89.

strftime_l()

POSIX.1-2008.

Большинство спецификаций этого формата поддерживаются следующими стандартами и пакетами: ANSI C (без пометки), Single UNIX Specification (с пометкой SU), пакет часовых поясов Олсона (с пометкой TZ) и glibc (с пометкой GNU). Версия glibc2 имеет несколько дополнительных расширений, но не поддерживает спецификацию %+. POSIX.1 ссылается только на ANSI C; POSIX.2 описывает несколько расширений в date(1), которые могут быть применимы к функции strftime(). Спецификация %F присутствует в стандартах C99 и POSIX.1‑2001.

В стандарте SUSv2 спецификация %S позволяет использовать диапазон от 00 до 61, что даёт теоретическую возможность включать в минуту двойную високосную секунду (на практике такой минуты ещё не было).

ПРИМЕЧАНИЯ¶

ПРОГРАММНЫЕ ОШИБКИ¶

Если строка результата превысит max допустимое количество байт, код ошибки errno НЕ устанавливается. Это не позволяет отличить такую ошибку от случаев, когда format возвращает корректный результат в виде строки нулевой длины. Стандарт POSIX.1‑2001 НЕ определяет никаких параметров errno для функции strftime().

Некоторые версии gcc(1) с программными ошибками, при использовании спецификации %c предупреждают: warning: в некоторых локалях `%c' выдаёт только последние 2 цифры года. Тем не менее, программистам рекомендуется использовать %c, так как она позволяет получить предпочтительное представление даты и времени. Встречаются всевозможные странные способы обхода этой проблемы в gcc(1). Относительно простой вариант — добавить промежуточную функцию:

size_t
my_strftime(char *s, size_t max, const char *fmt,


            const struct tm *tm)
{


    return strftime(s, max, fmt, tm);
}

В настоящее время gcc(1) имеет опцию -Wno-format-y2k, которая отключает проверку формата, связанную с возможным двузначным обозначением года, поэтому описанный выше обходной способ больше не требуется.

ПРИМЕРЫ¶

Формат даты по стандарту RFC 2822 (в английской локали с %a и %b)

"%a, %d %b %Y %T %z"

Формат даты по стандарту RFC 822 (в английской локали с %a и %b)

"%a, %d %b %y %T %z"

$ ./a.out '%m'
Строка результата: "11"
$ ./a.out '%5m'
Строка результата: "00011"
$ ./a.out '%_5m'
Строка результата: "   11"

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


    char outstr[200];


    time_t t;


    struct tm *tmp;


    if (argc != 2) {


        fprintf(stderr, "Usage: %s: <format-string>\n", argv[0]);


        exit(EXIT_FAILURE);


    }


    t = time(NULL);


    tmp = localtime(&t);


    if (tmp == NULL) {


        perror("localtime");


        exit(EXIT_FAILURE);


    }


    if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {


        fprintf(stderr, "strftime returned 0");


        exit(EXIT_FAILURE);


    }


    printf("Result string is \"%s\"\n", outstr);


    exit(EXIT_SUCCESS);
}

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

date(1), time(2), ctime(3), nl_langinfo(3), setlocale(3), sprintf(3), strptime(3)

ПЕРЕВОД¶

Русский перевод этой страницы руководства разработал(и) algri14 <aliger14@mail.ru>

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

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