<time.h>

No cabeçalho <time.h> estão localizadas as funções, variáveis e macros para manipulação de unidades de tempo, como ano, mês, dia, hora, minutos e segundos. A partir das funções fornecidas é possível obter a data e o horário do sistema, calcular intervalos de tempo, entre outras funcionalidades.

É um cabeçalho muito poderoso para o controle da execução do programa e para a manipulação de ações que têm datas e horas como referência.

Variáveis e Tipos

  • clock_t: Variável que tem por finalidade armazenar valores relacionados a pulsos de clock do processador, como o valor fornecido pela função clock().
  • time_t: Variável que armazena os valores numéricos brutos relacionados à data e hora do sistema (frequentemente em segundos desde a Epoch). Várias funções recebem ou retornam este tipo.
  • size_t: Variável utilizada para representar o tamanho que uma determinada variável e/ou tipo ocupa na memória.
  • struct tm: Estrutura de dados que armazena valores de calendário (data e hora desmembrados), contendo 9 variáveis inteiras (segundos, minutos, horas, dia do mês, mês, ano, dia da semana, dia do ano e horário de verão).

Macros

  • CLOCKS_PER_SEC: Macro responsável por armazenar a quantidade de pulsos por segundo do processador da máquina na qual o programa está sendo executado. É usada para converter o retorno de clock() em segundos.
  • NULL: Ponteiro utilizado para indicar que uma referência não aponta para posição de memória alguma.

Funções

clock() time() difftime() mktime() asctime() ctime() gmtime() localtime() strftime()

clock_t clock(void)

Retorna uma aproximação do tempo de processador (CPU) utilizado pelo programa desde o início de sua execução.

Recebe: void (não recebe parâmetros).

Retorna: A quantidade de pulsos de clock (tipo clock_t) consumidos. Se o tempo de processador não estiver disponível ou seu valor não puder ser representado, a função retorna -1.

Dica: Para converter o retorno em segundos, divida o valor pela macro CLOCKS_PER_SEC.

Exemplo

// EXEMPLO CLOCK()
#include <stdio.h>
#include <time.h>

int main() { 
    // O tipo clock_t é geralmente um long int
    printf("Pulsos de clock até o momento: %ld\n", (long)clock()); 
    printf("printf Aleatório\n"); 
    printf("Mais um teste da quantidade de pulsos de clock: %ld\n", (long)clock());

    return 0; 
}

Saída esperada

Pulsos de clock até o momento: 1701 
printf Aleatório 
Mais um teste da quantidade de pulsos de clock: 1797

time_t time(time_t *ponteiro_tempo)

Obtém o tempo atual do sistema, representado como o número de segundos decorridos desde a Epoch (00:00:00 UTC de 1º de janeiro de 1970).

Recebe: Um ponteiro para uma variável do tipo time_t onde o valor será armazenado. Se não desejar armazenar em uma variável externa, pode-se passar NULL.

Retorna: O tempo atual no formato time_t. Em caso de erro, retorna (time_t)-1.

Exemplo

// EXEMPLO TIME()
#include <stdio.h>
#include <time.h>

int main() { 
    // Opção 1: Retornando o valor diretamente e passando NULL
    time_t tempo = time(NULL); 
    // ctime converte time_t para uma string legível
    printf("%s", ctime(&tempo));

    // Opção 2: Passando o endereço da variável para a função preencher
    time(&tempo); 
    printf("Outro teste: %s", ctime(&tempo));

    return 0; 
}

Saída esperada

Thu May 27 20:20:01 2021 
Outro teste: Thu May 27 20:20:01 2021

double difftime(time_t tempo, time_t tempo0)

Calcula a diferença em segundos entre dois instantes de tempo.

Recebe: Dois valores do tipo time_t (o tempo final e o tempo inicial).

Retorna: A diferença (tempo - tempo0) expressa em segundos como um valor de ponto flutuante (double).

Exemplo

// EXEMPLO DIFFTIME()
#include <stdio.h>
#include <time.h>

int main() { 
    struct tm t_fim = {0}, t_ini = {0};

    // Configurando Tempo Final (ex: 84 segundos no componente tm_sec)
    t_fim.tm_sec = 84; 
    t_fim.tm_mday = 1; t_fim.tm_mon = 0; t_fim.tm_year = 100; // Jan 1, 2000

    // Configurando Tempo Inicial (ex: 42 segundos no componente tm_sec)
    t_ini.tm_sec = 42; 
    t_ini.tm_mday = 1; t_ini.tm_mon = 0; t_ini.tm_year = 100; // Jan 1, 2000

    // mktime converte struct tm para time_t
    double diferenca = difftime(mktime(&t_fim), mktime(&t_ini));

    printf("Diferença: %lf segundos\n", diferenca);

    return 0; 
}

Saída esperada

Diferença: 42.000000 segundos

time_t mktime(struct tm *tempo)

Converte uma estrutura de tempo desmembrada (struct tm) em um valor de tempo de calendário (time_t).

Recebe: Um ponteiro para uma struct tm contendo os componentes de data e hora.

Retorna: O valor time_t correspondente. Se a conversão falhar, retorna (time_t)-1.

Normalização: Esta função ajusta automaticamente valores fora do intervalo (ex: se você passar 70 segundos, ela converterá para 1 minuto e 10 segundos) e preenche os campos tm_wday (dia da semana) e tm_yday (dia do ano) na estrutura original.

Exemplo

// EXEMPLO MKTIME()
#include <stdio.h>
#include <time.h>

int main() { 
    struct tm tempo = {0};

    tempo.tm_sec = 42; 
    tempo.tm_min = 59; 
    tempo.tm_hour = 23; 
    tempo.tm_mday = 25; 
    // Mês é de 0 a 11. 12 fará o mktime normalizar para Janeiro do próximo ano.
    tempo.tm_mon = 12; 
    // O ano é contado a partir de 1900
    tempo.tm_year = 10191 - 1900; 

    time_t tempoConvertido = mktime(&tempo);

    if (tempoConvertido != (time_t)-1) {
        printf("%s", ctime(&tempoConvertido));
    }

    return 0; 
}

Saída esperada

Wed Jan 25 23:59:42 10192

char *asctime(const struct tm *tp)

Converte os valores armazenados em uma struct tm para uma string legível pelo ser humano.

Recebe: Um ponteiro para uma estrutura struct tm constante.

Retorna: Um ponteiro para uma string estática formatada como: "Dia Mês DD HH:MM:SS AAAA\n".

Atenção: A string de retorno é alocada estaticamente e compartilhada por asctime e ctime. Cada chamada a essas funções sobrescreve o conteúdo do buffer anterior.

Exemplo

// EXEMPLO ASCTIME()
#include <stdio.h>
#include <time.h>

int main() { 
    struct tm tempo = {0};
    
    tempo.tm_sec = 42; 
    tempo.tm_min = 59; 
    tempo.tm_hour = 23; 
    tempo.tm_mday = 25; 
    tempo.tm_mon = 11;             // Dezembro (índice 0-11)
    tempo.tm_year = 10191 - 1900;  // Anos desde 1900
    tempo.tm_wday = 3;             // 0 = Domingo, 3 = Quarta (Wed)

    // Converte a struct diretamente para string
    printf("%s", asctime(&tempo));

    return 0; 
}

Saída esperada

Wed Dec 25 23:59:42 10191

char *ctime(const time_t *timer)

Converte um valor de tempo de calendário (time_t) em uma string legível, levando em conta as configurações de fuso horário local.

Recebe: Um ponteiro para uma variável time_t contendo o tempo a ser convertido.

Retorna: Um ponteiro para uma string formatada (idêntica ao formato da asctime). Esta função é equivalente a chamar asctime(localtime(timer)).

Nota: Assim como a asctime, o retorno aponta para um buffer estático que será sobrescrito em chamadas subsequentes.

Exemplo

// EXEMPLO CTIME()
#include <stdio.h>
#include <time.h>

int main() { 
    time_t tempo; 
    
    // Obtém o tempo atual do sistema
    time(&tempo);

    // Converte o valor numérico diretamente para string legível
    printf("%s", ctime(&tempo));

    return 0; 
}

Saída esperada

Thu May 27 21:14:34 2021

struct tm *gmtime(const time_t *timer)

Converte um valor de tempo de calendário (time_t) em uma estrutura de tempo desmembrada (struct tm), expressa como Tempo Universal Coordenado (UTC/GMT).

Recebe: Um ponteiro para uma variável time_t contendo o tempo a ser convertido.

Retorna: Um ponteiro para uma estrutura struct tm preenchida com os valores de tempo universal. Em caso de erro, retorna NULL.

Atenção: O ponteiro retornado aponta para uma estrutura interna estática. Chamadas subsequentes a gmtime ou localtime sobrescreverão os dados dessa estrutura.

Exemplo

// EXEMPLO GMTIME()
#include <stdio.h>
#include <time.h>

// Fusos horários em relação ao UTC
#define BRT -3 
#define JST 9

int main() { 
    time_t tempo; 
    time(&tempo);

    // Converte para UTC (Meridiano de Greenwich)
    struct tm *tempo_utc = gmtime(&tempo);

    // Exibe horários calculados manualmente a partir do UTC
    printf("Horário no Japão: %02d:%02d:%02d\n", 
           (tempo_utc->tm_hour + JST) % 24, tempo_utc->tm_min, tempo_utc->tm_sec);
           
    printf("Horário no Brasil: %02d:%02d:%02d\n", 
           (tempo_utc->tm_hour + BRT + 24) % 24, tempo_utc->tm_min, tempo_utc->tm_sec);

    return 0; 
}

Saída esperada

Horário no Japão: 13:14:07 
Horário no Brasil: 01:14:07

struct tm *localtime(const time_t *timer)

Converte um valor de tempo de calendário (time_t) em uma estrutura de tempo desmembrada (struct tm), ajustada automaticamente para o fuso horário local do sistema.

Recebe: Um ponteiro para uma variável time_t (geralmente obtida via função time()).

Retorna: Um ponteiro para uma estrutura struct tm preenchida com os componentes de tempo local. Em caso de erro, retorna NULL.

Atenção: Assim como a gmtime, esta função utiliza um buffer estático compartilhado. Chamadas subsequentes a funções de conversão de tempo na mesma thread podem sobrescrever os dados.

Exemplo

// EXEMPLO LOCALTIME()
#include <stdio.h>
#include <time.h>

int main() { 
    time_t tempo; 
    time(&tempo); 

    // Converte o tempo do sistema para a estrutura local
    struct tm *tempo_local = localtime(&tempo);

    if (tempo_local != NULL) {
        printf("Horário atual: %02d:%02d:%02d\n", 
               tempo_local->tm_hour, 
               tempo_local->tm_min, 
               tempo_local->tm_sec);
    }

    return 0; 
}

Saída esperada

Horário atual: 01:19:11

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

Formata as informações de tempo da estrutura tm de acordo com as especificações contidas em format e armazena o resultado na string s.

Recebe: Um ponteiro para o array de destino, o tamanho máximo do buffer, a string de formato e o ponteiro para a estrutura de tempo de origem.

Retorna: O número de caracteres colocados no array s (excluindo o caractere nulo). Se o número total de caracteres exceder o limite max, a função retorna 0 e o conteúdo do array é indefinido.

Formatos comuns:
  • %d: Dia do mês (01-31)
  • %m: Mês (01-12)
  • %Y: Ano com quatro dígitos
  • %H: Hora (00-23)
  • %M: Minuto (00-59)
  • %S: Segundo (00-59)

Exemplo

// EXEMPLO STRFTIME()
#include <stdio.h>
#include <time.h>
#include <stdlib.h>

int main() { 
    time_t tempo; 
    time(&tempo);
    struct tm *tempo_local = localtime(&tempo);

    char data_formatada[100];
    
    // %c representa data e hora padronizadas para o locale atual
    if (strftime(data_formatada, sizeof(data_formatada), "%c", tempo_local)) {
        printf("%s\n", data_formatada);
    }

    return 0; 
}

Saída esperada

Fri May 28 19:51:07 2021