C/Standardikirjastot/stdlib.h

#include <stdlib.h>

Tähän otsikkotiedostoon on sijoitettu erilaisia funktioita, jotka eivät sovi mihinkään muuhun otsikkotiedostoon.

Makrot

EXIT_SUCCESS
EXIT_FAILURE

ovat kokonaislukuja, jotka sopivat exit-funktion argumentiksi. Ensimmäinen tarkoittaa, että ohjelma suoritettiin onnistuneesti loppuun asti, ja jälkimmäinen, että ohjelman suoritus keskeytyi jonkinlaisen virheen vuoksi.

RAND_MAX

on suurin kokonaisluku (vähintään 32767), jonka rand-funktio voi palauttaa,

MB_CUR_MAX

on se, montako merkkiä voi enintään olla monitavuisessa merkissä nykyisillä maa-asetuksilla (LC_CTYPE, ks. locale.h), vähintään 1 ja enintään MB_LEN_MAX (ks. stddef.h).

Funktiot

Tekstin muuntaminen luvuksi

Funktio	Selitys
double atof(const char *s);	Lukee merkkijonon s, ohittaa alussa olevat tyhjät merkit ja muuntaa niiden jälkeen olevan osan liukuluvuksi. Jos sitä ei voi muuntaa, on tyhjä tai sisältää vain tyhjiä merkkejä, palauttaa nollan.
int atoi(const char *s); long atol(const char *s); [C99] long long atoll(const char *s);	Lukee merkkijonon s, ohittaa alussa olevat tyhjät merkit ja muuntaa niiden jälkeen olevan osan kokonaisluvuksi. Jos sitä ei voi muuntaa, on tyhjä tai sisältää vain tyhjiä merkkejä, palauttaa nollan.
double strtod(const char *s, const char **loppu); [C99] float strtof(const char *s, const char **loppu); [C99] long double strtold(const char *s, const char **loppu);	Lukee merkkijonon s, ohittaa alussa olevat tyhjät merkit ja muuntaa niiden jälkeen olevan osan liukuluvuksi. Palauttaa luvun. Jos loppu ei ole NULL, siihen sijoitetaan osoite ensimmäiseen merkkijonon merkkiin, jota ei enää tulkittu osaksi lukua. Jos lukua ei voitu muuntaa, palauttaa nollan, ja loppu-osoittimeen (jos ei NULL) sijoitetaan s (vaikka alussa olisi ollut tyhjiä merkkejä). Jos luku on liian suuri esitettäväksi, palauttaa ±HUGE_VAL:n (ks. math.h) ja asettaa errno:n arvoksi ERANGE (ks. errno.h). Jos luku on liian lähellä nollaa esitettäväksi, palauttaa nollan (ks. math.h) ja asettaa errno:n arvoksi ERANGE (ks. errno.h).
long strtol(const char *s, const char **loppu, int kantaluku); [C99] long long strtoll(const char *s, const char **loppu, int kantaluku);	Lukee merkkijonon s, ohittaa alussa olevat tyhjät merkit ja muuntaa niiden jälkeen olevan osan etumerkilliseksi kokonaisluvuksi. Palauttaa luvun. kantaluku voi olla 2-36 tai 0. Jos se on 0, kantaluku tulkitaan automaattisesti C:n sääntöjen mukaisesti; alussa oleva 0 asettaa luvun oktaaliksi (kantaluku 8) ja 0x/0X heksadesimaaliksi (kantaluku 16), muuten luku tulkitaan desimaaliluvuksi. Jos kantaluku on 16 ja merkkijonossa on etumerkin jälkeen 0x/0X, se ohitetaan - tämä on ainoa poikkeus. Jos loppu ei ole NULL, siihen sijoitetaan osoite ensimmäiseen merkkijonon merkkiin, jota ei enää tulkittu osaksi lukua. Jos lukua ei voitu muuntaa, palauttaa nollan, ja loppu-osoittimeen (jos ei NULL) sijoitetaan s (vaikka alussa olisi ollut tyhjiä merkkejä). Jos luku on liian suuri esitettäväksi, palauttaa ±(L)LONG_MAX:n (ks. limits.h) ja asettaa errno:n arvoksi ERANGE (ks. errno.h).
unsigned long strtoul(const char *s, const char **loppu, int kantaluku); [C99] unsigned long long strtoull(const char *s, const char **loppu, int kantaluku);	Lukee merkkijonon s, ohittaa alussa olevat tyhjät merkit ja muuntaa niiden jälkeen olevan osan etumerkittömäksi kokonaisluvuksi. Palauttaa luvun. kantaluku voi olla 2-36 tai 0. Jos se on 0, kantaluku tulkitaan automaattisesti C:n sääntöjen mukaisesti; alussa oleva 0 asettaa luvun oktaaliksi (kantaluku 8) ja 0x/0X heksadesimaaliksi (kantaluku 16), muuten luku tulkitaan desimaaliluvuksi. Jos luvussa on miinusmerkki, se tulkitaan tavallisten tyyppimuunnossääntöjen mukaisesti (esim. -1 kuin jos olisi koodissa kirjoitettu (unsigned long)(-1)). Jos kantaluku on 16 ja merkkijonossa on etumerkin jälkeen 0x/0X, se ohitetaan - tämä on ainoa poikkeus. Jos loppu ei ole NULL, siihen sijoitetaan osoite ensimmäiseen merkkijonon merkkiin, jota ei enää tulkittu osaksi lukua. Jos lukua ei voitu muuntaa, palauttaa nollan, ja loppu-osoittimeen (jos ei NULL) sijoitetaan s (vaikka alussa olisi ollut tyhjiä merkkejä). Jos luku on liian suuri esitettäväksi, palauttaa ±U(L)LONG_MAX:n (ks. limits.h) ja asettaa errno:n arvoksi ERANGE (ks. errno.h).

Satunnaisluvut

int rand(void);

palauttaa satunnaisen kokonaisluvun väliltä [0, RAND_MAX].

void srand(unsigned int siemenluku);

alustaa satunnaislukugeneraattorin annetulla siemenluvulla. Oletussiemenluku on 1, jos srand-funktiota ei kutsuta ennen rand-funktiota.

Jos satunnaislukugeneraattori alustetaan useasti samalla siemenluvulla, rand tuottaa aina samat luvut joka alustuksen jälkeen. Tämän tuloksena myös rand ilman alustusta tuottaa samalla alustalla aina samat luvut. Muista siis aina alustaa generaattori ohjelman alussa, jos haluat satunnaisia lukuja!

rand ei ole muutenkaan erityisen hyvä satunnaislukugeneraattori. Se sopii ehkä yksinkertaisiin tarkoituksiin, mutta muihin kannattaa ilman muuta harkita toista ratkaisua.

Muistinhallinta

Pääartikkeli: C/Dynaaminen muistinvaraus

void *malloc(size_t koko);

(size_t: etumerkitön kokonaislukutyyppi, ks. stddef.h)

malloc varaa keosta muistilohkon, jonka koko on koko merkkiä (eli yleensä tavua), ja palauttaa osoittimen varattuun lohkoon. Lohkossa olevaa muistia ei ole alustettu mitenkään, joten sen sisältö voi olla aivan mitä tahansa. Muistin alustukseen sopii hyvin esim. memset (ks. string.h).

malloc:n kanssa pitää olla varovainen, että varattu koko riittää. Esimerkiksi varatessa tilaa 50 int-kokonaisluvulle koko ei suinkaan ole 50, vaan 50 * sizeof(int).

Jos muistin varaus epäonnistuu, palauttaa NULL:n. Ohjelmoijan vastuulla on tarkistaa, ettei palautettu osoitin ole NULL! (Muistathan, että esim. if-lausekkeessa osoitin on epätosi jos ja vain jos se on NULL.)

int *taulukko = malloc(64 * sizeof(int));
if (!taulukko) {
  puts("Taulukolle ei saatu varattua muistia");
  abort();
}

void *calloc(size_t lkm, size_t koko);

varaa muistia malloc:n tavoin. Varatun muistilohkon koko on annetun koon ja lukumäärän tulo, joten sizeof:lla kertomista ei calloc:n kanssa tarvita (malloc(50 * sizeof(int)) → calloc(50, sizeof(int))). calloc on usein parempi vaihtoehto myös siksi, että tulo voi olla liian suuri esitettäväksi; tätä ongelmaa ei ole calloc:lla. Toisin kuin malloc, calloc alustaa varatun muistin tyhjäksi (nollilla) ennen osoittimen palauttamista. calloc voi malloc:n tavoin palauttaa NULL:n, mikäli varaus epäonnistuu.

void *realloc(void *varaus, size_t uusi_koko);

muuttaa malloc:lla, calloc:lla tai realloc:lla varattua muistilohkoa. Osoittimen arvon on oltava tasan sellainen kuin mitä aiemmin mainittu funktio on palauttanut, eikä sitä ole saatu vapauttaa aiemmin realloc:lla tai free:llä. Muistivarauksen kokoa muutetaan niin, että sen uusi koko on pyydetyn määrän verran merkkejä (yleensä tavuja). realloc pitää tallella niin paljon alkuperäisestä varauksesta kun se voi; lopusta leikkautuu pois osia, jos koko laskee. Jos koko kasvaa, uutta loppuosaa ei alusteta, joten sen sisältö voi olla aivan mitä tahansa.

Jos koon muuttaminen onnistuu, funktio palauttaa uuden osoittimen; tällöin funktiolle annettu osoitin ei ole enää kelvollinen (sitä ei saa antaa enää edes free:lle). Palautettu osoitin voi olla sama kuin annettu, mutta tätä ei saa missään tapauksessa olettaa. Jos koon muuttaminen epäonnistuu, palauttaa NULL:n; tällöin, ja vain tällöin, argumentiksi annettu osoitin on yhä kelvollinen.

varaus saa olla NULL, jolloin realloc toimii kuin malloc. Uuden koon sen sijaan ei kannata koskaan olla 0, eikä realloc:n saa olettaa vapauttavan varausta siinä tapauksessa, vaikka jotkin toteutukset toimisivatkin näin.

void free(void *varaus);

vapauttaa muistivarauksen. Argumentiksi annetun osoittimen arvon on oltava tasan sellainen kuin mitä malloc, calloc tai realloc on palauttanut, eikä sitä ole saatu vapauttaa aiemmin realloc:lla tai free:llä. Poikkeus: varaus saa olla NULL, jolloin mitään ei tapahdu.

free-kutsun jälkeen osoitin on kelvoton, eikä sitä saa käyttää enää mihinkään - sillä ei saa kutsua edes free:tä toista kertaa.

Ohjelmoijan vastuulla on vapauttaa kaikki hänen tekemät muistivaraukset. Jos osoitin 'hukataan' ennen sitä vastaavan varauksen vapauttamista, varausta ei vapauteta automaattisesti, ja se 'jää elämään'. Tämä johtaa muistivuotoon. Ainoa poikkeus on, että ohjelmaa lopetettaessa kaikki sen tekemät muistivaraukset vapautuvat. Kuuluu kuitenkin hyviin tapoihin vapauttaa ne itse, siinä määrin kuin se on mahdollista.

Järjestelmäfunktiot

Funktio	Selitys
void abort(void);	Lopettaa ohjelman suorituksen välittömästi. atexit-pyyntöjä ei suoriteta. Tarkoitettu tapauksiin, jossa odottamattoman virheen takia ohjelman suorituksen on päätyttävä välittömästi. Älä käytä ohjelman lopettamiseen 'onnistuneissa' tapauksissa. Tämä funktio ei koskaan palaa kutsuvaan koodiin.
int atexit(void (*funktio)(void));	Pyytää C-standardikirjastoa suorittamaan annetun funktion (joka ei ota parametreja tai palauta mitään) ennen kuin ohjelman suoritus lakkaa, joko exit-funktion tai main:sta palauttamisen takia. Ensin pyydetyt funktiot suoritetaan viimeisenä. Palauttaa nollan, jos pyyntö rekisteröitiin, ja muun kuin nollan, jos tapahtui virhe. C-standardi vaatii, että toteutuksen on tuettava vähintään 32 rekisteröityä pyyntöä.
void exit(int paluuarvo);	Lopettaa ohjelman suorituksen. Suorittaa atexit-pyynnöt ennen lopettamista. Annettu argumentti toimii ohjelman paluuarvona. Tämä funktio ei koskaan palaa kutsuvaan koodiin. exit:llä on täysin sama vaikutus kuin paluuarvon palauttaminen main-funktiosta. Paluuarvo saa olla ainakin EXIT_SUCCESS (ohjelman suoritus onnistui) ja EXIT_FAILURE (ohjelman suoritus epäonnistui). Useilla nykyjärjestelmillä EXIT_SUCCESS on 0, kun taas muut arvot kuin 0 (yleensä väliltä -128-1, 1-127) ilmaisevat jonkinlaista virhettä.
char *getenv(const char *nimi);	Hakee ympäristömuuttujan nimen perusteella. Palauttaa osoittimen ympäristömuuttujan arvon sisältävään C-merkkijonoon. tai NULL:n, jos muuttujaa ei löytynyt.
int system(const char *komento);	Suorittaa järjestelmäkomennon ja palauttaa komennon paluuarvon, jos komento ei ole NULL. Jos komento on NULL, palauttaa nollan, jos komentoja ei voi suorittaa, ja muuten jonkin muun arvon. Tälle ei varmaan kannata antaa mitään, minkä käyttäjä pystyy päättämään, ellei sille ole erityisen painavaa syytä.
void _Exit(int paluuarvo);	[C99] Lopettaa ohjelman suorituksen suorittamatta atexit-pyyntöjä. Annettu argumentti toimii ohjelman paluuarvona (ks. exit). Tämä funktio ei koskaan palaa kutsuvaan koodiin.

Perusalgoritmit

Funktio	Selitys
void *bsearch(const void *haettava, const void *taulukko, size_t lkm, size_t koko, int (*vertaa)(const void *, const void *));	Binäärihaku eli puolitushaku. Hakee taulukosta, jonka ensimmäisen alkioon osoittaa osoitin taulukko ja jossa on lkm alkiota (joiden koko on koko merkkiä/tavua), haettavan alkion. vertaa on oltava funktio, joka vertaa kahta alkiota. Se palauttaa nollan, jos alkiot ovat yhtä suuret, negatiivisen kokonaisluvun jos ensimmäinen alkio on jälkimmäistä pienempi, ja positiivisen jos ensimmäinen alkio on jälkimmäistä suurempi. Vertailufunktio ei saa käyttää minkäänlaista ulkoista, mahdollisesti muuttuvaa, tietolähdettä vertailun pohjana, sillä vertailufunktion toiminnan muuttuminen kesken bsearch:n estää sitä toimimasta kunnolla. Taulukon alkioiden on oltava vertailujen mukaisessa järjestyksessä, tai funktio ei toimi oikein. Lopuksi funktio palauttaa osoittimen haettuun alkioon, tai NULL, jos haettavaa alkiota ei löytynyt taulukosta.
void qsort(void *taulukko, size_t lkm, size_t koko, int (*vertaa)(const void *, const void *));	Järjestää taulukon, jonka ensimmäisen alkioon osoittaa osoitin taulukko ja jossa on lkm alkiota (joiden koko on koko merkkiä/tavua). vertaa on oltava funktio, joka vertaa kahta alkiota. Se palauttaa nollan, jos alkiot ovat yhtä suuret, negatiivisen kokonaisluvun jos ensimmäinen alkio on jälkimmäistä pienempi, ja positiivisen jos ensimmäinen alkio on jälkimmäistä suurempi. Vertailufunktio ei saa käyttää minkäänlaista ulkoista, mahdollisesti muuttuvaa, tietolähdettä vertailun pohjana, sillä vertailufunktion toiminnan muuttuminen kesken qsort:n estää sitä toimimasta kunnolla. Funktiokutsun jälkeen taulukko on vertailujärjestyksessä. Yhtä suurten alkioiden järjestystä funktion palauduttua ei taata.

Esimerkit

 int vertaa(const void *a, const void *b) { return *(const int *)a - *(const int *)b; }
 /* ... */
 int taulukko[5] = { 3, 5, 1, 2, 4 };
 qsort(taulukko, sizeof(taulukko) / sizeof(*taulukko), sizeof(*taulukko), &vertaa);
 /* taulukko on nyt järjestyksessä */
 int haettava = 3;
 int *kolmonen = bsearch(&haettava, taulukko, sizeof(taulukko) / sizeof(*taulukko), sizeof(*taulukko), &vertaa);
 /* *haettava == 3 */

Kokonaislukuapufunktiot

Funktio	Selitys
int abs(int x); long labs(long x); [C99] long long llabs(long long x);	Itseisarvo. Palauttaa kokonaisluvun itseisarvon, mikäli se on esitettävissä tietotyypillä.
div_t div(int n, int d); ldiv_t ldiv(long n, long d); [C99] lldiv_t lldiv(long long n, long long d);	Palauttaa kahden kokonaisluvun osamäärän ja jakojäännöksen. Palautettu tietotyyppi on tietue, jossa on kentät quot (osamäärä) ja rem (jakojäännös), jotka ovat molemmat samaa tietotyyppiä kuin parametrit. Kenttien järjestystä tai mahdollisia muita kenttiä ei ole standardissa määritetty. n = quot * d + rem. Osamäärä pyöristyy nollaa kohti, eli esim. div(-1, 3).quot == 0, div(-1, 3).rem == -1.

Monitavuisten merkkien apufunktiot

Funktio	Selitys
int mblen(const char *m, size_t n);	Palauttaa monitavuisen merkin pituuden tavuina. Jos m ei ole NULL, merkki luetaan merkkijonosta m, josta luetaan enintään n tavua. Palauttaa 0, jos merkkijono on päättynyt, ja -1, mikäli monitavuinen merkki on kelvoton. Tällä funktiolla on mahdollisesti sisäinen tila. Se voidaan nollata antamalla m = NULL. Tällöin funktio palauttaa nollan, jos funktiolla ei ole sisäistä tilaa, ja muuten jonkin muun arvon.
int mbtowc(wchar_t *l, const char *m, size_t n);	Muuntaa monitavuisen merkin leveäksi merkiksi. Jos m ei ole NULL, merkki luetaan merkkijonosta m, josta luetaan enintään n tavua. Palauttaa luetun monitavuisen merkin pituuden merkkeinä (enintään MB_CUR_MAX). Palauttaa 0, jos merkkijono on päättynyt, ja -1, mikäli monitavuinen merkki on kelvoton. Jos l ei ole NULL, leveä merkki säilötään osoittimen osoittamaan muistipaikkaan, tai muuten funktio palauttaa vain pituuden. Tällä funktiolla on mahdollisesti sisäinen tila. Se voidaan nollata antamalla m = NULL. Tällöin funktio palauttaa nollan, jos funktiolla ei ole sisäistä tilaa, ja muuten jonkin muun arvon.
int wctomb(char *m, wchar_t l);	Muuntaa leveän merkin monitavuiseksi merkiksi. Jos m ei ole NULL, muunnettu merkki sijoitetaan sen osoittamaan muistipaikkaan. Palauttaa kirjoitetun monitavuisen merkin pituuden merkkeinä (enintään MB_CUR_MAX), tai -1, jos muunnos ei onnistu (esim. kyseistä merkkiä ei voi esittää). Tällä funktiolla on mahdollisesti sisäinen tila. Se voidaan nollata antamalla m = NULL. Tällöin funktio palauttaa nollan, jos funktiolla ei ole sisäistä tilaa, ja muuten jonkin muun arvon.
size_t mbstowcs(wchar_t *l, const char *m, size_t n);	Muuntaa monitavuisia merkkejä sisältävän merkkijonon leveitä merkkejä käyttäväksi merkkijonoksi. n vastaa merkkijonossa l olevaa tilaa (sinne mahtuu n leveää merkkiä). Palauttaa, montako leveää merkkiä kirjoitettiin, tai -1, jos muunnos ei onnistunut (esim. kelvoton merkki). Leveään merkkijonoon ei sijoiteta nollamerkkiä eli loppumerkkiä, mikäli n leveää merkkiä kirjoitettiin. Tällä funktiolla on mahdollisesti sisäinen tila.
size_t wcstombs(char *m, const wchar_t *l, size_t n);	Muuntaa leveitä merkkejä käyttävän merkkijonon monitavuisia merkkejä sisältäväksi merkkijonoksi. n vastaa merkkijonossa m olevaa tilaa (sinne mahtuu n merkkiä). Palauttaa, montako merkkiä kirjoitettiin, tai -1, jos muunnos ei onnistunut (esim. leveä merkki, jota ei voi esittää monitavuisena). Tulosmerkkijonoon ei sijoiteta nollamerkkiä eli loppumerkkiä, mikäli n merkkiä kirjoitettiin. Tällä funktiolla on mahdollisesti sisäinen tila.