ИМЯ¶

strftime - форматирование даты и времени

СИНТАКСИС¶

#include <time.h>

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

ОПИСАНИЕ¶

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

Формат представляет собой строку с null в конце, в которой могут содержаться специальные символьные последовательности, называемые определителями преобразования, каждая из которых состоит из символа '%' и ещё одного символа, называемого символом определителя преобразования. Все остальные символьные последовательности являются обычными символьными последовательностями.

Символы из обычных символьных последовательностей (включая байт null) копируются как есть из format в s. Однако, символы из определителей преобразования заменяются согласно списку, представленному ниже. В этом списке также показаны использованные поля из структуры tm.

%a

The abbreviated name of the day of the week according to the current locale. (Calculated from tm_wday.) (The specific names used in the current locale can be obtained by calling nl_langinfo(3) with ABDAY_{1–7} as an argument.)

%A

The full name of the day of the week according to the current locale. (Calculated from tm_wday.) (The specific names used in the current locale can be obtained by calling nl_langinfo(3) with DAY_{1–7} as an argument.)

%b

The abbreviated month name according to the current locale. (Calculated from tm_mon.) (The specific names used in the current locale can be obtained by calling nl_langinfo(3) with ABMON_{1–12} as an argument.)

%B

The full month name according to the current locale. (Calculated from tm_mon.) (The specific names used in the current locale can be obtained by calling nl_langinfo(3) with MON_{1–12} as an argument.)

%c

The preferred date and time representation for the current locale. (The specific format used in the current locale can be obtained by calling nl_langinfo(3) with D_T_FMT as an argument for the %c conversion specification, and with ERA_D_T_FMT for the %Ec conversion specification.) (In the POSIX locale this is equivalent to %a %b %e %H:%M:%S %Y.)

%C

The century number (year/100) as a 2-digit integer. (SU) (The %EC conversion specification corresponds to the name of the era.) (Calculated from tm_year.)

%d

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

%D

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

%e

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

%E

Modifier: use alternative ("era-based") format, see below. (SU)

%F

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

%G

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

%g

То же, что и %G, но без века, то есть двухразрядное число года (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); цифры предваряются пробелом (TZ, смотрите также %H, вычисляется из tm_hour).

%l

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

%m

Месяц в десятичной форме (от 01 до 12) (вычисляется из tm_mon).

%M

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

%n

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

%O

Modifier: use alternative numeric symbols, see below. (SU)

%p

Either "AM" or "PM" according to the given time value, or the corresponding strings for the current locale. Noon is treated as "PM" and midnight as "AM". (Calculated from tm_hour.) (The specific string representations used for "AM" and "PM" in the current locale can be obtained by calling nl_langinfo(3) with AM_STR and PM_STR, respectively.)

%P

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

%r

The time in a.m. or p.m. notation. (SU) (The specific format used in the current locale can be obtained by calling nl_langinfo(3) with T_FMT_AMPM as an argument.) (In the POSIX locale this is equivalent to %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. (SU, вычисляется из tm_wday).

%U

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

%V

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

%w

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

%W

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

%x

The preferred date representation for the current locale without the time. (The specific format used in the current locale can be obtained by calling nl_langinfo(3) with D_FMT as an argument for the %x conversion specification, and with ERA_D_FMT for the %Ex conversion specification.) (In the POSIX locale this is equivalent to %m/%d/%y.)

%X

The preferred time representation for the current locale without the date. (The specific format used in the current locale can be obtained by calling nl_langinfo(3) with T_FMT as an argument for the %X conversion specification, and with ERA_T_FMT for the %EX conversion specification.) (In the POSIX locale this is equivalent to %H:%M:%S.)

%y

The year as a decimal number without a century (range 00 to 99). (The %Ey conversion specification corresponds to the year since the beginning of the era denoted by the %EC conversion specification.) (Calculated from tm_year)

%Y

The year as a decimal number including the century. (The %EY conversion specification corresponds to the full alternative year representation.) (Calculated from tm_year)

%z

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

%Z

Название или сокращение часового пояса.

%+

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

%%

Символ '%'.

Some conversion specifications can be modified by preceding the conversion specifier character by the E or O modifier to indicate that an alternative format should be used. If the alternative format or specification does not exist for the current locale, the behavior will be as if the unmodified conversion specification were used. (SU) The Single UNIX Specification mentions %Ec, %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy, where the effect of the O modifier is to use alternative numeric symbols (say, roman numerals), and that of the E modifier is to use a locale-dependent alternative representation. The rules governing date representation with the E modifier can be obtained by supplying ERA as an argument to a nl_langinfo(3). One example of such alternative forms is the Japanese era calendar scheme in the ja_JP glibc locale.

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

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

Заметим, что возвращаемое значение 0 не всегда означает ошибку. Например, во многих локалях %p представляет собой пустую строку. Пустая строка format считается пустой строкой.

ОКРУЖЕНИЕ¶

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

АТРИБУТЫ¶

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

СООТВЕТСТВИЕ СТАНДАРТАМ¶

SVr4, C89, C99. Большинство этих определителей поддерживаются стандартом ANSI C (не помечен), Single UNIX Specification (помечен как SU), пакетом часовых поясов Олсона (Olson) (помечен как TZ) и glibc (помечен как GNU), кроме %+, которое не поддерживается в glibc2. С другой стороны, в 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().

Some buggy versions of gcc(1) complain about the use of %c: warning: `%c' yields only last 2 digits of year in some locales. Of course programmers are encouraged to use %c, as it gives the preferred date and time representation. One meets all kinds of strange obfuscations to circumvent this gcc(1) problem. A relatively clean one is to add an intermediate function

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 <time.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{


    char outstr[200];


    time_t t;


    struct tm *tmp;


    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 вернула 0");


        exit(EXIT_FAILURE);


    }


    printf("Строка результата: \"%s\"\n", outstr);


    exit(EXIT_SUCCESS);
}

СМ. ТАКЖЕ¶

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

ЗАМЕЧАНИЯ¶

Эта страница является частью проекта Linux man-pages версии 5.10. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу https://www.kernel.org/doc/man-pages/.

ПЕРЕВОД¶

Русский перевод этой страницы руководства был сделан Alexander Golubev <fatzer2@gmail.com>, Azamat Hackimov <azamat.hackimov@gmail.com>, Hotellook, Nikita <zxcvbnm3230@mail.ru>, Spiros Georgaras <sng@hellug.gr>, Vladislav <ivladislavefimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.