C/Standardikirjastot/time.h

#include <time.h>

Tämä kirjasto määrittelee aikojen ja päivämäärien käsittelyyn liittyviä tyyppejä ja funktioita.

size_t, NULL: ks. stddef.h

Makrot ja tyypit

CLOCKS_PER_SEC

(tai CLK_TCK) on luku, joka ilmaisee clock()-funktion paluuarvon tarkkuutta. Jos paluuarvo jaetaan CLOCKS_PER_SEC:llä, saadaan tulokseksi sekunteja.

clock_t
time_t

ovat clock()-funktion ja time()-funktion paluuarvojenn tietotyyppit. Molemmat tietotyypit ovat jonkinlaisia numeroita, joille voi suorittaa peruslaskutoimituksia.

Monissa nykyjärjestelmissä time_t on niin sanottu Unix-aikaleima, eli sekuntien lukumäärä sitten keskiyön 1. tammikuuta 1970 (klo 0.00.00). C-standardi ei kuitenkaan takaa tätä.

struct tm

on tietue, joka sisältää seuraavat kentät:

int tm_sec;    /* kellonajan sekunnit --- [0, 60] (60 karkaussekunneille) */
int tm_min;    /* kellonajan minuutit --- [0, 59] */
int tm_hour;   /* kellonajan tunnit --- [0, 23] */
int tm_mday;   /* päivämäärän päivä (kuukauden sisällä) --- [1, 31] */
int tm_mon;    /* päivämäärän kuukausi, 0 on tammikuu, jne. --- [0, 11] */
int tm_year;   /* päivämäärän vuosi - 1900; esim. 124 = vuosi 2024 */
int tm_wday;   /* viikonpäivä, 0 on sunnuntai, 1 on maanantai, jne. --- [0, 6] */
int tm_yday;   /* vuoden päivä, 0 on 1.1., jne. --- [0, 365] */
int tm_isdst;  /* kesäajan ilmaisin; 0 jos normaaliaika, positiivinen jos kesäaika, negatiivinen jos ei tiedetä
                  tällä esim. erotetaan kaksi kellonaikaa 3.30 kun siirrytään kesäajasta talviaikaan */

Funktiot

Perusfunktiot

clock_t clock(void);

palauttaa ohjelman käyttämän suoritinajan. Yksikkö on 1/CLOCKS_PER_SEC sekuntia. Huomaa, että tämä ei ole välttämättä sama asia kun suoritusaika. Se vastaa enemmän ohjelman tekemää työmäärää; jos tulos on yksi sekunti, ohjelma on teettänyt suorittimelle (tai suorittimen ytimelle) sen verran työtä kuin mitä se pystyy tekemään täydellä teholla yhden sekunnin.

double difftime(time_t time1, time_t time0);

laskee kahden time_t-ajankohdan välisen aikaeron ja palauttaa tuloksen sekunteina.

time_t mktime(struct tm *ptm);

koostaa time_t-arvon ptm-osoittimen osoittamasta struct tm -tietueesta, jonka tulkitaan olevan paikallista aikaa.

Tietueessa ei tarvitse määritellä etukäteen tm_wday ja tm_yday -kenttiä, ja niitä edeltävillä kentillä voi olla muitakin arvoja kuin yllä mainitut. Funktio muokkaa osoitettua tietuetta niin, että kaikki kentät siirretään oikein yllä määriteltyjen alueiden sisälle (esim. jos tm_mon on 12, niin siitä tulee 0, ja vuosi kasvaa yhdellä), ja samalla täyttää kentät tm_wday ja tm_yday.

Palauttaa (time_t)-1, jos annettua päivämäärää ja kellonaikaa ei voi esittää time_t-arvona.

time_t time(time_t *pt);

palauttaa nykyisen ajanhetken time_t-arvona, tai (time_t)-1, jos ei tiedossa. Jos pt ei ole NULL, sama arvo tallennetaan myös osoittimen osoittamaan muistipaikkaan.

Tekstimuunnokset

char *asctime(const struct tm *ptm);

muuntaa struct tm -tietueen (jonka arvojen on oltava sallittujen arvojen sisäpuolella) tekstiksi. Muunnos tehdään sisäiseen puskuriin, joita on olemassa koko ohjelmassa vain yksi, ja funktio palauttaa osoitteen puskuriin. Tuloksen muoto on seuraavanlainen:

Fri Jul 12 14:55:53 2024

jossa ensimmäiset kolme merkkiä on viikonpäivä englanninkielisellä lyhenteellä, seuraavat kolme kuukausi englanninkielisellä lyhenteellä, sitten kuukauden päivä, kellonaika ja vuosi. Lopuksi merkkijonossa on vielä rivinvaihto.

char *ctime(const time_t *aika);

muuntaa ensin aikaleiman localtime-funktiolla päivämääräksi ja ajaksi, ja sitten tekstiksi asctime-funktiolla.

asctime:ä ja ctime:ä ei saa yhteisen sisäisen puskurin takia käyttää monisäikeisessä ohjelmassa. Ne ovat yleensäkin muinaisjäänne, joiden käyttö ei ole suositeltavaa.

struct tm *gmtime(const time_t *aika);

muuntaa aikaleiman struct tm -tietueeksi, joka on GMT- eli UTC-aikaa. Palauttaa osoitteen sisäiseen puskuriin, joita on olemassa koko ohjelmassa vain yksi, ja jossa muunnettu tietue sijaitsee.

struct tm *localtime(const time_t *aika);

muuntaa aikaleiman struct tm -tietueeksi, joka on paikallista aikaa. Palauttaa osoitteen sisäiseen puskuriin, joita on olemassa koko ohjelmassa vain yksi, ja jossa muunnettu tietue sijaitsee.

Yhteisen sisäisen puskurin takia gmtime:n ja localtime:n käyttö monisäikeisessä ohjelmassa on hankalaa ja vaatii jonkinlaisen rakenteen, jolla estetään useaa säiettä kutsumasta niitä samaan aikaan.

size_t strftime(char *puskuri, size_t koko, const char *kaava, const struct tm *aika);

muuntaa päivämäärän ja ajan tekstiksi annettuun puskuriin, jonka koko ilmaistaan argumenttina. Palauttaa kirjoitettujen merkkien määrän (lopussa olevaa nollamerkkiä ei lasketa). Jos tulos ei mahdu puskuriin, palauttaa nollan, ja puskurin sisältöä ei tällöin taata mitenkään.

Tekstimuunnos tehdään annetun kaavan mukaisesti, jossa erityismuuttujat ilmaistaan prosenttimerkillä. Muut merkit kopioidaan tekstiin sellaisenaan. Muunnos noudattaa nykyistä maa-asetuksia (ks. locale.h).

Koodi	Selitys
%%	Prosenttimerkki sellaisenaan
%a	Viikonpäivän nimen lyhenne
%A	Viikonpäivän koko nimi
%b [C99] %h	Kuukauden nimen lyhenne
%B	Kuukauden koko nimi
%c	Päivämäärä ja aika maa-asetusten mukaisessa esitysmuodossa
%d	Kuukauden päivä (01-31), kaksi numeroa
%H	Kellonajan tunnit (00-23), kaksi numeroa
%I	Kellonajan tunnit (01-12) 12 tunnin kellolla, kaksi numeroa
%j	Vuoden päivä (001-366), kolme numeroa
%m	Kuukausi (01-12), kaksi numeroa
%M	Kellonajan minuutit (00-59), kaksi numeroa
%p	Aamupäivä tai iltapäivä
%S	Kellonajan sekunnit (00-59), kaksi numeroa
%U	Viikon numero (00-53), kaksi numeroa; vuoden ensimmäinen sunnuntai on viikon 1 ensimmäinen päivä
%w	Viikonpäivä (0-6, 0 = sunnuntai)
%W	Viikon numero (00-53), kaksi numeroa; vuoden ensimmäinen maanantai on viikon 1 ensimmäinen päivä
%x	Päivämäärä maa-asetusten mukaisessa esitysmuodossa
%X	Kellonaika maa-asetusten mukaisessa esitysmuodossa
%y	Vuosi (00-99), kaksi viimeistä numeroa
%Y	Vuosi
%Z	Aikavyöhykkeen nimi tai lyhenne
[C99] %C	Vuosi, paitsi kaksi viimeistä numeroa
[C99] %D	Sama kuin %m/%d/%y
[C99] %e	Kuukauden päivä (1-31), yksi tai kaksi numeroa
[C99] %F	Sama kuin %Y-%m-%d
[C99] %G	ISO 8601 -järjestelmän mukainen viikkovuosi
[C99] %g	ISO 8601 -järjestelmän mukainen viikkovuosi, kaksi viimeistä numeroa
[C99] %n	Rivinvaihto
[C99] %r	%H:%M 12 tunnin kellolla + aamupäivä/iltapäivä
[C99] %R	Sama kuin %H:%M
[C99] %T	Sama kuin %H:%M:%S
[C99] %t	Sarkain
[C99] %u	Viikonpäivä (1-7, 1 = maanantai)
[C99] %z	Aikavyöhykkeen ero UTC:sta ISO 8601 -standardin mukaisessa muodossa

C99 tukee lisäksi etuliitettä E koodeilla %Ec, %EC, %Ex, %EX, %Ey ja %EY, sekä etuliitettä O koodeilla %Ob, %OB, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy. Nämä käyttävät maa-asetusten vaihtoehtoista kalenteria (E) tai lukujärjestelmää (O).

Esimerkkejä

Kaava	Esimerkkitulos
%H:%M:%S	14:55:53
%d.%m.%Y	12.07.2024
%a %d.%m.%Y klo %H:%M:%S	pe 12.07.2024 klo 14:55:53