strftime(3) - wariua/manpages-ko GitHub Wiki

strftime - 날짜 및 시간 서식화

#include <time.h>

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

strftime() 함수는 분할 시간 tm을 서식 format에 따라 변환해서 그 결과를 크기 max인 문자 배열 s에 집어넣는다. 분할 시간 구조체 tm은 <time.h>에 정의돼 있다. ctime(3)도 참고.

서식은 널 종료 문자열이며 변환 지정자라는 특별한 문자 열을 포함할 수 있다. 각 변환 지정자는 '%' 문자로 시작해서 변환 지정 문자라는 어떤 다른 문자로 끝난다. 그 외의 모든 문자 열은 일반 문자 열이다.

일반 문자 열의 문자들(널 바이트 포함)은 format에서 s로 그대로 복사한다. 하지만 변환 지정자의 문자들은 아래 목록에 나온 대로 바꿔서 넣는다. 이 목록에는 tm 구조체의 이용 필드(들)도 적혀 있다.

몇몇 변환 지정자들에선 변환 지정 문자 앞에 E나 O 수식자를 붙여서 대체 형식을 써야 한다고 표시할 수 있다. 현재 로캘에서 대체 형식 내지 지정자가 존재하지 않는 경우에는 수식 없이 변환 지정자를 쓴 것처럼 동작하게 된다. (SU) 단일 유닉스 규격에서는 %Ec, %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy를 언급하는데, O 수식자의 효과는 대체 숫자 심볼(가령 로마 숫자)을 쓰는 것이고 E 수식자의 효과는 로캘별 대체 표현을 쓰는 것이다.

결과 문자열이 종료 널 바이트를 포함해서 max 바이트를 초과하지 않는 경우에는 배열 s에 집어넣은 (종료 널 바이트를 뺀) 바이트 수를 strftime()이 반환한다. 결과 문자열의 (종료 널 바이트 포함) 길이가 max 바이트를 넘게 될 경우에는 strftime()이 0을 반환하며, 이때 배열의 내용물은 규정돼 있지 않다.

참고로 반환 값 0이 반드시 오류를 나타내는 건 아니다. 예를 들어 여러 로캘에서 %p는 빈 문자열이 된다. format 문자열이 비어 있어도 마찬가지로 빈 문자열이 나온다.

환경 변수 TZ 및 LC_TIME을 쓴다.

이 절에서 사용하는 용어들에 대한 설명은 attributes(7)를 보라.

SVr4, C89, C99. ANSI C에 있는 변환(표시 없음), 단일 유닉스 규격에 있는 변환(SU 표시), Olson의 timezone 패키지에서 제공하는 변환(TZ 표시), glibc에서 제공하는 변환(GNU 표시) 사이에는 엄격한 포함 관계가 있다. 단 glibc2에서는 %+를 지원하지 않는다. 한편으로 glibc2에는 다른 여러 확장이 있다. POSIX.1에서는 ANSI C만을 참조한다. 하지만 POSIX.2에서는 date(1) 하에서 strftime()에도 적용될 수 있을 여러 확장들을 기술한다. %F 변환은 C99 및 POSIX.1-2001에 있다.

SUSv2에서는 %S 변환자의 허용 범위가 00에서 61까지이다. 이는 1분에 윤초가 두 번 포함될 수 있는 이론적 가능성에 대비하기 위한 것이다. (지금까지 그런 경우는 한 번도 없었다.)

%G, %g, %V는 ISO 8601 표준에 정의된 주 기준 연도로부터 계산한 값들을 내놓는다. 이 체계에서는 월요일부터 한 주가 시작하며, 첫 번째 주에 01번을 붙이고 마지막 주는 52번이나 53번이 된다. 1번 주는 4일 이상이 새해에 속하는 첫 번째 주이다. (즉 01번 주는 목요일을 포함한 그해 첫째 주이기도 하고, 1월 4일을 포함한 주이기도 하다.) 새해의 달력 첫 번째 주에서 3일 이하가 그해에 속할 때 ISO 8601 주 기반 체계에서는 그 날들을 전해의 53번 주로 계산한다. 예를 들어 2010년 1월 1일은 금요일이고, 그래서 그 달력 주의 3일만 2010년에 속한다. 따라서 ISO 8601 주 기반 체계에서는 그 날들을 2009년(%G)의 53번 주(%V)에 포함되는 걸로 본다. 즉 ISO 8601 기준 2010년의 01번 주는 2010년 1월 4일 월요일에 시작한다.

glibc에서는 변환 지정자 확장을 몇 가지 제공한다. (이 확장들은 POSIX.1-2001에 명세돼 있지 않지만 몇몇 다른 시스템에서도 비슷한 기능을 제공한다.) '%' 문자와 변환 지정 문자 사이에 선택적으로 플래그와 필드 폭을 지정할 수 있다. (E 및 O 수식자가 있는 경우에는 그 앞에 온다.)

다음 플래그 문자들을 허용한다.

십진수로 된 폭 지정자가 (존재하지 않을 수도 있는) 플래그 다음에 선택적으로 올 수 있다. 필드의 원래 크기가 그 폭보다 작으면 결과 문자열 왼쪽을 채워서 지정한 폭으로 맞춘다.

출력 문자열이 max 바이트를 넘게 될 경우에 errno를 설정하지 않는다. 이 때문에 그 오류 경우와 format 문자열이 적법하게 길이 0인 출력 문자열을 만들어 내는 경우를 구별할 수 없다. POSIX.1-2001에서는 strftime()에 대해 어떤 errno 설정도 명세하고 있지 않다.

일부 버그 있는 gcc(1) 버전들에서는 %c 사용 시 warning: `%c' yields only last 2 digits of year in some locales라고 나온다. 물론 프로그래머들은 많이 쓰는 날짜 및 시간 표현이 나오는 %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"

아래 프로그램으로 strftime() 동작을 실험해 볼 수 있다.

다음은 glibc의 strftime() 구현이 내놓는 결과 문자열 예시이다.

$ ./a.out '%m'
Result string is "11"
$ ./a.out '%5m'
Result string is "00011"
$ ./a.out '%_5m'
Result string is "   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 returned 0");
        exit(EXIT_FAILURE);
    }

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

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

2019-03-06