strftime
Руководство программиста Linux STRFTIME (3)
НАЗВАНИЕ
вверхуstrftime - формат даты и времени
ОБЗОР
наверх#include <time.h>
size_t strftime (char * s , size_t max , const char * format ,
const struct tm * tm );
ОПИСАНИЕ
наверхФункция strftime () форматирует время разбивки tm в соответствии с
в формат спецификации формата и помещает результат в
символьный массив s размером макс . Распределенная временная структура tm
определена в <time.h> . См. Также ctime (3) .
Спецификация формата представляет собой строку с завершающим нулем и может
содержат специальные последовательности символов, называемые спецификациями преобразования
, каждая из которых начинается с символа '%'
и завершается другим символом, известным как символ спецификатора преобразования
. Все остальные последовательности символов являются обычными последовательностями символов .
Символы обычных последовательностей символов (в том числе
нулевой байт) дословно копируются из формата в 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 Число столетий (год / 100) в виде 2-значного целого числа. (SU)
(Спецификация преобразования % EC соответствует названию
эпохи.) (Вычислено от tm_year .)
% d День месяца в виде десятичного числа (от 01 до 31).
(Рассчитано по tm_mday .)
% D Эквивалент % m /% d /% y . (Yecch - только для американцев.
Американцы должны отметить , что в других странах % d /% м /% г является
довольно часто. Это означает, что в международном контексте
этот формат неоднозначен и не должен использоваться.) (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_year , 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 Время в формате am или pm. (SU) (Конкретный
формат, используемый в текущей локали, можно получить с помощью
вызов nl_langinfo (3) с T_FMT_AMPM в качестве аргумента.)
(В локали POSIX это эквивалентно % I:% M:% S% p .)
% R Время в 24-часовом формате ( % H:% M ). (SU) Для версии
включая секунды, см. % T ниже.
% s Количество секунд с начала 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, где неделя 1 - это
первая неделя, в которой в новом году не менее 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 Год в виде десятичного числа, включая столетие. (
% EY преобразования соответствует полному
альтернативное представление года.) (Рассчитывается из
tm_year )
% г + ччммы или -hhmm цифровой временной зоны (то есть, час и
минутное смещение от UTC). (SU)
% Z Название или сокращение часового пояса.
% + Дата и время в формате date (1) . (TZ) (Не поддерживается
в glibc2.)
%% Буквальный символ "%".
Некоторые спецификации преобразования можно изменить, поставив перед
символ спецификатора преобразования с помощью модификатора E или O , чтобы указать
что следует использовать альтернативный формат. Если альтернатива
формат или спецификация не существует для текущей локали,
поведение будет таким, как если бы неизмененное преобразование
спецификации. (SU) Единая спецификация UNIX
упоминает % Ec , % EC , % Ex , % EX , % Ey , % EY , % Od , % Oe , % OH , % OI , % Om ,
% OM , % OS , % Ou , % OU , % OV , % Ow , % OW , % Oy , где влияние O
модификатор - использовать альтернативные числовые символы (например, римский
цифры), а модификатор E должен использовать локаль -
зависимое альтернативное представление. Правила, регулирующие дату
представление с модификатором E можно получить,
указав ERA в качестве аргумента для nl_langinfo (3) . Один из примеров такого
альтернативные формы - это календарная схема японской эры в
ja_JP язык glibc.
ВОЗВРАЩЕННАЯ СТОИМОСТЬ
наверхПри условии, что строка результата, включая завершающий нуль
byte, не превышает max байтов, strftime () возвращает количество
байты (исключая завершающий нулевой байт), помещенные в массив
с . Если длина результирующей строки (включая завершающую
нулевой байт) превысит максимальное количество байтов, тогда strftime () вернет 0 и
содержимое массива не определено.
Обратите внимание, что возвращаемое значение 0 не обязательно указывает на
ошибка. Например, во многих странах % p возвращает пустую строку.
Пустая строка формата также даст пустую строку.
ОКРУЖАЮЩАЯ СРЕДА
наверхИспользуются переменные среды TZ и LC_TIME .
АТРИБУТЫ
наверхДля объяснения терминов, используемых в этом разделе, см.
Атрибуты (7) .
┌───────────┬────────────────┬──────────────────────
│ Интерфейс │ Атрибут │ Значение │
├───────────┼────────────────┼──────────────────────
│ strftime () │ Безопасность потоков │ Локаль MT-Safe env │
└───────────┴────────────────┴──────────────────────
СООТВЕТСТВИЕ
верхуSVr4, C89, C99. Между набором
преобразований, приведенных в ANSI C (без пометок), приведенных в Single
Спецификация UNIX (помечена как SU), указанная в часовом поясе Олсона
пакет (помечен TZ), и те, что даны в glibc (помечены как GNU),
за исключением того, что % + не поддерживается в glibc2. С другой стороны
glibc2 имеет еще несколько расширений. POSIX.1 относится только к ANSI
C; POSIX.2 описывает под датой (1) несколько расширений, которые могут
применимо и к strftime (). Преобразование % F находится в C99 и
POSIX.1-2001.
В SUSv2 спецификатор % S допускал диапазон от 00 до 61, чтобы разрешить
для теоретической возможности минуты, которая включала
двойная високосная секунда (такой минуты еще не было).
ПРИМЕЧАНИЯ
вверхуНедельные даты ISO 8601
Значения доходности % G , % g и % V рассчитываются исходя из недельного года.
определяется стандартом ISO 8601. В этой системе недели начинаются
понедельник, и пронумерованы от 01, для первой недели, до 52
или 53, за последнюю неделю. Неделя 1 - это первая неделя, когда четыре или
в течение нового года попадает больше дней (или, как синоним, неделя 01:
первая неделя года, в которую входит четверг; или неделя
с 4 января). Когда три дня или меньше первого
календарная неделя нового года попадает в этот год, затем ISO
8601 недельная система считает эти дни частью 52 или 53 недели.
предыдущего года. Например, 1 января 2010 г. - пятница,
Это означает, что на 2010 год приходятся всего три дня этой календарной недели.
Таким образом, недельная система ISO 8601 считает эти дни
часть 53 недели ( % V ) 2009 года ( % G ); неделя 01 ISO 8601
2010 год начинается в понедельник, 4 января 2010 года. Аналогично, первый
два дня января 2011 г. считаются частью 52-й недели
2010 год.
Заметки Glibc
Glibc предоставляет некоторые расширения для спецификаций преобразования.
(Эти расширения не указаны в POSIX.1-2001, но некоторые
другие системы предоставляют аналогичные функции.) Между "%"
символ и символ спецификатора преобразования, необязательный
флаг и ширина поля могут быть указаны. (Они предшествуют E или O
модификаторы, если есть.)
Разрешены следующие символы флага:
_ (подчеркивание) Заполните числовую строку результата пробелами.
- (тире) Не дополнять числовую строку результата.
0 Заполните числовую строку результата нулями, даже если
символ спецификатора преобразования использует пробел с заполнением
дефолт.
^ Преобразование буквенных символов в строке результата в
верхний регистр.
# Поменять местами регистр результирующей строки. (Этот флаг работает только
с определенными символами спецификатора преобразования и
это действительно полезно только с % Z. )
Необязательный спецификатор десятичной ширины может следовать за (возможно
отсутствует) флаг. Если натуральный размер поля меньше, чем
этой ширины, то результирующая строка дополняется (слева) до
указанная ширина.
ОШИБКИ
наверхЕсли выходная строка будет превышать макс байт, ERRNO это не установлено.
Это делает невозможным отличить этот случай ошибки от
случаи, когда строка формата законно создает нулевую длину
строка вывода. 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)
{
вернуть 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"
Пример программы
Приведенную ниже программу можно использовать для экспериментов с strftime ().
Некоторые примеры результирующей строки, созданной glibc
реализация strftime () выглядит следующим образом:
$ ./a.out "% m"
Строка результата - «11»
$ ./a.out "% 5m"
Строка результата - «00011»
$ ./a.out "% _5m"
Строка результата - «11»
