# C/Appendice/Librerie standard/time.h

C
Copertina Tutti i moduli · Sviluppo
* LinguaggioC/Linguaggio
** PanoramicaC/Linguaggio/Panoramica
** Struttura del linguaggioC/Linguaggio/Struttura del linguaggio
* Variabili, operatori e costantiC/Variabili, operatori e costanti
** VariabiliC/Variabili, operatori e costanti/Variabili
** Operatori aritmeticiC/Variabili, operatori e costanti/Operatori aritmetici
** Operatori sui bitC/Variabili, operatori e costanti/Operatori sui bit
** CostantiC/Variabili, operatori e costanti/Costanti
* Blocchi e funzioniC/Blocchi e funzioni
** Blocchi if e switchC/Blocchi e funzioni/Blocchi if e switch
** Operatori logiciC/Blocchi e funzioni/Operatori logici
** CicliC/Blocchi e funzioni/Cicli
** FunzioniC/Blocchi e funzioni/Funzioni
** mainC/Blocchi e funzioni/main
** LibrerieC/Blocchi e funzioni/Librerie
** RicorsivitàC/Blocchi e funzioni/Ricorsività
* Vettori e puntatoriC/Vettori e puntatori
** VettoriC/Vettori e puntatori/Vettori
** PuntatoriC/Vettori e puntatori/Puntatori
** Interscambiabilità tra puntatori e vettoriC/Vettori e puntatori/Interscambiabilità tra puntatori e vettori
* StringheC/Variabili, operatori e costanti/Stringhe
* Enumerazioni, strutture e unioniC/Enumerazioni, strutture e unioni
** EnumerazioniC/Enumerazioni, strutture e unioni/Enumerazioni
** StruttureC/Enumerazioni, strutture e unioni/Strutture
** UnioniC/Enumerazioni, strutture e unioni/Unioni
* Conversioni di tipoC/Conversioni di tipo
* Lettura e scrittura su fileC/Lettura e scrittura su file
** File di TestoC/Lettura e scrittura su file/File di Testo
** File BinariC/Lettura e scrittura su file/File Binari
* Compilatore e precompilatoreC/Compilatore e precompilatore
** CompilatoreC/Compilatore e precompilatore/Compilatore
** DirettiveC/Compilatore e precompilatore/Direttive
** HeaderC/Compilatore e precompilatore/Header
* VisibilitàC/Visibilità
* Gestione della memoriaC/Gestione della memoria
* Le applicazioni CGIC/Le applicazioni CGI
* Appendice
** Librerie standardC/Appendice/Librerie standard
*** assert.hC/Appendice/Librerie standard/assert.h
*** ctype.hC/Appendice/Librerie standard/ctype.h
*** errno.hC/Appendice/Librerie standard/errno.h
*** float.hC/Appendice/Librerie standard/float.h
*** limits.hC/Appendice/Librerie standard/limits.h
*** locale.hC/Appendice/Librerie standard/locale.h
*** math.hC/Appendice/Librerie standard/math.h
*** setjmp.hC/Appendice/Librerie standard/setjmp.h
*** signal.hC/Appendice/Librerie standard/signal.h
*** stdarg.hC/Appendice/Librerie standard/stdarg.h
*** stddef.hC/Appendice/Librerie standard/stddef.h
*** stdio.hC/Appendice/Librerie standard/stdio.h
*** stdlib.hC/Appendice/Librerie standard/stdlib.h
*** string.hC/Appendice/Librerie standard/string.h
*** time.hC/Appendice/Librerie standard/time.h
** StrumentiC/Appendice/Strumenti
*** InstallerC/Appendice/Strumenti/Installer
** Librerie esterneC/Appendice/Librerie esterne
* Bibliografia
    IndiceC/Indice
Modifica il sommario
time.h è l'header file della libreria standard del C che fornisce un accesso standardizzato alle funzioni di acquisizione e manipolazione del tempo.

## Cicli CPU

La funzione clock consente di ottenere il tempo di utilizzo del microprocessore (CPU), espresso virtualmente in cicli di CPU. In pratica, viene definita la macro-variabile CLOCKS_PER_SEC, contenente il valore che esprime convenzionalmente la quantità di cicli di CPU per secondo; quindi, il valore restituito dalla funzione clock si traduce in secondi dividendolo per CLOCKS_PER_SEC. Il valore restituito dalla funzione clock e l'espressione in cui si traduce la macro-variabile CLOCKS_PER_SEC sono di tipo clock_t:
La funzione clock restituisce il tempo di CPU espresso in unità clock_t, utilizzato dal processo elaborativo a partire dall'avvio del programma. Se la funzione non è in grado di dare questa indicazione, allora restituisce il valore -1, o più precisamente (clock_t) (-1).
Per valutare l'intervallo di tempo di utilizzo della CPU, da una certa posizione del programma, a un'altra, occorre memorizzare i valori ottenuti dalla funzione e poi procedere a una sottrazione.

## Rappresentazione del tempo

La libreria definisce il tipo time_t che, secondo lo standard, rappresenta la quantità di unità di tempo trascorsa a partire da un'epoca di riferimento.

## Rappresentazione del tempo in una struttura

La libreria standard prescrive che sia definito il tipo struct tm, con il quale è possibile rappresentare tutte le informazioni relative a un certo tempo, secondo le convenzioni umane. Lo standard prescrive con precisione i membri minimi della struttura e l'intervallo di valori che possono contenere:
Si può osservare che il mese viene rappresentato con valori che vanno da 0 a 11, pertanto gennaio si indica con lo zero e dicembre con il numero 11; inoltre, l'intervallo ammesso per i secondi consente di rappresentare un secondo in più, dato che l'intervallo corretto sarebbe da 0 a 59; infine, il fatto che i giorni dell'anno vadano da 0 (il primo) a 365 (l'ultimo), significa che negli anni normali i valori vanno da 0 a 364, mentre negli anni bisestili si arriva a contare fino a 365.

## Funzioni per il tempo

Un gruppo di funzioni dichiarate nel file time.h ha lo scopo di elaborare in qualche modo le informazioni legate al tempo. Queste funzioni trattano il tempo in forma di variabili di tipo time_t o di tipo struct tm.
La variabile di tipo time_t che viene usata in queste funzioni potrebbe esprimere un valore riferito al tempo universale (UT), mentre le funzioni che la utilizzano dovrebbero tenere conto del fuso orario.

### time

La funzione time determina il tempo attuale secondo il calendario del sistema operativo, restituendolo nella forma del tipo time_t. La funzione richiede un parametro, costituito da un puntatore di tipo time_t *: se questo puntatore è valido, la stessa informazione che viene restituita viene anche memorizzata nell'indirizzo indicato da tale puntatore.
In pratica, se è possibile (valore diverso da NULL), l'informazione data-orario raccolta dalla funzione, viene anche memorizzata in *timer.
Se la funzione non può fornire l'informazione richiesta, allora restituisce il valore -1, o più precisamente: (time_t) (-1).

### difftime

La funzione difftime calcola la differenza tra due date, espresse in forma time_t e restituisce l'intervallo in secondi, in una variabile in virgola mobile, di tipo double:
Per la precisione, viene eseguito time1-time0 e di conseguenza va il segno del risultato.

### mktime

La funzione mktime riceve come argomento il puntatore a una variabile strutturata di tipo struct tm, contenente le informazioni sull'ora locale, e determina il valore di quella data secondo la rappresentazione interna, di tipo time_t:
La funzione tiene in considerazione solo alcuni membri della struttura; per la precisione, non considera il giorno della settimana e il giorno dell'anno; inoltre, ammette anche valori al di fuori degli intervalli stabiliti per i vari membri della struttura; infine, considera un valore negativo per il membro timeptr->tm_isdst come la richiesta di determinare se sia o meno in vigore l'ora estiva per la data indicata.
Se la funzione non è in grado di restituire un valore rappresentabile nel tipo time_t, o comunque se non può eseguire il suo compito, restituisce il valore -1, o più precisamente (time_t) (-1). Se invece tutto procede regolarmente, la funzione provvede anche a correggere i valori dei vari membri della struttura e a ricalcolare il giorno della settimana e dell'anno.

### gmtime e localtime

Le funzioni gmtime e localtime hanno in comune il fatto di ricevere come argomento il puntatore di tipo time_t *, a un'informazione data-orario, per restituire il puntatore a una variabile strutturata di tipo struct tm *. In altri termini, le due funzioni convertono una data espressa nella forma del tipo time_t, in una data suddivisa nella struttura tm:
Nell'ambito di queste funzioni, è ragionevole supporre che l'informazione di tipo time_t a cui fanno riferimento, sia espressa in termini di tempo universale e che le funzioni stesse abbiano la possibilità di stabilire il fuso orario e la modalità di regolazione dell'ora estiva.
In ogni caso, la differenza tra le due funzioni sta nel fatto che gmtime traduce il tempo a cui punta il suo argomento in una struttura contenente la data tradotta secondo il tempo coordinato universale, mentre localtime la traduce secondo l'ora locale.
Va osservato che queste funzioni restituiscono un puntatore a un'area di memoria che può essere sovrascritta da altre chiamate alle stessi funzioni o a funzioni simili.

## Conversione in stringhe

Un gruppo di funzioni del file time.h è destinato alla conversione dei valori data-orario in stringhe, per l'interpretazione umana.

### asctime

La funzione asctime converte un'informazione data-orario, espressa nella forma di una struttura struct tm, in una stringa che esprime l'ora locale, usando però una rappresentazione fissa in lingua inglese:

### ctime

La funzione ctime converte un'informazione data-orario, espressa nella forma del tipo time_t in una stringa che esprime l'ora locale, usando però una rappresentazione fissa in lingua inglese:

### strftime

La funzione strftime si occupa di interpretare il contenuto di una struttura di tipo struct tm e di tradurlo in un testo, secondo una stringa di composizione libera. In altri termini, questa funzione si comporta in modo simile a printf, dove l'input è costituito dalla struttura contenente le informazioni data-orario.
Dal modello del prototipo della funzione, si vede che questa restituisce un valore numerico di tipo size_t. Questo valore rappresenta la quantità di elementi che sono stati scritti nella stringa di destinazione, rappresentata dal primo parametro. Dal computo di questi elementi è escluso il carattere nullo di terminazione, ma questo viene comunque aggiunto dalla funzione.
La funzione richiede, nell'ordine: un array di caratteri da utilizzare per comporre il testo; la dimensione massima di questo array; la stringa di composizione, contenente del testo costante e degli specificatori di conversione; il puntatore alla struttura contenente le informazioni data-orario da usare nella conversione.
La funzione termina il proprio lavoro con successo solo se può scrivere nell'array di destinazione il testo composto secondo le indicazioni della stringa di composizione, includendo anche il carattere nullo di terminazione. Se ciò non avviene, il valore restituito dalla funzione è zero e il contenuto dell'array di destinazione è imprecisato.
Il listato successivo mostra un programma completo che dimostra il funzionamento di strftime. Va osservato che la conversione eseguita da tale funzione è sensibile alla configurazione locale; precisamente dipende dalla categoria LC_TIME:
Ecco cosa si potrebbe ottenere eseguendo questo programma in un sistema con localizzazione in italiano:
42: Salve: sono le 10:31 del 30 aprile 2010.
Nella tabella successiva vengono elencati gli specificatori di conversione principali. Sono ammissibili delle varianti, con l'aggiunta di modificatori, che però non vengono descritte. Per esempio è ammissibile l'uso degli specificatori %Ec e %Od, per indicare rispettivamente una variante di %c e %d.