Ogni linguaggio di programmazione ha le proprie librerie standard e solitamente ogni linguaggio ha delle documentazione in cui viene data una descrizione di ogni funzione nella libreria standard.

Per esempio in java la documentazione è reperibile online, ossia (almeno per la versione 12), qui.

Ed in C? Esiste un manuale? Ovviamente sì!

Molto semplicemente, il manuale di ogni funzione in C è in realtà il man di linux!

In sintesi, è possibile accedere alla descrizione di una particolare funzione C aprendo il terminale e scrivendo man 3 <nome_funzione> o, per funzioni di sistema man 2 <nome_funzione>. il 3 od il 2 sono fissi.

Supponiamo di voler cercare la documentazione relativa a atoi. Per farlo, apriamo il terminale (Ctrl + Alt + T) e scriviamo:

man 3 atoi

Abbiamo scritto man 3 atoi e non man 2 atoi perché atoi non è una funzione importantissima per il sistema operativo.

Il risultato è il seguente

Solitamente in una entry di un manuale, sono essenziali le seguenti informazioni:

• header: indica quale header file bisogna includere per poter utilizzare senza problemi la funzione (in questo caso stdlib);
• signature: indica quali sono gli input e l'output della funzione;
• descrizione: contiene informazioni spesso importanti per capire come la funzione opera;
• return value: indica la semantica del valore di ritorno della funzione stessa.

Spesso alcune funzioni necessitano di soddisfare alcune precondizioni. Per esempio consideriamo la funzione asprintf (man 3 asprintf):

Come si può vedere il man specifica che è necessario definire la macro _GNU_SOURCE prima di includere l'header relativo, in questo caso stdio.h

Alcune funzioni sono essenziali per il sistema operativo e meritano di stare in una sezione del man a parte. Per esempio la funzione C stat permette di reperire informazioni riguardanti un file in particolare. Usare man 3 stat non darà alcun risultato (siccome la funzione è essenziale per il sistema operativo). Per accedere alla relativa documentazione, è necessario eseguire man 2 stat:

Come si può vedere questa funzione può essere usata con sicurezza solo includendo 3 differenti header files. Inoltre è essenziale per capire il risultato di stat stessa.

Perché a volte bisogna usare man 2 <funzione> ed a volte man 3 <funzione>. Il motivo è che il manuale letto da man ha varie sezioni, ognuna in cui sono contenute particolari descrizioni. In particolare la sezione 3 contiene tutte le descrizioni relative alla funzioni C, mentre 2 contiene le descrizioni delle "system calls". Se non si sceglie alcun numero, di default il man usa la sezione 1.

• Spiegazioni man page;