Spostato il vecchi myhost.c e creato nuovo programma mygetaddr per provare
[gapil.git] / sockctrl.tex
1 %% sockctrl.tex
2 %%
3 %% Copyright (C) 2004 Simone Piccardi.  Permission is granted to
4 %% copy, distribute and/or modify this document under the terms of the GNU Free
5 %% Documentation License, Version 1.1 or any later version published by the
6 %% Free Software Foundation; with the Invariant Sections being "Prefazione",
7 %% with no Front-Cover Texts, and with no Back-Cover Texts.  A copy of the
8 %% license is included in the section entitled "GNU Free Documentation
9 %% License".
10 %%
11 \chapter{La gestione dei socket}
12 \label{cha:sock_generic_management}
13
14 Esamineremo in questo capitolo una serie di funzionalità aggiuntive relative
15 alla gestione dei socket, come la gestione della risoluzione di nomi e
16 indirizzi, le impostazioni delle varie proprietà ed opzioni relative ai
17 socket, e le funzioni di controllo che permettono di modificarne il
18 comportamento.
19
20
21 \section{La risoluzione dei nomi}
22 \label{sec:sock_name_resolution}
23
24 Negli esempi dei capitoli precedenti abbiamo sempre identificato le singole
25 macchine attraverso indirizzi numerici, sfruttando al più le funzioni di
26 conversione elementare illustrate in sez.~\ref{sec:sock_addr_func} che
27 permettono di passare da un indirizzo espresso in forma \textit{dotted
28   decimal} ad un numero. Vedremo in questa sezione le funzioni utilizzate per
29 poter utilizzare dei nomi simbolici al posto dei valori numerici, e viceversa
30 quelle che permettono di ottenere i nomi simbolici associati ad indirizzi,
31 porte o altre proprietà del sistema.
32
33
34 \subsection{La struttura del \textit{resolver}}
35 \label{sec:sock_resolver}
36
37 La risoluzione dei nomi è associata tradizionalmente al servizio del
38 \textit{Domain Name Service} che permette di identificare le macchine su
39 internet invece che per numero IP attraverso il relativo \textsl{nome a
40   dominio}.\footnote{non staremo ad entrare nei dettagli della definizione di
41   cosa è un nome a dominio, dandolo per noto, una introduzione alla
42   problematica si trova in \cite{AGL} (cap. 9) mentre per una trattazione
43   approfondita di tutte le problematiche relative al DNS si può fare
44   riferimento a \cite{DNSbind}.} In realtà per DNS si intendono spesso i
45 server che forniscono su internet questo servizio, mentre nel nostro caso
46 affronteremo la problematica dal lato client, di un qualunque programma che
47 necessita di compiere questa operazione.
48
49 \begin{figure}[htb]
50   \centering
51   \includegraphics[width=10cm]{img/resolver}
52   \caption{Schema di funzionamento delle routine del \textit{resolver}.}
53   \label{fig:sock_resolver_schema}
54 \end{figure}
55
56 Inoltre quella fra nomi a dominio e indirizzi IP non è l'unica corrispondenza
57 possibile fra nomi simbolici e valori numerici, come abbiamo visto anche in
58 sez.~\ref{sec:sys_user_group} per le corrispondenze fra nomi di utenti e
59 gruppi e relativi identificatori numerici; per quanto riguarda però tutti i
60 nomi associati a identificativi o servizi relativi alla rete il servizio di
61 risoluzione è gestito in maniera unificata da un insieme di routine fornite
62 con le librerie del C, detto appunto \textit{resolver}.
63
64 Lo schema di funzionamento del \textit{resolver} è illustrato in
65 fig.~\ref{fig:sock_resolver_schema}; in sostanza i programmi hanno a
66 disposizione un insieme di funzioni di libreria con cui chiamano il
67 \textit{resolver}, indicate con le frecce nere. Ricevuta la richiesta è
68 quest'ultimo che, sulla base della sua configurazione, esegue le operazioni
69 necessarie a fornire la risposta, che possono essere la lettura delle
70 informazioni mantenute nei relativi dei file statici presenti sulla macchina,
71 una interrogazione ad un DNS (che a sua volta, per il funzionamento del
72 protocollo, può interrogarne altri) o la richiesta ad altri server per i quali
73 sia fornito il supporto, come LDAP.\footnote{la sigla LDAP fa riferimento ad
74   un protocollo, il \textit{Lightweight Directory Access Protocol}, che
75   prevede un meccanismo per la gestione di \textsl{elenchi} di informazioni
76   via rete; il contenuto di un elenco può essere assolutamente generico, e
77   questo permette il mantenimento dei più vari tipi di informazioni su una
78   infrastruttura di questo tipo.}
79
80 La configurazione del \textit{resolver} attiene più alla amministrazione di
81 sistema che alla programmazione, ciò non di meno, prima di trattare le varie
82 funzioni di librerie utilizzate dai programmi, vale la pena fare una
83 panoramica generale.  Originariamente la configurazione del \textit{resolver}
84 riguardava esclusivamente le questioni relative alla gestione dei nomi a
85 dominio, e prevedeva solo l'utilizzo del DNS e del file statico
86 \file{/etc/hosts}.
87
88 Per questo aspetto il file di configurazione principale del sistema è
89 \file{/etc/resolv.conf} che contiene in sostanza l'elenco degli indirizzi IP
90 dei server DNS da contattare; a questo si affianca il file
91 \file{/etc/host.conf} il cui scopo principale è indicare l'ordine in cui
92 eseguire la risoluzione dei nomi (se usare prima i valori di \file{/etc/hosts}
93 o quelli del DNS). Tralasciamo i dettagli relativi alle varie direttive che
94 possono essere usate in questi file, che si trovano nelle rispettive pagine di
95 manuale.
96
97 Con il tempo però è divenuto possibile fornire diversi sostituti per
98 l'utilizzo delle associazione statiche in \file{/etc/hosts}, inoltre oltre
99 alla risoluzione dei nomi a dominio ci sono anche altri nomi da risolvere,
100 come quelli che possono essere associati ad una rete (invece che ad una
101 singola macchina) o ai gruppi di macchine definiti dal servizio
102 NIS,\footnote{il \textit{Network Information Service} è un servizio, creato da
103   Sun, e poi diffuso su tutte le piattaforme unix-like, che permette di
104   raggruppare all'interno di una rete (in quelli che appunto vengono chiamati
105   \textit{netgroup}) varie macchine, centralizzando i servizi di definizione
106   di utenti e gruppi e di autenticazione, oggi è sempre più spesso sostituito
107   da LDAP.} o come quelli dei protocolli e dei servizi che sono mantenuti nei
108 file statici \file{/etc/protocols} e \file{/etc/services}.  Molte di queste
109 informazioni non si trovano su un DNS, ma in una rete locale può essere molto
110 utile centralizzare il mantenimento di alcune di esse su opportuni server.
111 Inoltre l'uso di diversi supporti possibili per le stesse informazioni (ad
112 esempio il nome delle macchine può essere mantenuto sia tramite
113 \file{/etc/hosts}, che con il DNS, che con NIS) comporta il problema
114 dell'ordine in cui questi vengono interrogati.\footnote{con le implementazioni
115   classiche i vari supporti erano introdotti modificando direttamente le
116   funzioni di libreria, prevedendo un ordine di interrogazione predefinito e
117   non modificabile (a meno di una ricompilazione delle librerie stesse).}
118
119 Per risolvere questa serie di problemi la risoluzione dei nomi a dominio
120 eseguirà dal \textit{resolver} è stata inclusa all'interno di un meccanismo
121 generico per la risoluzione di corrispondenze fra nomi ed informazioni ad essi
122 associate chiamato \textit{Name Service Switch}\footnote{il sistema è stato
123   introdotto la prima volta nelle librerie standard di Solaris, le \acr{glibc}
124   hanno ripreso lo stesso schema, si tenga presente che questo sistema non
125   esiste per altre librerie standard come le \acr{libc5} o le \acr{uclib}.}
126 cui abbiamo accennato anche in sez.~\ref{sec:sys_user_group} per quanto
127 riguarda la gestione dei dati associati a utenti e gruppi.  Il \textit{Name
128   Service Switch} (cui spesso si fa riferimento con l'acronimo NSS) è un
129 sistema di librerie dinamiche che permette di definire in maniera generica sia
130 i supporti su cui mantenere i dati di corrispondenza fra nomi e valori
131 numerici, sia l'ordine in cui effettuare le ricerche sui vari supporti
132 disponibili. Il sistema prevede una serie di possibili classi di
133 corrispondenza, quelle attualmente definite sono riportate in
134 tab.~\ref{tab:sys_NSS_classes}.
135
136 \begin{table}[htb]
137   \footnotesize
138   \centering
139   \begin{tabular}[c]{|l|p{8cm}|}
140     \hline
141     \textbf{Classe} & \textbf{Tipo di corrispondenza}\\
142     \hline
143     \hline
144     \texttt{shadow}   & corrispondenze fra username e proprietà dell'utente
145                        (\acr{uid}, ecc.).\\  
146     \texttt{group}    & corrispondenze fra nome del gruppo e proprietà dello 
147                         stesso.\\  
148     \texttt{aliases}  & alias per la posta elettronica\\ 
149     \texttt{ethers}   & corrispondenze fra numero IP e MAC address della
150                         scheda di rete.\\ 
151     \texttt{hosts}    & corrispondenze fra nome a dominio e numero IP.\\ 
152     \texttt{netgroup} & corrispondenze gruppo di rete e macchine che lo
153                         compongono.\\  
154     \texttt{networks} & corrispondenze fra nome di una rete e suo indirizzo
155                         IP.\\  
156     \texttt{protocols}& corrispondenze fra nome di un protocollo e relativo
157                         numero identificativo.\\ 
158     \texttt{rpc}      & corrispondenze fra nome di un servizio RPC e relativo 
159                         numero identificativo.\\ 
160     \texttt{services} & corrispondenze fra nome di un servizio e numero di
161                         porta. \\ 
162     \hline
163   \end{tabular}
164   \caption{Le diverse classi di corrispondenze definite
165     all'interno del \textit{Name Service Switch}.} 
166   \label{tab:sys_NSS_classes}
167 \end{table}
168
169 Il sistema  del \textit{Name Service  Switch} è controllato dal  contenuto del
170 file \file{/etc/nsswitch.conf}; questo contiene una riga\footnote{seguendo una
171   convezione  comune per  i  file  di configurazione  le  righe vuote  vengono
172   ignorate  e  tutto  quello  che  segue un  carattere  ``\texttt{\#}''  viene
173   considerato un  commento.} di configurazione per ciascuna  di queste classi,
174 che  viene inizia  col nome  di tab.~\ref{tab:sys_NSS_classes}  seguito  da un
175 carattere ``\texttt{:}'' e  prosegue con la lista dei  \textsl{servizi} su cui
176 le  relative informazioni sono  raggiungibili, scritti  nell'ordine in  cui si
177 vuole siano interrogati.
178
179 Ogni  servizio è  specificato  a sua  volta  da un  nome, come  \texttt{file},
180 \texttt{dns},  \texttt{db},  ecc.  che  identifica la  libreria  dinamica  che
181 realizza l'interfaccia  con esso. Per  ciascun servizio se \texttt{NAME}  è il
182 nome  utilizzato  dentro   \file{/etc/nsswitch.conf},  dovrà  essere  presente
183 (usualmente  in   \file{/lib})  una  libreria   \texttt{libnss\_NAME}  che  ne
184 implementa le funzioni.
185
186 In ogni caso, qualunque sia la modalità con cui ricevono i dati o il supporto
187 su cui vengono mantenuti, e che si usino o meno funzionalità aggiuntive
188 fornire dal sistema del \textit{Name Service Switch}, dal punto di vista di un
189 programma che deve effettuare la risoluzione di un nome a dominio, tutto
190 quello che conta sono le funzioni classiche che il \textit{resolver} mette a
191 disposizione,\footnote{è cura della implementazione fattane nelle \acr{glibc}
192   tenere conto della presenza del \textit{Name Service Switch}.} e sono queste
193 quelle che tratteremo nelle sezioni successive.
194
195
196 \subsection{Le funzioni di interrogazione del \textit{resolver}}
197 \label{sec:sock_resolver_functions}
198
199 Prima di trattare le funzioni usate normalmente nella risoluzione dei nomi a
200 dominio conviene trattare in maniera più dettagliata il meccanismo principale
201 da esse utilizzato e cioè quello del servizio DNS. Come accennato questo,
202 benché in teoria sia solo uno dei possibili supporti su cui mantenere le
203 informazioni, in pratica costituisce il meccanismo principale con cui vengono
204 risolti i nomi a dominio.  Per questo motivo esistono una serie di funzioni di
205 libreria che servono specificamente ad eseguire delle interrogazioni verso un
206 server DNS, funzioni che poi vengono utilizzate per realizzare le funzioni
207 generiche di libreria usate anche dal sistema del \textit{resolver}.
208
209 Il sistema del DNS è in sostanza di un database distribuito organizzato in
210 maniera gerarchica, i dati vengono mantenuti in tanti server distinti ciascuno
211 dei quali si occupa della risoluzione del proprio \textsl{dominio}; i nomi a
212 dominio sono organizzati in una struttura ad albero analoga a quella
213 dell'albero dei file, con domini di primo livello (come i \texttt{.org}),
214 secondo livello (come \texttt{.truelite.it}), ecc.  In questo caso le
215 separazioni sono fra i vari livelli sono definite dal carattere ``\texttt{.}''
216 ed i nomi devono essere risolti da destra verso sinistra.\footnote{per chi si
217   stia chiedendo quale sia la radice di questo albero, cioè l'equivalente di
218   ``\texttt{/}'', la risposta è il dominio speciale ``\texttt{.}'', che in
219   genere non viene mai scritto esplicitamente, ma che, come chiunque abbia
220   configurato un server DNS sa bene, esiste ed è gestito dai cosiddetti
221   \textit{root DNS} che risolvono i domini di primo livello.} Il meccanismo
222 funziona con il criterio della \textsl{delegazione}, un server responsabile
223 per un dominio di primo livello può delegare la risoluzione degli indirizzi
224 per un suo dominio di secondo livello ad un altro server, il quale a sua volta
225 potrà delegare la risoluzione di un eventuale sottodominio di terzo livello ad
226 un altro server ancora.
227
228 In realtà un server DNS è in grado di fare altro rispetto alla risoluzione di
229 un nome a dominio in un indirizzo IP; ciascuna voce nel database viene
230 chiamata \textit{resource record}, e può contenere diverse informazioni. In
231 genere i \textit{resource record} vengono classificati per la \textsl{classe
232   di indirizzi} cui i dati contenuti fanno riferimento, e per il \textsl{tipo}
233 di questi ultimi.\footnote{ritroveremo classi di indirizzi e tipi di record
234   più avanti in tab.~\ref{tab:DNS_address_class} e
235   tab.~\ref{tab:DNS_record_type}.}  Oggigiorno i dati mantenuti nei server DNS
236 sono quasi esclusivamente relativi ad indirizzi internet, per cui in pratica
237 viene utilizzata soltanto una classe di indirizzi; invece le corrispondenze
238 fra un nome a dominio ed un indirizzo IP sono solo uno fra i vari tipi di
239 informazione che un server DNS fornisce normalmente.
240
241 L'esistenza di vari tipi di informazioni è un altro dei motivi per cui il
242 \textit{resolver} prevede, rispetto a quelle relative alla semplice
243 risoluzione dei nomi, un insieme di funzioni specifiche dedicate
244 all'interrogazione di un server DNS; la prima di queste funzioni è
245 \funcd{res\_init}, il cui prototipo è:
246 \begin{functions}
247   \headdecl{netinet/in.h} \headdecl{arpa/nameser.h} \headdecl{resolv.h}
248   \funcdecl{int res\_init(void)}
249
250 Inizializza il sistema del \textit{resolver}.
251
252 \bodydesc{La funzione restituisce 0 in caso di successo e -1 in caso di
253   errore.}
254 \end{functions}
255
256 La funzione legge il contenuto dei file di configurazione (i già citati
257 \file{resolv.conf} e \file{host.conf}) per impostare il dominio di default,
258 gli indirizzi dei server DNS da contattare e l'ordine delle ricerche; se non
259 sono specificati server verrà utilizzato l'indirizzo locale, e se non è
260 definito un dominio di default sarà usato quello associato con l'indirizzo
261 locale (ma questo può essere sovrascritto con l'uso della variabile di
262 ambiente \texttt{LOCALDOMAIN}). In genere non è necessario eseguire questa
263 funzione direttamente in quanto viene automaticamente chiamata la prima volta
264 che si esegue una delle altre.
265
266 Le impostazioni e lo stato del \textit{resolver} vengono mantenuti in una
267 serie di variabili raggruppate nei campi di una apposita struttura \var{\_res}
268 usata da tutte queste funzioni. Essa viene definita in \file{resolv.h} ed è
269 utilizzata internamente alle funzioni essendo definita come variabile globale;
270 questo consente anche di accedervi direttamente all'interno di un qualunque
271 programma, una volta che la sia opportunamente dichiarata come:
272 \includecodesnip{listati/resolv_option.c}
273
274 Tutti i campi della struttura sono ad uso interno, e vengono usualmente
275 inizializzati da \func{res\_init} in base al contenuto dei file di
276 configurazione e ad una serie di valori di default. L'unico campo che può
277 essere utile modificare è \var{\_res.options}, una maschera binaria che
278 contiene una serie di bit di opzione che permettono di controllare il
279 comportamento del \textit{resolver}. 
280
281 \begin{table}[htb]
282   \centering
283   \footnotesize
284   \begin{tabular}[c]{|l|p{8cm}|}
285     \hline
286     \textbf{Costante} & \textbf{Significato} \\
287     \hline
288     \hline
289     \const{RES\_INIT}       & viene attivato se è stata chiamata
290                               \func{res\_init}. \\
291     \const{RES\_DEBUG}      & stampa dei messaggi di debug.\\
292     \const{RES\_AAONLY}     & accetta solo risposte autoritative.\\
293     \const{RES\_USEVC}      & usa connessioni TCP per contattare i server 
294                               invece che l'usuale UDP.\\
295     \const{RES\_PRIMARY}    & interroga soltanto server DNS primari.
296                               \\
297     \const{RES\_IGNTC}      & ignora gli errori di troncamento, non ritenta la
298                               richiesta con una connessione TCP.\\
299     \const{RES\_RECURSE}    & imposta il bit che indica che si desidera
300                               eseguire una interrogazione ricorsiva.\\
301     \const{RES\_DEFNAMES}   & se attivo \func{res\_search} aggiunge il nome
302                               del dominio di default ai nomi singoli (che non
303                               contengono cioè un ``\texttt{.}'').\\
304     \const{RES\_STAYOPEN}   & usato con \const{RES\_USEVC} per mantenere
305                               aperte le connessioni TCP fra interrogazioni
306                               diverse. \\
307     \const{RES\_DNSRCH}     & se attivo \func{res\_search} esegue le ricerche
308                               di nomi di macchine nel dominio corrente o nei
309                               domini ad esso sovrastanti.\\
310     \const{RES\_INSECURE1}  & blocca i controlli di sicurezza di tipo 1.\\
311     \const{RES\_INSECURE2}  & blocca i controlli di sicurezza di tipo 2.\\
312     \const{RES\_NOALIASES}  & blocca l'uso della variabile di ambiente
313                               \texttt{HOSTALIASES}.\\ 
314     \const{RES\_USE\_INET6} & restituisce indirizzi IPv6 con
315                               \func{gethostbyname}. \\
316     \const{RES\_ROTATE}     & ruota la lista dei server DNS dopo ogni
317                               interrogazione.\\
318     \const{RES\_NOCHECKNAME}& non controlla i nomi per verificarne la
319                               correttezza sintattica. \\
320     \const{RES\_KEEPTSIG}   & non elimina i record di tipo \texttt{TSIG}.\\
321     \const{RES\_BLAST}      & \\
322     \const{RES\_DEFAULT}    & è l'insieme di \const{RES\_RECURSE},
323                               \const{RES\_DEFNAMES} e \const{RES\_DNSRCH}.\\
324     \hline
325   \end{tabular}
326   \caption{Costanti utilizzabili come valori per \var{\_res.options}.}
327   \label{tab:resolver_option}
328 \end{table}
329
330 Per utilizzare questa funzionalità per modificare le impostazioni direttamente
331 da programma occorrerà impostare un opportuno valore per questo campo ed
332 invocare esplicitamente \func{res\_init}, dopo di che le altre funzioni
333 prenderanno le nuove impostazioni. Le costanti che definiscono i vari bit di
334 questo campo, ed il relativo significato sono illustrate in
335 tab.~\ref{tab:resolver_option}; trattandosi di una maschera binaria un valore
336 deve essere espresso con un opportuno OR aritmetico di dette costanti; ad
337 esempio il valore di default delle opzioni, espresso dalla costante
338 \const{RES\_DEFAULT}, è definito come:
339 \includecodesnip{listati/resolv_option_def.c}
340
341 Non tratteremo il significato degli altri campi non essendovi necessità di
342 modificarli direttamente; gran parte di essi sono infatti impostati dal
343 contenuto dei file di configurazione, mentre le funzionalità controllate da
344 alcuni di esse possono essere modificate con l'uso delle opportune variabili
345 di ambiente come abbiamo visto per \texttt{LOCALDOMAIN}. In particolare con
346 \texttt{RES\_RETRY} si soprassiede il valore del campo \var{retry} che
347 controlla quante volte viene ripetuto il tentativo di connettersi ad un server
348 DNS prima di dichiarare fallimento; il valore di default è 4, un valore nullo
349 significa bloccare l'uso del DNS. Infine con \texttt{RES\_TIMEOUT} si
350 soprassiede il valore del campo \var{retrans},\footnote{preimpostato al valore
351   della omonima costante \const{RES\_TIMEOUT} di \file{resolv.h}.} che è il
352 valore preso come base (in numero di secondi) per definire la scadenza di una
353 richiesta, ciascun tentativo di richiesta fallito viene ripetuto raddoppiando
354 il tempo di scadenza per il numero massimo di volte stabilito da
355 \texttt{RES\_RETRY}.
356
357 La funzione di interrogazione principale è \funcd{res\_query}, che serve ad
358 eseguire una richiesta ad un server DNS per un nome a dominio
359 \textsl{completamente specificato} (quello che si chiama FQDN, \textit{Fully
360   Qualified Domain Name}); il suo prototipo è:
361
362 \begin{functions}
363 \headdecl{netinet/in.h}
364 \headdecl{arpa/nameser.h}
365 \headdecl{resolv.h}
366 \funcdecl{int res\_query(const char *dname, int class, int type,
367               unsigned char *answer, int anslen)}
368
369   Esegue una interrogazione al DNS.
370
371 \bodydesc{La funzione restituisce un valore positivo pari alla lunghezza dei
372     dati scritti nel buffer \param{answer} in caso di successo e -1 in caso di
373     errore.}
374 \end{functions}
375
376 La funzione esegue una interrogazione ad un server DNS relativa al nome da
377 risolvere passato nella stringa indirizzata da \param{dname}, inoltre deve
378 essere specificata la classe di indirizzi in cui eseguire la ricerca con
379 \param{class}, ed il tipo di \textit{resource record} che si vuole ottenere
380 con \param{type}. Il risultato della ricerca verrà scritto nel buffer di
381 lunghezza \param{anslen} puntato da \param{answer} che si sarà opportunamente
382 allocato in precedenza.
383
384
385 Una seconda funzione di ricerca, analoga a \func{res\_query}, che prende gli
386 stessi argomenti, ma che esegue l'interrogazione con le funzionalità
387 addizionali previste dalle due opzioni \const{RES\_DEFNAMES} e
388 \const{RES\_DNSRCH}, è \funcd{res\_search}, il cui prototipo è:
389 \begin{functions}
390 \headdecl{netinet/in.h}
391 \headdecl{arpa/nameser.h}
392 \headdecl{resolv.h}
393 \funcdecl{int res\_search(const char *dname, int class, int type,
394               unsigned char *answer, int anslen)}
395
396   Esegue una interrogazione al DNS.
397   
398   \bodydesc{La funzione restituisce un valore positivo pari alla lunghezza dei
399     dati scritti nel buffer \param{answer} in caso di successo e -1 in caso di
400     errore.}
401 \end{functions}
402
403 In sostanza la funzione ripete una serie di chiamate a \func{res\_query}
404 aggiungendo al nome contenuto nella stringa \param{dname} il dominio di
405 default da cercare, fermandosi non appena trova un risultato.  Il risultato di
406 entrambe le funzioni viene scritto nel formato opportuno (che sarà diverso a
407 seconda del tipo di record richiesto) nel buffer di ritorno; sarà compito del
408 programma (o di altre funzioni) estrarre i relativi dati, esistono una serie
409 di funzioni interne usate per la scansione di questi dati, per chi fosse
410 interessato una trattazione dettagliata è riportata nel quattordicesimo
411 capitolo di \cite{DNSbind}.
412
413 Le classi di indirizzi supportate da un server DNS sono tre, ma di queste in
414 pratica oggi viene utilizzata soltanto quella degli indirizzi internet; le
415 costanti che identificano dette classi, da usare come valore per l'argomento
416 \param{class} delle precedenti funzioni, sono riportate in
417 tab.~\ref{tab:DNS_address_class}.\footnote{esisteva in realtà anche una classe
418   \const{C\_CSNET} per la omonima rete, ma è stata dichiarata obsoleta.}
419
420 \begin{table}[htb]
421   \centering
422   \footnotesize
423   \begin{tabular}[c]{|l|p{8cm}|}
424     \hline
425     \textbf{Costante} & \textbf{Significato} \\
426     \hline
427     \hline
428     \const{C\_IN}   & indirizzi internet, in pratica i soli utilizzati oggi.\\
429     \const{C\_HS}   & indirizzi \textit{Hesiod}, utilizzati solo al MIT, oggi
430                       completamente estinti. \\
431     \const{C\_CHAOS}& indizzi per la rete \textit{Chaosnet}, un'altra rete
432                       sperimentale nata al MIT. \\
433     \const{C\_ANY}  & indica un indirizzo di classe qualunque.\\
434     \hline
435   \end{tabular}
436   \caption{Costanti identificative delle classi di indirizzi per l'argomento
437     \param{class} di \func{res\_query}.}
438   \label{tab:DNS_address_class}
439 \end{table}
440
441 Come accennato le tipologie di dati che sono mantenibili su un server DNS sono
442 diverse, ed a ciascuna di essa corrisponde un diverso tipo di \textit{resource
443   record}. L'elenco delle costanti\footnote{ripreso dai file di dichiarazione
444   \file{arpa/nameser.h} e \file{arpa/nameser\_compat.h}.} che definiscono i
445 valori che si possono usare per l'argomento \param{type} per specificare il
446 tipo di \textit{resource record} da richiedere è riportato in
447 tab.~\ref{tab:DNS_record_type}; le costanti (tolto il \texttt{T\_} iniziale)
448 hanno gli stessi nomi usati per identificare i record nei file di zona di
449 BIND,\footnote{BIND, acronimo di \textit{Berkley Internet Name Domain}, è una
450   implementazione di un server DNS, ed, essendo utilizzata nella stragrande
451   maggioranza dei casi, fa da riferimento; i dati relativi ad un certo
452   dominio (cioè i suoi \textit{resource record} vengono mantenuti in quelli
453   che sono usualmente chiamati \textsl{file di zona}, e in essi ciascun tipo
454   di dominio è identificato da un nome che è appunto identico a quello delle
455   costanti di tab.~\ref{tab:DNS_record_type} senza il \texttt{T\_} iniziale.}
456 e che normalmente sono anche usati come nomi per indicare i record.
457
458 \begin{table}[!htb]
459   \centering
460   \footnotesize
461   \begin{tabular}[c]{|l|l|}
462     \hline
463     \textbf{Costante} & \textbf{Significato} \\
464     \hline
465     \hline
466     \const{T\_A}     & indirizzo di una stazione.\\
467     \const{T\_NS}    & server DNS autoritativo per il dominio richiesto.\\
468     \const{T\_MD}    & destinazione per la posta elettronica.\\
469     \const{T\_MF}    & redistributore per la posta elettronica.\\
470     \const{T\_CNAME} & nome canonico.\\
471     \const{T\_SOA}   & inizio di una zona di autorità.\\
472     \const{T\_MB}    & nome a dominio di una casella di posta.\\
473     \const{T\_MG}    & nome di un membro di un gruppo di posta.\\
474     \const{T\_MR}    & nome di un cambiamento di nome per la posta.\\
475     \const{T\_NULL}  & record nullo.\\
476     \const{T\_WKS}   & servizio noto.\\
477     \const{T\_PTR}   & risoluzione inversa di un indirizzo numerico.\\
478     \const{T\_HINFO} & informazione sulla stazione.\\
479     \const{T\_MINFO} & informazione sulla casella di posta.\\
480     \const{T\_MX}    & server cui instradare la posta per il dominio.\\
481     \const{T\_TXT}   & stringhe di testo (libere).\\
482     \const{T\_RP}    & nome di un responsabile (\textit{responsible person}).\\
483     \const{T\_AFSDB} & database per una cella AFS.\\
484     \const{T\_X25}   & indirizzo di chiamata per X.25.\\
485     \const{T\_ISDN}  & indirizzo di chiamata per ISDN.\\
486     \const{T\_RT}    & router.\\
487     \const{T\_NSAP}  & indirizzo NSAP.\\
488     \const{T\_NSAP\_PTR}& risoluzione inversa per NSAP (deprecato).\\
489     \const{T\_SIG}   & firma digitale di sicurezza.\\
490     \const{T\_KEY}   & chiave per firma.\\
491     \const{T\_PX}    & corrispondenza per la posta X.400.\\
492     \const{T\_GPOS}  & posizione geografica.\\
493     \const{T\_AAAA}  & indirizzo IPv6.\\
494     \const{T\_LOC}   & informazione di collocazione.\\
495     \const{T\_NXT}   & dominio successivo.\\
496     \const{T\_EID}   & identificatore di punto conclusivo.\\
497     \const{T\_NIMLOC}& posizionatore \textit{nimrod}.\\
498     \const{T\_SRV}   & servizio.\\
499     \const{T\_ATMA}  & indirizzo ATM.\\
500     \const{T\_NAPTR} & puntatore ad una \textit{naming authority} .\\
501     \const{T\_TSIG}  & firma di transazione.\\
502     \const{T\_IXFR}  & trasferimento di zona incrementale.\\
503     \const{T\_AXFR}  & trasferimento di zona di autorità.\\
504     \const{T\_MAILB} & trasferimento di record di caselle di posta.\\
505     \const{T\_MAILA} & trasferimento di record di server di posta.\\
506     \const{T\_ANY}   & valore generico.\\
507     \hline
508   \end{tabular}
509   \caption{Costanti identificative del tipo di record per l'argomento
510     \param{type} di \func{res\_query}.}
511   \label{tab:DNS_record_type}
512 \end{table}
513
514
515 L'elenco di tab.~\ref{tab:DNS_record_type} è quello di \textsl{tutti} i
516 \textit{resource record} definiti, con una breve descrizione del relativo
517 significato.  Di tutti questi però viene impiegato correntemente solo un
518 piccolo sottoinsieme, alcuni sono obsoleti ed altri fanno riferimento a dati
519 applicativi che non ci interessano non avendo nulla a che fare con la
520 risoluzione degli indirizzi IP, pertanto non entreremo nei dettagli del
521 significato di tutti i \textit{resource record}, ma solo di quelli usati dalle
522 funzioni del \textit{resolver}. Questi sono sostanzialmente i seguenti (per
523 indicarli si è usata la notazione dei file di zona di BIND):
524 \begin{basedescript}{\desclabelwidth{1.2cm}\desclabelstyle{\nextlinelabel}}
525 \item[\texttt{A}] viene usato per indicare la corrispondenza fra un nome a
526   dominio ed un indirizzo IPv4; ad esempio la corrispondenza fra
527   \texttt{dodds.truelite.it} e l'indirizzo IP \texttt{62.48.34.25}.
528 \item[\texttt{AAAA}] viene usato per indicare la corrispondenza fra un nome a
529   dominio ed un indirizzo IPv6; è chiamato in questo modo dato che la
530   dimensione di un indirizzo IPv6 è quattro volte quella di un indirizzo IPv4.
531 \item[\texttt{PTR}] per fornire la corrispondenza inversa fra un indirizzo IP
532   ed un nome a dominio ad esso associato si utilizza questo tipo di record (il
533   cui nome sta per \textit{pointer}).
534 \item[\texttt{CNAME}] qualora si abbiamo più nomi che corrispondono allo
535   stesso indirizzo (come ad esempio \texttt{www.truelite.it}, o
536   \texttt{sources.truelite.it}, che fanno sempre riferimento a
537   \texttt{dodds.truelite.it}) si può usare questo tipo di record per creare
538   degli \textit{alias} in modo da associare un qualunque altro nome al
539   \textsl{nome canonico} della macchina (si chiama così quello associato al
540   record \texttt{A}).
541 \end{basedescript}
542
543 Come accennato in caso di successo le due funzioni di richiesta restituiscono
544 il risultato della interrogazione al server, in caso di insuccesso l'errore
545 invece viene segnalato da un valore di ritorno pari a -1, ma in questo caso,
546 non può essere utilizzata la variabile \var{errno} per riportare un codice di
547 errore, in quanto questo viene impostato per ciascuna delle chiamate al
548 sistema utilizzate dalle funzioni del \textit{resolver}, non avrà alcun
549 significato nell'indicare quale parte del procedimento di risoluzione è
550 fallita.
551
552 Per questo motivo è stata definita una variabile di errore separata,
553 \var{h\_errno}, che viene utilizzata dalle funzioni del \textit{resolver} per
554 indicare quale problema ha causato il fallimento della risoluzione del nome.
555 Ad essa si può accedere una volta che la si dichiara con:
556 \includecodesnip{listati/herrno.c} 
557 ed i valori che può assumere, con il relativo significato, sono riportati in
558 tab.~\ref{tab:h_errno_values}.
559
560 \begin{table}[!htb]
561   \centering
562   \footnotesize
563   \begin{tabular}[c]{|l|p{10cm}|}
564     \hline
565     \textbf{Costante} & \textbf{Significato} \\
566     \hline
567     \hline
568     \const{HOST\_NOT\_FOUND} & l'indirizzo richiesto non è valido e la
569                                macchina indicata è sconosciuta. \\
570     \const{NO\_ADDRESS}      & il nome a dominio richiesto è valido, ma non ha
571                                un indirizzo associato ad esso
572                                (alternativamente può essere indicato come 
573                                \const{NO\_DATA}). \\
574     \const{NO\_RECOVERY}     & si è avuto un errore non recuperabile
575                                nell'interrogazione di un server DNS. \\
576     \const{TRY\_AGAIN}       & si è avuto un errore temporaneo
577                                nell'interrogazione di un server DNS, si può
578                                ritentare l'interrogazione in un secondo
579                                tempo. \\
580     \hline
581   \end{tabular}
582   \caption{Valori possibili della variabile \var{h\_errno}.}
583   \label{tab:h_errno_values}
584 \end{table}
585
586 Insieme alla nuova variabile vengono definite anche due nuove funzioni per
587 stampare l'errore a video, analoghe a quelle di sez.~\ref{sec:sys_strerror}
588 per \var{errno}, ma che usano il valore di \var{h\_errno}; la prima è
589 \funcd{herror} ed il suo prototipo è:
590 \begin{functions}
591 \headdecl{netdb.h}
592 \funcdecl{void herror(const char *string)}
593
594 Stampa un errore di risoluzione.
595 \end{functions}
596
597 La funzione è l'analoga di \func{perror} e stampa sullo standard error un
598 messaggio di errore corrispondente al valore corrente di \var{h\_errno}, a cui
599 viene anteposta la stringa \param{string} passata come argomento.  La seconda
600 funzione è \funcd{hstrerror} ed il suo prototipo è:
601 \begin{functions}
602 \headdecl{netdb.h}
603 \funcdecl{const char *hstrerror(int err)}
604
605 Restituisce una stringa corrispondente ad un errore di risoluzione.
606 \end{functions}
607 \noindent che, come  l'analoga \func{strerror}, restituisce una stringa con un
608 messaggio di errore già formattato, corrispondente al codice passato come
609 argomento (che si presume sia dato da \var{h\_errno}).
610
611
612
613
614 \subsection{La risoluzione dei nomi a dominio}
615 \label{sec:sock_name_services}
616
617 La principale funzionalità del \textit{resolver} resta quella di risolvere i
618 nomi a dominio in indirizzi IP, per cui non ci dedicheremo oltre alle funzioni
619 di richiesta generica ed esamineremo invece le funzioni a questo dedicate. La
620 prima funzione è \funcd{gethostbyname} il cui scopo è ottenere l'indirizzo di
621 una stazione noto il suo nome a dominio, il suo prototipo è:
622 \begin{prototype}{netdb.h}
623 {struct hostent *gethostbyname(const char *name)}
624
625 Determina l'indirizzo associato al nome a dominio \param{name}.
626
627 \bodydesc{La funzione restituisce in caso di successo il puntatore ad una
628   struttura di tipo \struct{hostent} contenente i dati associati al nome a
629   dominio, o un puntatore nullo in caso di errore.}
630 \end{prototype}
631
632 La funzione prende come argomento una stringa \param{name} contenente il nome
633 a dominio che si vuole risolvere, in caso di successo i dati ad esso relativi
634 vengono memorizzati in una opportuna struttura \struct{hostent} la cui
635 definizione è riportata in fig.~\ref{fig:sock_hostent_struct}. 
636
637 \begin{figure}[!htb]
638   \footnotesize \centering
639   \begin{minipage}[c]{15cm}
640     \includestruct{listati/hostent.h}
641   \end{minipage}
642   \caption{La struttura \structd{hostent} per la risoluzione dei nomi a
643     dominio e degli indirizzi IP.}
644   \label{fig:sock_hostent_struct}
645 \end{figure}
646
647 Quando un programma chiama \func{gethostbyname} e questa usa il DNS per
648 effettuare la risoluzione del nome, è con i valori contenuti nei relativi
649 record che vengono riempite le varie parti della struttura \struct{hostent}.
650 Il primo campo della struttura, \var{h\_name} contiene sempre il \textsl{nome
651   canonico}, che nel caso del DNS è appunto il nome associato ad un record
652 \texttt{A}. Il secondo campo della struttura, \var{h\_aliases}, invece è un
653 puntatore ad vettore di puntatori, terminato da un puntatore nullo. Ciascun
654 puntatore del vettore punta ad una stringa contenente uno degli altri
655 possibili nomi associati allo stesso \textsl{nome canonico} (quelli che nel
656 DNS vengono inseriti come record di tipo \texttt{CNAME}).
657
658 Il terzo campo della struttura, \var{h\_addrtype}, indica il tipo di indirizzo
659 che è stato restituito, e può assumere soltanto i valori \const{AF\_INET} o
660 \const{AF\_INET6}, mentre il quarto campo, \var{h\_length}, indica la
661 lunghezza dell'indirizzo stesso in byte. 
662
663 Infine il campo \var{h\_addr\_list} è il puntatore ad un vettore di puntatori
664 ai singoli indirizzi; il vettore è terminato da un puntatore nullo.  Inoltre,
665 come illustrato in fig.~\ref{fig:sock_hostent_struct}, viene definito il campo
666 \var{h\_addr} come sinonimo di \code{h\_addr\_list[0]}, cioè un riferimento
667 diretto al primo indirizzo della lista.
668
669 Oltre ai normali nomi a dominio la funzione accetta come argomento
670 \param{name} anche indirizzi numerici, in formato dotted decimal per IPv4 o
671 con la notazione illustrata in sez.~\ref{sec:IP_ipv6_notation} per IPv6. In
672 tal caso \func{gethostbyname} non eseguirà nessuna interrogazione remota, ma
673 si limiterà a copiare la stringa nel campo \var{h\_name} ed a creare la
674 corrispondente struttura \var{in\_addr} da indirizzare con
675 \code{h\_addr\_list[0]}.
676
677 Con l'uso di \func{gethostbyname} normalmente si ottengono solo gli indirizzi
678 IPv4, se si vogliono ottenere degli indirizzi IPv6 occorrerà prima impostare
679 l'opzione \const{RES\_USE\_INET6} nel campo \texttt{\_res.options} e poi
680 chiamare \func{res\_init} (vedi sez.~\ref{sec:sock_resolver_functions}) per
681 modificare le opzioni del resolver; dato che questo non è molto comodo è stata
682 definita\footnote{questa è una estensione fornita dalle \acr{glibc},
683   disponibile anche in altri sistemi unix-like.} un'altra funzione,
684 \funcd{gethostbyname2}, il cui prototipo è:
685 \begin{functions}
686   \headdecl{netdb.h} 
687   \headdecl{sys/socket.h}
688   \funcdecl{struct hostent *gethostbyname2(const char *name, int af)}
689
690 Determina l'indirizzo di tipo \param{af} associato al nome a dominio
691 \param{name}.
692
693 \bodydesc{La funzione restituisce in caso di successo il puntatore ad una
694   struttura di tipo \struct{hostent} contenente i dati associati al nome a
695   dominio, o un puntatore nullo in caso di errore.}
696 \end{functions}
697
698 In questo caso la funzione prende un secondo argomento \param{af} che indica
699 (i soli valori consentiti sono \const{AF\_INET} o \const{AF\_INET6}, per
700 questo è necessario l'uso di \texttt{sys/socket.h}) la famiglia di indirizzi
701 che dovrà essere utilizzata nei risultati restituiti dalla funzione. Per tutto
702 il resto la funzione è identica a \func{gethostbyname}, ed identici sono i
703 suoi risultati.
704
705 \begin{figure}[!htb]
706   \footnotesize \centering
707   \begin{minipage}[c]{15cm}
708     \includecodesample{listati/mygethost.c}
709   \end{minipage}
710   \normalsize
711   \caption{Esempio di codice per la risoluzione di un indirizzo.}
712   \label{fig:mygethost_example}
713 \end{figure}
714
715 Vediamo allora un primo esempio dell'uso delle funzioni di risoluzione, in
716 fig.~\ref{fig:mygethost_example} è riportato un estratto del codice di un
717 programma che esegue una semplice interrogazione al \textit{resolver} usando
718 \func{gethostbyname} e poi ne stampa a video i risultati. Al solito il
719 sorgente completo, che comprende il trattamento delle opzioni ed una funzione
720 per stampare un messaggio di aiuto, è nel file \texttt{mygethost.c} dei
721 sorgenti allegati alla guida.
722
723 Il programma richiede un solo argomento che specifichi il nome da cercare,
724 senza il quale (\texttt{\small 12--15}) esce con un errore. Dopo di che
725 (\texttt{\small 16}) si limita a chiamare \func{gethostbyname}, ricevendo il
726 risultato nel puntatore \var{data}. Questo (\texttt{\small 17--20}) viene
727 controllato per rilevare eventuali errori, nel qual caso il programma esce
728 dopo aver stampato un messaggio con \func{herror}. 
729
730 Se invece la risoluzione è andata a buon fine si inizia (\texttt{\small 21})
731 con lo stampare il nome canonico, dopo di che (\texttt{\small 22--26}) si
732 stampano eventuali altri nomi. Per questo prima (\texttt{\small 22}) si prende
733 il puntatore alla cima della lista che contiene i nomi e poi (\texttt{\small
734   23--26}) si esegue un ciclo che sarà ripetuto fin tanto che nella lista si
735 troveranno dei puntatori validi\footnote{si ricordi che la lista viene
736   terminata da un puntatore nullo.} per le stringhe dei nomi; prima
737 (\texttt{\small 24}) si stamperà la stringa e poi (\texttt{\small 25}) si
738 provvederà ad incrementare il puntatore per passare al successivo elemento
739 della lista.
740
741 Una volta stampati i nomi si passerà a stampare gli indirizzi, il primo passo
742 (\texttt{\small 27--34}) è allora quello di riconoscere il tipo di indirizzo
743 sulla base del valore del campo \var{h\_addrtype}, stampandolo a video. Si è
744 anche previsto di stampare un errore nel caso (che non dovrebbe mai accadere)
745 di un indirizzo non valido.
746
747 Infine (\texttt{\small 35--40}) si stamperanno i valori degli indirizzi, di
748 nuovo (\texttt{\small 35}) si inizializzerà un puntatore alla cima della lista
749 e si eseguirà un ciclo fintanto che questo punterà ad indirizzi validi in
750 maniera analoga a quanto fatto in precedenza per i nomi a dominio. Si noti
751 come, essendo il campo \var{h\_addr\_list} un puntatore ad strutture di
752 indirizzi generiche, questo sia ancora di tipo \texttt{char **} e si possa
753 riutilizzare lo stesso puntatore usato per i nomi.
754
755 Per ciascun indirizzo valido si provvederà (\texttt{\small 37}) ad una
756 conversione con la funzione \func{inet\_ntop} (vedi
757 sez.~\ref{sec:sock_addr_func}) passandole gli opportuni argomenti, questa
758 restituirà la stringa da stampare (\texttt{\small 38}) con il valore
759 dell'indirizzo in \var{buffer}, che si è avuto la cura di dichiarare
760 inizialmente (\texttt{\small 10}) con dimensioni adeguate; dato che la
761 funzione è in grado di tenere conto automaticamente del tipo di indirizzo non
762 ci sono precauzioni particolari da prendere.\footnote{volendo essere pignoli
763   si dovrebbe controllarne lo stato di uscita, lo si è tralasciato per non
764   appesantire il codice, dato che in caso di indirizzi non validi si sarebbe
765   avuto un errore con \func{gethostbyname}, ma si ricordi che la sicurezza non
766   è mai troppa.}
767
768 Le funzioni illustrate finora hanno un difetto: utilizzando una area di
769 memoria interna per allocare i contenuti della struttura \struct{hostent} non
770 possono essere rientranti. Questo comporta anche che in due successive
771 chiamate i dati potranno essere sovrascritti. Si tenga presente poi che
772 copiare il contenuto della sola struttura non è sufficiente per salvare tutti
773 i dati, in quanto questa contiene puntatori ad altri dati, che pure possono
774 essere sovrascritti; per questo motivo, se si vuole salvare il risultato di
775 una chiamata, occorrerà eseguire quella che si chiama una
776 \index{\textit{deep~copy}}\textit{deep copy}.\footnote{si chiama così quella
777   tecnica per cui, quando si deve copiare il contenuto di una struttura
778   complessa (con puntatori che puntano ad altri dati, che a loro volta possono
779   essere puntatori ad altri dati) si deve copiare non solo il contenuto della
780   struttura, ma eseguire una scansione per risolvere anche tutti i puntatori
781   contenuti in essa (e così via se vi sono altre sottostrutture con altri
782   puntatori) e copiare anche i dati da questi referenziati.}
783
784 Per ovviare a questi problemi nelle \acr{glibc} sono definite anche delle
785 versioni rientranti delle precedenti funzioni, al solito queste sono
786 caratterizzate dall'avere un suffisso \texttt{\_r}, pertanto avremo le due
787 funzioni \funcd{gethostbyname\_r} e \funcd{gethostbyname2\_r} i cui prototipi
788 sono:
789 \begin{functions}
790   \headdecl{netdb.h} 
791   \headdecl{sys/socket.h}
792   \funcdecl{int gethostbyname\_r(const char *name, struct hostent *ret, 
793     char *buf, size\_t buflen, struct hostent **result, int *h\_errnop)}
794   \funcdecl{int gethostbyname2\_r(const char *name, int af,
795          struct hostent *ret, char *buf, size\_t buflen, 
796          struct hostent **result, int *h\_errnop)}
797   
798   Versioni rientranti delle funzioni \func{gethostbyname} e
799   \func{gethostbyname2}. 
800        
801   \bodydesc{Le funzioni restituiscono 0 in caso di successo ed un valore
802     negativo in caso di errore.}
803 \end{functions}
804
805 Gli argomenti \param{name} (e \param{af} per \func{gethostbyname2\_r}) hanno
806 lo stesso significato visto in precedenza. Tutti gli altri argomenti hanno lo
807 stesso significato per entrambe le funzioni. Per evitare l'uso di variabili
808 globali si dovrà allocare preventivamente una struttura \struct{hostent} in
809 cui ricevere il risultato, passandone l'indirizzo alla funzione nell'argomento
810 \param{ret}.  Inoltre, dato che \struct{hostent} contiene dei puntatori, dovrà
811 essere allocato anche un buffer in cui le funzioni possano scrivere tutti i
812 dati del risultato dell'interrogazione da questi puntati; l'indirizzo e la
813 lunghezza di questo buffer devono essere indicati con gli argomenti
814 \param{buf} e \param{buflen}.
815
816 Gli ultimi due argomenti vengono utilizzati per avere indietro i risultati
817 come \index{\textit{value~result~argument}}\textit{value result argument}, si
818 deve specificare l'indirizzo della variabile su cui la funzione dovrà salvare
819 il codice di errore con \param{h\_errnop} e quello su cui dovrà salvare il
820 puntatore che si userà per accedere i dati con \param{result}.
821
822 In caso di successo entrambe le funzioni restituiscono un valore nullo,
823 altrimenti restituiscono un codice di errore negativo e all'indirizzo puntato
824 da \param{result} sarà salvato un puntatore nullo, mentre a quello puntato da
825 \param{h\_errnop} sarà salvato il valore del codice di errore, dato che per
826 essere rientrante la funzione non può la variabile globale \var{h\_errno}. In
827 questo caso il codice di errore, oltre ai valori di
828 tab.~\ref{tab:h_errno_values}, può avere anche quello di \errcode{ERANGE}
829 qualora il buffer allocato su \param{buf} non sia sufficiente a contenere i
830 dati, in tal caso si dovrà semplicemente ripetere l'esecuzione della funzione
831 con un buffer di dimensione maggiore.
832
833 Una delle caratteristiche delle interrogazioni al servizio DNS è che queste
834 sono normalmente eseguite con il protocollo UDP, ci sono casi in cui si
835 preferisce che vengano usate connessioni permanenti con il protocollo TCP. Per
836 ottenere questo\footnote{si potrebbero impostare direttamente le opzioni di
837   \var{\_\_res.options}, ma queste funzioni permettono di semplificare la
838   procedura.} sono previste delle funzioni apposite; la prima è
839 \funcd{sethostent}, il cui prototipo è:
840 \begin{prototype}{netdb.h}
841 {void sethostent(int stayopen)}
842
843 Richiede l'uso di connessioni per le interrogazioni ad un server DNS.
844
845 \bodydesc{La funzione non restituisce nulla.}
846 \end{prototype}
847
848 La funzione permette di richiedere l'uso di connessioni TCP per la richiesta
849 dei dati, e che queste restino aperte per successive richieste. Il valore
850 dell'argomento \param{stayopen} indica se attivare questa funzionalità, un
851 valore pari a 1 (o diverso da zero), che indica una condizione vera in C,
852 attiva la funzionalità.  Come si attiva l'uso delle connessioni TCP lo si può
853 disattivare con la funzione \funcd{endhostent}; il suo prototipo è:
854 \begin{prototype}{netdb.h}
855 {void endhostent(void)}
856
857 Disattiva l'uso di connessioni per le interrogazioni ad un server DNS.
858
859 \bodydesc{La funzione non restituisce nulla.}
860 \end{prototype}
861 \noindent e come si può vedere la funzione è estremamente semplice, non
862 richiedendo nessun argomento.
863
864
865 Infine si può richiedere la risoluzione inversa di un indirizzo IP od IPv6,
866 per ottenerne il nome a dominio ad esso associato, per fare questo si può
867 usare la funzione \funcd{gethostbyaddr}, il cui prototipo è:
868 \begin{functions}
869   \headdecl{netdb.h} 
870   \headdecl{sys/socket.h} 
871   \funcdecl{struct hostent *gethostbyaddr(const char *addr, int len, int type)}
872
873   Richiede la risoluzione inversa di un indirizzo IP.
874        
875   \bodydesc{La funzione restituisce l'indirizzo ad una struttura
876     \struct{hostent} in caso di successo ed \const{NULL} in caso di errore.}
877 \end{functions}
878
879 In questo caso l'argomento \param{addr} dovrà essere il puntatore ad una
880 appropriata struttura contenente il valore dell'indirizzo IP (o IPv6) che si
881 vuole risolvere. L'uso del tipo \type{char *} per questo argomento è storico,
882 il dato dovrà essere fornito in una struttura \struct{in\_addr}\footnote{si
883   ricordi che, come illustrato in fig.~\ref{fig:sock_sa_ipv4_struct}, questo
884   in realtà corrisponde ad un numero intero, da esprimere comunque in
885   \textit{network order}, non altrettanto avviene però per \var{in6\_addr},
886   pertanto è sempre opportuno inizializzare questi indirizzi con
887   \func{inet\_pton} (vedi sez.~\ref{sec:sock_conv_func_gen}).}  per un
888 indirizzo IPv4 ed una struttura \struct{in6\_addr} per un indirizzo IPv6,
889 mentre in \param{len} se ne dovrà specificare la dimensione (rispettivamente 4
890 o 16), infine l'argomento \param{type} indica il tipo di indirizzo e dovrà
891 essere o \const{AF\_INET} o \const{AF\_INET6}.
892
893 La funzione restituisce, in caso di successo, un puntatore ad una struttura
894 \struct{hostent}, solo che in questo caso la ricerca viene eseguita
895 richiedendo al DNS un record di tipo \texttt{PTR} corrispondente all'indirizzo
896 specificato. In caso di errore al solito viene usata la variabile
897 \var{h\_errno} per restituire un opportuno codice. In questo caso l'unico
898 campo del risultato che interessa è \var{h\_name} che conterrà il nome a
899 dominio, la funziona comunque inizializza anche il primo campo della lista
900 \var{h\_addr\_list} col valore dell'indirizzo passato come argomento.
901
902 Per risolvere il problema dell'uso da parte delle due funzioni
903 \func{gethostbyname} e \func{gethostbyaddr} di memoria statica che può essere
904 sovrascritta fra due chiamate successive, e per avere sempre la possibilità di
905 indicare esplicitamente il tipo di indirizzi voluto (cosa che non è possibile
906 con \func{gethostbyname}), vennero introdotte due nuove funzioni di
907 risoluzione,\footnote{le funzioni sono presenti nelle \acr{glibc} versione
908   2.1.96, ma essendo considerate deprecate (vedi
909   sez.~\ref{sec:sock_advanced_name_services}) sono state rimosse nelle
910   versioni successive.} \funcd{getipnodebyname} e \funcd{getipnodebyaddr}, i
911 cui prototipi sono:
912 \begin{functions}
913   \headdecl{netdb.h} 
914   \headdecl{sys/types.h} 
915   \headdecl{sys/socket.h} 
916
917   \funcdecl{struct hostent *getipnodebyname(const char *name, int af, int
918     flags, int *error\_num)} 
919
920   \funcdecl{struct hostent *getipnodebyaddr(const void *addr, size\_t len,
921     int af, int *error\_num)}
922
923   Richiedono rispettivamente la risoluzione e la risoluzione inversa di un
924   indirizzo IP.
925        
926   \bodydesc{Entrambe le funzioni restituiscono l'indirizzo ad una struttura
927     \struct{hostent} in caso di successo ed \const{NULL} in caso di errore.}
928 \end{functions}
929
930 Entrambe le funzioni supportano esplicitamente la scelta di una famiglia di
931 indirizzi con l'argomento \param{af} (che può assumere i valori
932 \const{AF\_INET} o \const{AF\_INET6}), e restituiscono un codice di errore
933 (con valori identici a quelli precedentemente illustrati in
934 tab.~\ref{tab:h_errno_values}) nella variabile puntata da \param{error\_num}.
935 La funzione \func{getipnodebyaddr} richiede poi che si specifichi l'indirizzo
936 come per \func{gethostbyaddr} passando anche la lunghezza dello stesso
937 nell'argomento \param{len}.
938
939 La funzione \func{getipnodebyname} prende come primo argomento il nome da
940 risolvere, inoltre prevede un apposito argomento \param{flags}, da usare come
941 maschera binaria, che permette di specificarne il comportamento nella
942 risoluzione dei diversi tipi di indirizzi (IPv4 e IPv6); ciascun bit
943 dell'argomento esprime una diversa opzione, e queste possono essere specificate
944 con un OR aritmetico delle costanti riportate in
945 tab.~\ref{tab:sock_getipnodebyname_flags}.
946
947 \begin{table}[!htb]
948   \centering
949   \footnotesize
950   \begin{tabular}[c]{|l|p{10cm}|}
951     \hline
952     \textbf{Costante} & \textbf{Significato} \\
953     \hline
954     \hline
955     \const{AI\_V4MAPPED}  & usato con \const{AF\_INET6} per richiedere una
956                             ricerca su un indirizzo IPv4 invece che IPv6; gli
957                             eventuali risultati saranno rimappati su indirizzi 
958                             IPv6.\\
959     \const{AI\_ALL}       & usato con \const{AI\_V4MAPPED}; richiede sia
960                             indirizzi IPv4 che IPv6, e gli indirizzi IPv4
961                             saranno rimappati in IPv6.\\
962     \const{AI\_ADDRCONFIG}& richiede che una richiesta IPv4 o IPv6 venga
963                             eseguita solo se almeno una interfaccia del
964                             sistema è associata ad un indirizzo di tale tipo.\\
965     \const{AI\_DEFAULT}   & il valore di default, è equivalente alla
966                             combinazione di \const{AI\_ADDRCONFIG} e di
967                             \const{AI\_V4MAPPED)}.\\  
968     \hline
969   \end{tabular}
970   \caption{Valori possibili per i bit dell'argomento \param{flags} della
971     funzione \func{getipnodebyname}.}
972   \label{tab:sock_getipnodebyname_flags}
973 \end{table}
974
975 Entrambe le funzioni restituiscono un puntatore ad una struttura \var{hostent}
976 che contiene i risultati della ricerca, che viene allocata dinamicamente
977 insieme a tutto lo spazio necessario a contenere i dati in essa referenziati;
978 per questo motivo queste funzioni non soffrono dei problemi dovuti all'uso di
979 una sezione statica di memoria presenti con le precedenti \func{gethostbyname}
980 e \func{gethostbyaddr}.  L'uso di una allocazione dinamica però comporta anche
981 la necessità di deallocare esplicitamente la memoria occupata dai risultati
982 una volta che questi non siano più necessari; a tale scopo viene fornita la
983 funzione \funcd{freehostent}, il cui prototipo è:
984 \begin{functions}
985   \headdecl{netdb.h} 
986   \headdecl{sys/types.h} 
987   \headdecl{sys/socket.h} 
988
989   \funcdecl{void freehostent(struct hostent *ip)} 
990
991   Disalloca una struttura \var{hostent}.
992        
993   \bodydesc{La funzione non ritorna nulla.}
994 \end{functions}
995
996 La funzione permette di disallocare una struttura \var{hostent}
997 precedentemente allocata in una chiamata di \func{getipnodebyname} o
998 \func{getipnodebyaddr}, e prende come argomento l'indirizzo restituito da una
999 di queste funzioni.
1000
1001 Infine per concludere la nostra panoramica sulle funzioni di risoluzione dei
1002 nomi dobbiamo citare le funzioni che permettono di interrogare gli altri
1003 servizi di risoluzione dei nomi illustrati in sez.~\ref{sec:sock_resolver}; in
1004 generale infatti ci sono una serie di funzioni nella forma
1005 \texttt{getXXXbyname} e \texttt{getXXXbyaddr} per ciascuna delle informazioni
1006 di rete mantenute dal \textit{Name Service Switch} che permettono
1007 rispettivamente di trovare una corrispondenza cercando per nome o per numero.
1008
1009 L'elenco di queste funzioni è riportato nelle colonne finali di
1010 tab.~\ref{tab:name_resolution_functions}, dove le si sono suddivise rispetto
1011 al tipo di informazione che forniscono (riportato in prima colonna). Nella
1012 tabella si è anche riportato il file su cui vengono ordinariamente mantenute
1013 queste informazioni, che però può essere sostituito da un qualunque supporto
1014 interno al \textit{Name Service Switch} (anche se usualmente questo avviene
1015 solo per la risoluzione degli indirizzi). Ciascuna funzione fa riferimento ad
1016 una sua apposita struttura che contiene i relativi dati, riportata in terza
1017 colonna.
1018
1019 \begin{table}[!htb]
1020   \centering
1021   \footnotesize
1022   \begin{tabular}[c]{|l|l|l|l|l|}
1023     \hline
1024     \textbf{Informazione}&\textbf{File}&\textbf{Struttura}&
1025     \multicolumn{2}{|c|}{\textbf{Funzioni}}\\
1026     \hline
1027     \hline
1028     indirizzo&\file{/etc/hosts}&\struct{hostent}&\func{gethostbyname}&
1029              \func{gethostbyaddr}\\ 
1030     servizio &\file{/etc/services}&\struct{servent}&\func{getservbyname}&
1031              \func{getservbyaddr}\\ 
1032     rete     &\file{/etc/networks}&\struct{netent}&\func{getnetbyname}&
1033              \func{getnetbyaddr}\\ 
1034     protocollo&\file{/etc/protocols}&\struct{protoent}&\func{getprotobyname}&
1035               \func{getprotobyaddr}\\ 
1036     \hline
1037   \end{tabular}
1038   \caption{Funzioni di risoluzione dei nomi per i vari servizi del
1039     \textit{Name Service Switch}.}
1040   \label{tab:name_resolution_functions}
1041 \end{table}
1042
1043 Delle funzioni di tab.~\ref{tab:name_resolution_functions} abbiamo trattato
1044 finora soltanto quelle relative alla risoluzione dei nomi, dato che sono le
1045 più usate, e prevedono praticamente da sempre la necessità di rivolgersi ad
1046 una entità esterna; per le altre invece, estensioni fornite dal NSS a parte,
1047 si fa sempre riferimento ai dati mantenuti nei rispettivi file. 
1048
1049 Dopo la risoluzione dei nomi a dominio una delle ricerche più comuni è quella
1050 sui nomi dei servizi noti (cioè \texttt{http}, \texttt{smtp}, ecc.) da
1051 associare alle rispettive porte, le due funzioni da utilizzare per questo sono
1052 \funcd{getservbyname} e \funcd{getservbyaddr}, che permettono rispettivamente
1053 di ottenere il numero di porta associato ad un servizio dato il nome e
1054 viceversa; i loro prototipi sono:
1055 \begin{functions}
1056   \headdecl{netdb.h} 
1057   \funcdecl{struct servent *getservbyname(const char *name, const char *proto)}
1058   \funcdecl{struct servent *getservbyport(int port, const char *proto)} 
1059
1060   Risolvono il nome di un servizio nel rispettivo numero di porta e viceversa.
1061        
1062   \bodydesc{Ritornano il puntatore ad una struttura \struct{servent} con i
1063     risultati in caso di successo, o \const{NULL} in caso di errore.}
1064 \end{functions}
1065
1066 Entrambe le funzioni prendono come ultimo argomento una stringa \param{proto}
1067 che indica il protocollo per il quale si intende effettuare la
1068 ricerca,\footnote{le informazioni mantenute in \file{/etc/services} infatti
1069   sono relative sia alle porte usate su UDP che su TCP, occorre quindi
1070   specificare a quale dei due protocolli si fa riferimento.} che nel caso si
1071 IP può avere come valori possibili solo \texttt{udp} o
1072 \texttt{tcp};\footnote{in teoria si potrebbe avere un qualunque protocollo fra
1073   quelli citati in \file{/etc/protocols}, posto che lo stesso supporti il
1074   concetto di \textsl{porta}, in pratica questi due sono gli unici presenti.}
1075 se si specifica un puntatore nullo la ricerca sarà eseguita su un protocollo
1076 qualsiasi.
1077
1078 Il primo argomento è il nome del servizio per \func{getservbyname},
1079 specificato tramite la stringa \param{name}, mentre \func{getservbyport}
1080 richiede il numero di porta in \param{port}. Entrambe le funzioni eseguono una
1081 ricerca sul file \file{/etc/services}\footnote{il \textit{Name Service Switch}
1082   astrae il concetto a qualunque supporto su cui si possano mantenere i
1083   suddetti dati. } ed estraggono i dati dalla prima riga che corrisponde agli
1084 argomenti specificati; se la risoluzione ha successo viene restituito un
1085 puntatore ad una apposita struttura \struct{servent} contenente tutti i
1086 risultati), altrimenti viene restituito un puntatore nullo.  Si tenga presente
1087 che anche in questo caso i dati vengono mantenuti in una area di memoria
1088 statica e che quindi la funzione non è rientrante.
1089
1090 \begin{figure}[!htb]
1091   \footnotesize \centering
1092   \begin{minipage}[c]{15cm}
1093     \includestruct{listati/servent.h}
1094   \end{minipage}
1095   \caption{La struttura \structd{servent} per la risoluzione dei nomi dei
1096     servizi e dei numeri di porta.}
1097   \label{fig:sock_servent_struct}
1098 \end{figure}
1099
1100 La definizione della struttura \struct{servent} è riportata in
1101 fig.~\ref{fig:sock_servent_struct}, il primo campo, \var{s\_name} contiene
1102 sempre il nome canonico del servizio, mentre \var{s\_aliases} è un puntatore
1103 ad un vettore di stringhe contenenti gli eventuali nomi alternativi
1104 utilizzabili per identificare lo stesso servizio. Infine \var{s\_port}
1105 contiene il numero di porta e \var{s\_proto} il nome del protocollo.
1106
1107 Come riportato in tab.~\ref{tab:name_resolution_functions} ci sono analoghe
1108 funzioni per la risoluzione del nome dei protocolli e delle reti; non staremo
1109 a descriverle nei dettagli, in quanto il loro uso è molto limitato, esse
1110 comunque hanno una struttura del tutto analoga alle precedenti, e tutti i
1111 dettagli relativi al loro funzionamento possono essere trovati nelle
1112 rispettive pagine di manuale.
1113
1114 Oltre alle funzioni di ricerca esistono delle ulteriori funzioni che prevedono
1115 una lettura sequenziale delle informazioni mantenute nel \textit{Name Service
1116   Switch} (in sostanza permettono di leggere i file contenenti le informazioni
1117 riga per riga), che sono analoghe a quelle elencate in
1118 tab.~\ref{tab:sys_passwd_func} per le informazioni relative ai dati degli
1119 utenti e dei gruppi.  Nel caso specifico dei servizi avremo allora le tre
1120 funzioni \funcd{setservent}, \funcd{getservent} e \funcd{endservent} i cui
1121 prototipi sono:
1122 \begin{functions}
1123   \headdecl{netdb.h} 
1124   \funcdecl{void setservent(int stayopen)} 
1125   Apre il file \file{/etc/services} e si posiziona al suo inizio.
1126
1127   \funcdecl{struct servent *getservent(void)}
1128   Legge la voce successiva nel file \file{/etc/services}.      
1129
1130   \funcdecl{void endservent(void)} 
1131   Chiude il file \file{/etc/services}.
1132
1133   \bodydesc{Le due funzioni \func{setservent} e \func{endservent} non
1134     restituiscono nulla, \func{getservent} restituisce il puntatore ad una
1135     struttura \struct{servent} in caso di successo e \const{NULL} in caso di
1136     errore o fine del file.}
1137 \end{functions}
1138
1139 La prima funzione, \func{getservent}, legge una singola voce a partire dalla
1140 posizione corrente in \file{/etc/services}, pertanto si può eseguire una
1141 lettura sequenziale dello stesso invocandola più volte. Se il file non è
1142 aperto provvede automaticamente ad aprirlo, nel qual caso leggerà la prima
1143 voce. La seconda funzione, \func{setservent}, permette di aprire il file
1144 \file{/etc/services} per una successiva lettura, ma se il file è già stato
1145 aperto riporta la posizione di lettura alla prima voce del file, in questo
1146 modo si può far ricominciare da capo una lettura sequenziale. L'argomento
1147 \param{stayopen}, se diverso da zero, fa sì che il file resti aperto anche fra
1148 diverse chiamate a \func{getservbyname} e \func{getservbyaddr}.\footnote{di
1149   default dopo una chiamata a queste funzioni il file viene chiuso, cosicchè
1150   una successiva chiamata a \func{getservent} riparte dall'inizio.}  La terza
1151 funzione, \funcd{endservent}, provvede semplicemente a chiudere il file.
1152
1153 Queste tre funzioni per la lettura sequenziale di nuovo sono presenti per
1154 ciascuno dei vari tipi di informazione relative alle reti di
1155 tab.~\ref{tab:name_resolution_functions}; questo significa che esistono
1156 altrettante funzioni nella forma \texttt{setXXXent}, \texttt{getXXXent} e
1157 \texttt{endXXXent}, analoghe alle precedenti per la risoluzione dei servizi,
1158 che abbiamo riportato in tab.~\ref{tab:name_sequential_read}.  Essendo, a
1159 parte il tipo di informazione che viene trattato, sostanzialmente identiche
1160 nel funzionamento e di scarso utilizzo, non staremo a trattarle una per una,
1161 rimandando alle rispettive pagine di manuale.
1162
1163 \begin{table}[!htb]
1164   \centering
1165   \footnotesize
1166   \begin{tabular}[c]{|l|l|l|l|}
1167     \hline
1168     \textbf{Informazione}&\multicolumn{3}{|c|}{\textbf{Funzioni}}\\
1169     \hline
1170     \hline
1171     indirizzo&\func{sethostent}&\func{gethostent}&\func{endhostent} \\
1172     servizio &cd te\func{setservent}&\func{getservent}&\func{endservent}\\ 
1173     rete     &\func{setnetent}&\func{getnetent}&\func{endnetent}\\ 
1174     protocollo&\func{setprotoent}&\func{getprotoent}&\func{endprotoent}\\ 
1175     \hline
1176   \end{tabular}
1177   \caption{Funzioni lettura sequenziale dei dati del \textit{Name Service
1178       Switch}.} 
1179   \label{tab:name_sequential_read}
1180 \end{table}
1181
1182
1183
1184
1185
1186 \subsection{Le funzioni avanzate per la risoluzione dei nomi}
1187 \label{sec:sock_advanced_name_services}
1188
1189 Quelle illustrate nella sezione precedente sono le funzioni classiche per la
1190 risoluzione di nomi ed indirizzi IP, ma abbiamo già visto come esse soffrano
1191 di vari inconvenienti come il fatto che usano informazioni statiche, e non
1192 prevedono la possibilità di avere diverse classi di indirizzi. Anche se sono
1193 state create delle estensioni o metodi diversi che permettono di risolvere
1194 alcuni di questi inconvenienti,\footnote{rimane ad esempio il problema
1195   generico che si deve sapere in anticipo quale tipo di indirizzi IP (IPv4 o
1196   IPv6) corrispondono ad un certo nome a dominio.}  comunque esse non
1197 forniscono una interfaccia sufficientemente generica.
1198
1199 Inoltre in genere quando si ha a che fare con i socket non esiste soltanto il
1200 problema della risoluzione del nome che identifica la macchina, ma anche
1201 quello del servizio a cui ci si vuole rivolgere.  Per questo motivo con lo
1202 standard Posix 1003.1-2001 sono state indicate come deprecate le varie
1203 funzioni \func{gethostbyaddr}, \func{gethostbyname}, \var{getipnodebyname} e
1204 \var{getipnodebyaddr} ed è stata introdotta una interfaccia completamente
1205 nuova.
1206
1207 La prima funzione di questa interfaccia è \funcd{getaddrinfo}, che combina le
1208 funzionalità delle precedenti \func{getipnodebyname}, \func{getipnodebyaddr},
1209 \func{getservbyname} e \func{getservbyport}, consentendo di ottenere
1210 contemporaneamente sia la risoluzione di un indirizzo simbolico che del nome
1211 un servizio; il suo prototipo è:
1212 \begin{functions}
1213   \headdecl{netdb.h} 
1214   \headdecl{sys/socket.h} 
1215   \headdecl{netdb.h} 
1216
1217   \funcdecl{int getaddrinfo(const char *node, const char *service, const
1218     struct addrinfo *hints, struct addrinfo **res)}
1219
1220   Esegue una risoluzione di un nome a dominio e di un nome di servizio.
1221
1222   \bodydesc{La funzione restituisce 0 in caso di successo o un codice di
1223     errore diverso da zero in caso di fallimento.}
1224 \end{functions}
1225
1226 La funzione prende come primo argomento il nome della macchina che si vuole
1227 risolvere, specificato tramite la stringa \param{node}. Questo argomento,
1228 oltre ad un comune nome a dominio, può indicare anche un indirizzo numerico in
1229 forma \textit{dotted-decimal} per IPv4 o in formato esadecimale per IPv6.  Si
1230 può anche specificare il nome di una rete invece che di una singola macchina.
1231 Il secondo argomento, \param{service}, specifica invece il nome del servizio
1232 che si intende risolvere. Per uno dei due argomenti si può anche usare il
1233 valore \const{NULL}, nel qual caso la risoluzione verrà effettuata utilizzando
1234 soltantoo sulla base del valore dell'altro.
1235
1236 Il terzo argomento, \param{hints}, deve essere invece un puntatore ad una
1237 struttura \struct{addrinfo} usata per dare dei \textsl{suggerimenti} al
1238 procedimento di risoluzione riguardo al protocollo o del tipo di socket che si
1239 intenderà utilizzare; la funzione infatti permette di effettuare ricerche
1240 generiche sugli indirizzi, usando sia IPv4 che IPv6, e richiedere risoluzioni
1241 sui nomi dei servizi indipendentemente dal protocollo (ad esempio TCP o UDP)
1242 che questi possono utilizzare.
1243
1244 \begin{figure}[!htb]
1245   \footnotesize \centering
1246   \begin{minipage}[c]{15cm}
1247     \includestruct{listati/addrinfo.h}
1248   \end{minipage}
1249   \caption{La struttura \structd{addrinfo} usata nella nuova interfaccia POSIX
1250     per la risoluzione di nomi a dominio e servizi.}
1251   \label{fig:sock_addrinfo_struct}
1252 \end{figure}
1253
1254 La struttura \struct{addrinfo}, la cui definizione\footnote{la definizione è
1255   ripresa direttamente dal file \texttt{netdb.h} in questa struttura viene
1256   dichiarata, la pagina di manuale riporta \type{size\_t} come tipo di dato
1257   per il campo \var{ai\_addrlen}, qui viene usata quanto previsto dallo
1258   standard POSIX, in cui viene utilizzato \type{socklen\_t}; i due tipi di
1259   dati sono comunque equivalenti.} è riportata in
1260 fig.~\ref{fig:sock_addrinfo_struct} viene usata sia in ingresso, per passare
1261 dei valori di controllo alla funzione, che in uscita, per ricevere i
1262 risultati. Il primo campo, \var{ai\_flags}, è una maschera binaria di bit che
1263 permettono di controllare le varie modalità di risoluzione degli indirizzi,
1264 che viene usato soltanto in ingresso. I tre campi successivi \var{ai\_family},
1265 \var{ai\_socktype}, e \var{ai\_protocol} contengono rispettivamente la
1266 famiglia di indirizzi, il tipo di socket e il protocollo, in ingresso vengono
1267 usati per impostare una selezione (impostandone il valore nella struttura
1268 puntata da \param{hints}), mentre in uscita indicano il tipo di risultato
1269 contenuto nella struttura. 
1270
1271 Tutti i campi seguenti vengono usati soltanto in uscita; il campo
1272 \var{ai\_addrlen} indica la dimensione della struttura degli indirizzi
1273 ottenuta come risultato, il cui contenuto sarà memorizzato nella struttura
1274 \struct{sockaddr} posta all'indirizzo puntato dal campo \var{ai\_addr}. Il
1275 campo \var{ai\_canonname} è il puntatore alla stringa contenente il nome
1276 canonico della macchina, ed infine, quando la funzione restituisce più di un
1277 risultato, \var{ai\_next} è il puntatore alla struttura \struct{addrinfo}
1278 successiva della lista.
1279
1280 Ovviamente non è necessario dare dei suggerimenti in ingresso, ed usando
1281 \const{NULL} come valore per l'argomento \param{hints} si possono compiere
1282 ricerche generiche.  Se però si specifica un valore non nullo questo deve
1283 puntare ad una struttura \struct{addrinfo} precedentemente allocata nella
1284 quale siano stati opportunamente impostati i valori dei campi
1285 \var{ai\_family}, \var{ai\_socktype}, \var{ai\_protocol} ed \var{ai\_flags}.
1286
1287 I due campi \var{ai\_family} e \var{ai\_socktype} prendono gli stessi valori
1288 degli analoghi argomenti della funzione \func{socket}; in particolare per
1289 \var{ai\_family} si possono usare i valori di tab.~\ref{tab:net_pf_names} ma
1290 sono presi in considerazione solo \const{PF\_INET} e \const{PF\_INET6}, mentre
1291 se non si vuole specificare questo nessuna famiglia di indirizzi si può usare
1292 il valore \const{PF\_UNSPEC}.  Allo stesso modo per \var{ai\_socktype} si
1293 possono usare i valori illustrati sez.~\ref{sec:sock_type} per indicare per
1294 quale tipo di socket si vuole risolvere il servizio indicato, anche se i soli
1295 significativi sono \const{SOCK\_STREAM} e \const{SOCK\_DGRAM}; in questo caso,
1296 se non si vuole effettuare nessuna risoluzione specifica, si potrà usare un
1297 valore nullo.
1298
1299 Il campo \var{ai\_protocol} permette invece di effettuare la selezione dei
1300 risultati per il nome del servizio usando il numero identificativo del
1301 rispettivo protocollo di trasporto (i cui valori possibili sono riportati in
1302 \file{/etc/protocols}); di nuovo i due soli valori utilizzabili sono quelli
1303 relativi a UDP e TCP, o il valore nullo che indica di ignorare questo campo
1304 nella selezione.
1305
1306 Infine l'ultimo campo è \var{ai\_flags}; che deve essere impostato come una
1307 maschera binaria; i bit di questa variabile infatti vengono usati per dare
1308 delle indicazioni sul tipo di risoluzione voluta, ed hanno valori analoghi a
1309 quelli visti in sez.~\ref{sec:sock_name_services} per \func{getipnodebyname};
1310 il valore di \var{ai\_flags} può essere impostata con un OR aritmetico delle
1311 costanti di tab.~\ref{tab:ai_flags_values}, ciascuna delle quali identifica un
1312 bit della maschera.
1313
1314 \begin{table}[!htb]
1315   \centering
1316   \footnotesize
1317   \begin{tabular}[c]{|l|p{10cm}|}
1318     \hline
1319     \textbf{Costante} & \textbf{Significato} \\
1320     \hline
1321     \hline
1322     \const{AI\_PASSIVE}    & viene utilizzato per ottenere un indirizzo in
1323                              formato adatto per una successiva chiamata a
1324                              \func{bind}. Se specificato quando si è usato 
1325                              \const{NULL} come valore per \param{node} gli
1326                              indirizzi restituiti saranno inizializzati al
1327                              valore generico (\const{INADDR\_ANY} per IPv4 e
1328                              \const{IN6ADDR\_ANY\_INIT} per IPv6), altrimenti
1329                              verrà usato l'indirizzo dell'interfaccia di
1330                              \textit{loopback}. Se invece non è impostato gli
1331                              indirizzi verrano restituiti in formato adatto ad
1332                              una chiamata a \func{connect} o \func{sendto}.\\
1333     \const{AI\_CANONNAME}  & richiede la restituzione del nome canonico della
1334                              macchina, che verrà salvato in una stringa il cui
1335                              indirizzo sarà restituito nel campo
1336                              \var{ai\_canonname} della prima struttura
1337                              \struct{addrinfo} dei risultati. Se il nome
1338                              canonico non è disponibile al suo posto
1339                              viene restituita una copia di \param{node}. \\ 
1340     \const{AI\_NUMERICHOST}& se impostato il nome della macchina specificato
1341                              con \param{node} deve essere espresso in forma
1342                              numerica, altrimenti sarà restituito un errore
1343                              \const{EAI\_NONAME} (vedi
1344                              tab.~\ref{tab:addrinfo_error_code}), in questo
1345                              modo si evita ogni chiamata alle funzioni di
1346                              risoluzione.\\ 
1347     \const{AI\_V4MAPPED}   & stesso significato dell'analoga di
1348                              tab.~\ref{tab:sock_getipnodebyname_flags}.\\  
1349     \const{AI\_ALL}        & stesso significato dell'analoga di
1350                              tab.~\ref{tab:sock_getipnodebyname_flags}.\\ 
1351     \const{AI\_ADDRCONFIG} & stesso significato dell'analoga di
1352                              tab.~\ref{tab:sock_getipnodebyname_flags}.\\ 
1353     \hline
1354   \end{tabular}
1355   \caption{Costanti associate ai bit del campo \var{ai\_flags} della struttura 
1356     \struct{addrinfo}.} 
1357   \label{tab:ai_flags_values}
1358 \end{table}
1359
1360 Come ultimo argomento di \func{getaddrinfo} deve essere passato un puntatore
1361 ad una variabile (di tipo puntatore ad una struttura \struct{addrinfo}) che
1362 verrà utilizzata dalla funzione per restituire (come \textit{value result
1363   argument}) i propri risultati. La funzione infatti è rientrante, ed alloca
1364 autonomamente tutta la memoria necessaria in cui verranno riportati i
1365 risultati della risoluzione.  La funzione restituisce in \param{res} il
1366 puntatore alla prima di una \textit{linked list} di strutture di tipo
1367 \struct{addrinfo} contenenti tutte le informazioni ottenute.
1368
1369 La funzione restituisce un valore nullo in caso di successo, o un codice in
1370 caso di errore. I valori usati come codice di errore sono riportati in
1371 tab.~\ref{tab:addrinfo_error_code}; dato che la funzione utilizza altre
1372 funzioni e chiamate al sistema per ottenere il suo risultato in generale il
1373 valore di \var{errno} non è significativo, eccetto il caso in cui si sia
1374 ricevuto un errore di \const{EAI\_SYSTEM}, nel qual caso l'errore
1375 corrispondente è riportato tramite \var{errno}.
1376
1377 \begin{table}[!htb]
1378   \centering
1379   \footnotesize
1380   \begin{tabular}[c]{|l|p{10cm}|}
1381     \hline
1382     \textbf{Costante} & \textbf{Significato} \\
1383     \hline
1384     \hline
1385     \const{EAI\_FAMILY}  & la famiglia di indirizzi richiesta non è
1386                            supportata. \\ 
1387     \const{EAI\_SOCKTYPE}& il tipo di socket richiesto non è supportato. \\
1388     \const{EAI\_BADFLAGS}& il campo \var{ai\_flags} contiene dei valori non
1389                            validi. \\
1390     \const{EAI\_NONAME}  & il nome a dominio o il servizio non sono noti,
1391                            viene usato questo errore anche quando si specifica
1392                            il valore \const{NULL} per entrambi gli argomenti
1393                            \param{node} e \param{service}. \\
1394     \const{EAI\_SERVICE} & il servizio richiesto non è disponibile per il tipo
1395                            di socket richiesto, anche se può esistere per
1396                            altri tipi di socket. \\
1397     \const{EAI\_ADDRFAMILY}& la rete richiesta non ha nessun indirizzo di rete
1398                            per la famiglia di indirizzi specificata. \\
1399     \const{EAI\_NODATA}  & la . \\
1400     \const{EAI\_MEMORY}  & è stato impossibile allocare la memoria necessaria
1401                            alle operazioni. \\
1402     \const{EAI\_FAIL}    & il DNS ha restituito un errore di risoluzione  
1403                            permanente. \\
1404     \const{EAI\_AGAIN}   & il DNS ha restituito un errore di risoluzione  
1405                            temporaneo, si può ritentare in seguito. \\
1406     \const{EAI\_SYSTEM}  & c'è stato un errore di sistema, si può controllare
1407                            \var{errno} per i dettagli. \\
1408 %    \hline
1409 % estensioni GNU, trovarne la documentazione
1410 %    \const{EAI\_INPROGRESS}& richiesta in corso. \\
1411 %    \const{EAI\_CANCELED}& la richiesta è stata cancellata.\\
1412 %    \const{EAI\_NOTCANCELED}& la richiesta non è stata cancellata. \\
1413 %    \const{EAI\_ALLDONE} & tutte le richieste sono complete. \\
1414 %    \const{EAI\_INTR}    & richiesta interrotta. \\
1415     \hline
1416   \end{tabular}
1417   \caption{Costanti associate ai valori dei codici di errore della funzione
1418     \func{getaddrinfo}.} 
1419   \label{tab:addrinfo_error_code}
1420 \end{table}
1421
1422 Come per i codici di errore di \func{gethostbyname} anche in questo caso è
1423 fornita una apposita funzione, analoga di \func{strerror}, che consente di
1424 utilizzarli direttamente per stampare a video un messaggio esplicativo; la
1425 funzione è \func{gai\_strerror} ed il suo prototipo è:
1426 \begin{functions}
1427   \headdecl{netdb.h} 
1428
1429   \funcdecl{const char *gai\_strerror(int errcode)}
1430
1431   Fornisce il messaggio corrispondente ad un errore di \func{getaddrinfo}.
1432
1433   \bodydesc{La funzione restituisce il puntatore alla stringa contenente il
1434     messaggio di errore.}
1435 \end{functions}
1436
1437 La funzione restituisce un puntatore alla stringa contenente il messaggio
1438 corrispondente dal codice di errore \param{errcode} ottenuto come valore di
1439 ritorno di \func{getaddrinfo}.  La stringa è allocata staticamente, ma essendo
1440 costante, ed accessibile in sola lettura, questo non comporta nessun problema
1441 di rientranza della funzione.
1442
1443 Dato che ad un certo nome a dominio possono corrispondere più indirizzi IP
1444 (sia IPv4 che IPv6), e che un certo servizio può essere fornito su protocolli
1445 e tipi di socket diversi, in generale, a meno di non aver eseguito una
1446 selezione specifica attraverso l'uso di \param{hints}, si otterrà una diversa
1447 struttura \struct{addrinfo} per ciascuna possibilità.  Ad esempio se si
1448 richiede la risoluzione del servizio \textit{echo} si avrà come risposta la
1449 lista illustrata in fig.~\ref{fig:sock_addrinfo_list}.
1450
1451 \begin{figure}[!htb]
1452   \centering
1453   \includegraphics[width=10cm]{img/addrinfo_list}
1454   \caption{La \textit{linked list} delle strutture \struct{addrinfo}
1455     restituite da \func{getaddrinfo}.}
1456   \label{fig:sock_addrinfo_list}
1457 \end{figure}
1458
1459 Come primo esempio di uso di \func{getaddrinfo} vediamo un programma
1460 elementare di interrogazione del resolver, basato questa funzione, il cui
1461 corpo principale è riportato in fig.. Il codice
1462 del programma è nel file \texttt{mygetaddr.c}, dei sorgenti allegati alla
1463 guida.
1464
1465 \begin{figure}[!htb]
1466   \footnotesize \centering
1467   \begin{minipage}[c]{15cm}
1468     \includecodesample{listati/mygetaddr.c}
1469   \end{minipage}
1470   \normalsize
1471   \caption{Esempio di codice per la risoluzione di un indirizzo.}
1472   \label{fig:mygethost_example}
1473 \end{figure}
1474
1475
1476
1477 Una volta estratti i risultati dalla \textit{linked list} puntata da
1478 \param{res} si dovrà avere cura di disallocare opportunamente tutta la
1479 memoria, per questo viene fornita l'apposita funzione \funcd{freeaddrinfo}, il
1480 cui prototipo è:
1481 \begin{functions}
1482   \headdecl{netdb.h} 
1483
1484   \funcdecl{void freeaddrinfo(struct addrinfo *res)}
1485
1486   Libera la memoria allocata da una precedente chiamata a \func{getaddrinfo}.
1487
1488   \bodydesc{La funzione non restituisce nessun codice di errore.}
1489 \end{functions}
1490
1491 La funzione prende come unico argomento il puntatore \param{res}, ottenuto da
1492 una precedente chiamata a \func{getaddrinfo}, e scandisce la lista delle
1493 strutture per liberare tutta la memoria allocata. Dato che la funzione non ha
1494 valori di ritorno deve essere posta molta cura nel passare un valore valido
1495 per \param{res}.
1496
1497
1498
1499
1500 \section{Le opzioni dei socket}
1501 \label{sec:TCP_sock_options}
1502
1503 Finora abbiamo trattato i socket nel loro comportamento più comune, è però
1504 possibile attivare alcune modalità diverse di funzionamento degli stessi
1505
1506 Dato che la maggior parte delle opzioni dei socket sono relative ai socket
1507 TCP, ed hanno poi significato analogo quando usate con altri socket, abbiamo
1508 preferito trattare l'argomento in generale in questa sezione piuttosto che nel
1509 capitolo dedicato alla trattazione generica dei socket.
1510
1511 \section{Altre funzioni di controllo}
1512 \label{sec:TCP_sock_ctrl}
1513
1514
1515
1516
1517
1518 %%% Local Variables: 
1519 %%% mode: latex
1520 %%% TeX-master: "gapil"
1521 %%% End: